1. Connect API
Payday Payments
  • API Transaccional (API KEY)
    • Crear Clabe
      POST
    • Listar Transacciones
      GET
    • Listar Transaccion
      GET
    • Listar Transacciones X CLABE
      GET
    • Crear Payment Intent
      POST
    • Listar Payment Intents
      GET
    • Obtener Payment Intent
      GET
    • Cancelar Payment Intent
      POST
    • Crear webhook
      POST
    • Borrar Webhook
      DELETE
    • Evento - Transaction Income
    • Evento - Payment Receive
    • Consultar Transferencia X TxID
      GET
    • Consultar Detalle Transferencia
      GET
    • Cancelar Transferencia
      POST
  • Connect API
    • Implementacion Connect
    • Crear regla de split
      POST
    • Listar Reglas Split
      GET
    • Obtener regla split por id
      GET
    • Actualizar regla split
      PUT
    • Eliminar regla split
      DELETE
    • Enlazar Connect
      PUT
    • Desactivar Connect
      PUT
    • Crear cuentas conectadas
      POST
    • Listar cuentas conectadas
      GET
    • Obtener cuenta conectada por id
      GET
    • Actualizar cuenta conectada
      PUT
    • Eliminar cuenta conectada
      DELETE
    • Listar Transferencias Manuales
      GET
    • Libera un transfer de hold manual
      POST
  • Partner API (OAuth)
    • Obtener Token
    • Crear Cuenta
    • Configurar Cuenta Bancaria
    • Crear API Key Transaccional
    • Rotar API Key Transaccional
    • Revocar API Key
  1. Connect API

Implementacion Connect

Flujo Connect#

Objetivo#

Este documento describe el flujo completo para operar Connect desde la API Developer:
1.
Crear cuenta conectada.
2.
Crear regla de split.
3.
Crear CLABE con Connect y regla (o enlazar regla y habilitar Connect en un usuario existente).
Resultado esperado:
Si un usuario/CLABE tiene connect_enabled=true y una connect_split_rule_id valida, todos los pagos recibidos en esa CLABE se procesan con la regla Connect asignada.

Alcance#

