STP Bank API

STP (Sistema de Transferencias y Pagos Interbancarias) es el proveedor bancario de Finalitix. Código de institución: 00000.

Protocolo

HTTP: HTTPS con axios
Autenticación: Firmas RSA-SHA256 (ver Firmas RSA)
Content-Type: application/json

URLs de servicio

Las URLs se obtienen del secreto STP_SECRET_NAME en Secrets Manager, no están hardcodeadas en el código.

Operación	Campo en secreto	Método HTTP
Registrar persona física	`regPersonaFisicaUrl`	PUT
Registrar persona moral	`regPersonaMoralUrl`	PUT
Registrar orden de pago	`registraOrdenUrl`	PUT
Consultar saldo	`consultaSaldoUrl`	POST
Conciliación de órdenes	`conciliacionUrl`	POST

Operaciones iniciadas por Finalitix → STP

Registrar cuenta (persona física)

PUT {regPersonaFisicaUrl}
{
  "empresa": "FINALITIX",
  "cuenta": "64618001000001237",
  "rfcCurp": "PEGJ800101ABC",
  "nombre": "JUAN PEREZ GARCIA",
  "tipoCuenta": 40,
  "firma": "<RSA-SHA256 en Base64>"
}

Respuesta exitosa: { id: 0, descripcion: "cuenta creada" }

Registrar orden de pago

PUT {registraOrdenUrl}
{
  "empresa": "FINALITIX",
  "institucionContraparte": 40002,
  "institucionOperante": 00000,
  "claveRastreo": "FNLTX1234567890",
  "monto": "1500.00",
  "tipoPago": 30,
  "tipoCuentaOrdenante": 40,
  "nombreOrdenante": "MARIA LOPEZ",
  "cuentaOrdenante": "64618001000001237",
  "rfcCurpOrdenante": "LOMM850202XYZ",
  "tipoCuentaBeneficiario": 40,
  "nombreBeneficiario": "EMPRESA DESTINO SA",
  "cuentaBeneficiario": "002180012345678901",
  "rfcCurpBeneficiario": "EDI200101AAA",
  "conceptoPago": "Pago de servicios",
  "referenciaNumerica": 1234567,
  "nombreParticipanteIndirecto": "",
  "cuentaParticipanteIndirecto": "",
  "rfcParticipanteIndirecto": "",
  "firma": "<RSA-SHA256 en Base64>"
}

Respuesta exitosa: { id: 12345678 } (id > 999 indica éxito)

Notificaciones STP → Finalitix (callbacks)

STP envía notificaciones a estos endpoints de la API:

Evento	Endpoint	Descripción
Estado de cuenta	`PUT /stp/v1/account`	Cuenta activada o rechazada
Abono recibido	`POST /stp/v1/transaction`	Transferencia entrante a usuario Finalitix
Estado de orden	`PUT /stp/v1/transaction`	Orden liquidada, cancelada o devuelta

Valores de referencia

Concepto	Valor
Código de institución Finalitix/STP	`00000`
Tipo de cuenta CLABE	`40`
Tipo de pago SPEI	`30`
Moneda	`MXN`
Instrumento monetario	`01`