Este flujo usa rutas bajo /api/developer/* con autenticacion por API key en header Bearer.
Autenticacion esperada:
Donde {{API_KEY_AK}} es la API key (empieza con ak_...).

Pre-requisitos#

1.
API key activa para el tenant.

Paso 1 - Crear cuenta conectada#

Ruta:
POST /api/developer/connected-accounts
Ejemplo:
Respuesta esperada (201):
{
  "_id": "681f10b2f9a4d8a9b9f2a001",
  "tenantId": "tenant_demo",
  "name": "Proveedor Principal",
  "clabe": "646180157000000001",
  "beneficiario": "PROVEEDOR PRINCIPAL SA DE CV",
  "institucion": 40012,
  "rfcCurp": "PPR010101AAA",
  "email": "pagos@proveedor-principal.com",
  "isActive": true,
  "metadata": {},
  "createdAt": "2026-04-18T18:20:10.120Z",
  "updatedAt": "2026-04-18T18:20:10.120Z",
  "__v": 0
}
Notas:
clabe debe tener exactamente 18 digitos.
📌
Crea mas cuentas conectadas si tu regla reparte a varios destinos.

Paso 2 - Crear regla de split#

Ruta:
POST /api/developer/connect/split-rules
Ejemplo (70/20/10):
Respuesta esperada (201):
{
  "_id": "681f1199f9a4d8a9b9f2a010",
  "tenantId": "tenant_demo",
  "name": "Regla 70-20-10",
  "isActive": true,
  "isDefault": false,
  "holdPeriod": "24h",
  "splits": [
    {
      "connectedAccountId": "681f10b2f9a4d8a9b9f2a001",
      "type": "percentage",
      "value": 70,
      "description": "Proveedor principal"
    },
    {
      "connectedAccountId": "681f10c1f9a4d8a9b9f2a002",
      "type": "percentage",
      "value": 20,
      "description": "Comisionista"
    }
  ],
  "platformRetainPercentage": 10,
  "metadata": {
    "version": "v1"
  },
  "createdAt": "2026-04-18T18:30:49.200Z",
  "updatedAt": "2026-04-18T18:30:49.200Z",
  "__v": 0
}
Validaciones importantes:
splits no puede estar vacio.
Si todos los splits son percentage, entonces:
sum(splits.value) + platformRetainPercentage = 100.
Las connectedAccountId deben existir y estar activas.
holdPeriod permitido: 0h, 2h, 24h, 48h, 72h.

Paso 3 - Crear CLABE con Connect y regla#

Hay dos formas validas.

Opcion A: Crear CLABE y enlazar Connect en un solo request#

Ruta:
POST /api/developer/clabe
Ejemplo:
Respuesta esperada:
{
  "success": true,
  "clabe": "646180686066963041",
  "tenantUserId": "681f25f2f9a4d8a9b9f2a200",
  "connect_enabled": true,
  "connect_split_rule_id": "681f1199f9a4d8a9b9f2a010"
}

Opcion B: Crear CLABE primero y enlazar despues#

B.1 Crear CLABE#

B.2 Enlazar Connect por tenantUserId#

Ruta:
PUT /api/developer/clabe/:id/connect
Respuesta esperada:
{
  "success": true,
  "user": {
    "id": "681f25f2f9a4d8a9b9f2a200",
    "name": "Cliente Connect",
    "email": "cliente.connect@example.com",
    "phone": "9999999999",
    "centro_costo": "669",
    "clabe": "646180686066963041",
    "isActive": true,
    "connect_enabled": true,
    "connect_split_rule_id": "681f1199f9a4d8a9b9f2a010",
    "createdAt": "2026-04-18T19:00:00.000Z",
    "updatedAt": "2026-04-18T19:01:00.000Z"
  }
}

Regla de negocio (SPLIT)#

Si el usuario/CLABE queda con:
connect_enabled = true
connect_split_rule_id = <RULE_ID valido>
entonces todos los pagos recibidos en esa CLABE intentan ejecutar Connect con esa regla.

Que pasa cuando entra un pago a la CLABE enlazada#

1.
Llega webhook STP.
2.
Se identifica el usuario por CLABE.
3.
Si connect_enabled=true, se determina la regla de split:
prioridad 1: tenantUser.connect_split_rule_id
prioridad 2: paymentIntent.metadata.connectSplitRuleId
prioridad 3: regla default activa del tenant
4.
Se crean connect_transfers en estado pending con scheduledAt segun holdPeriod.
5.
El connectDispersionWorker toma transfers vencidos y los envia a STP.
6.
El worker crea/actualiza registro en dispersiones, ajusta retiros y aplica rollback financiero en fallo final.

Verificacion operativa (consultas recomendadas)#

1) Ver transacciones recibidas#

2) Ver transfers Connect generados#

3) Ver detalle de transfer#

4) Cancelar transfer pendiente (si aplica)#

Errores comunes y solucion#

1.
Invalid API key:
API key invalida, revocada o mal enviada.
2.
connect_split_rule_id not found or inactive:
La regla no existe en el tenant o esta inactiva.
3.
Connected accounts not found or inactive al crear regla:
Alguna cuenta de splits no existe o no esta activa.
4.
No aparecen transfers:
Usuario no tiene connect_enabled=true.
No hay regla asignada ni default activa.
El pago no entro a la CLABE enlazada.
5.
Transfers en pending por mucho tiempo:
holdPeriod aun no vence.

Checklist rapido de puesta en marcha#

1.
Crear cuentas conectadas.
2.
Crear regla de split activa.
3.
Crear/enlazar CLABE con connect_enabled=true y connect_split_rule_id.
4.
Recibir un pago en esa CLABE.
5.
Verificar transaccion en /api/developer/transactions.
6.
Verificar transfers en /api/developer/connect/transfers.

Endpoints Connect Developer usados en este flujo#

POST /api/developer/connected-accounts
GET /api/developer/connected-accounts
POST /api/developer/connect/split-rules
GET /api/developer/connect/split-rules
POST /api/developer/clabe
PUT /api/developer/clabe/:id/connect
GET /api/developer/transactions
GET /api/developer/connect/transfers
GET /api/developer/connect/transfers/:id
POST /api/developer/connect/transfers/:id/cancel

Nota de recomendacion#

Para un comportamiento deterministico, asigna siempre connect_split_rule_id por usuario/CLABE.
No dependas de fallback a regla default para casos criticos de negocio.
Modificado en 2026-04-21 15:38:20
Anterior
Cancelar Transferencia
Siguiente
Crear regla de split
Built with