Seguimiento de dispersiones

Una vez que tienes beneficiarios e instrucciones de dispersión configuradas, puedes consultar en cualquier momento qué se va a pagar, qué ya se pagó y en qué estado está cada dispersión.

Conceptos

• Grupo de dispersión (batch) — todos los pagos que ocurren (o se proyecta que ocurran) en una misma fecha para tu negocio.
• Dispersión — el pago individual a un beneficiario dentro de un grupo.

Grupos de dispersión (batches)

# Próximos 30 días (proyección)
curl --request GET \
  --url 'https://api.conekta.io/payouts/batches?tab=proximas' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

# Historial real
curl --request GET \
  --url 'https://api.conekta.io/payouts/batches?tab=historial' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Parámetros de consulta:

Respuesta 200 OK:

{
  "data": [
    {
      "date": "2026-06-02",
      "status": "upcoming",
      "funding_batch_id": null,
      "beneficiary_count": 3,
      "disbursement_count": 4,
      "total_amount": 2925000,
      "total_fees": 0,
      "is_projection": true
    }
  ],
  "pagination": { "pageIndex": 1, "totalPages": 1, "totalItems": 8, "itemsPerPage": 20, "hasPreviousPage": false, "hasNextPage": false }
}

Valores de status:

total_amount y total_fees están en centavos MXN — a diferencia del amount de una instrucción de dispersión, que se expresa en pesos como string. total_fees refleja la comisión efectivamente cobrada hasta el momento de la consulta — se actualiza a medida que se despachan y cobran las dispersiones del grupo, no es un estimado fijo desde su creación. funding_batch_id es null mientras el grupo sigue siendo una proyección (is_projection: true); se llena una vez que existe un fondeo real para esa fecha.

Detalle de un grupo

curl --request GET \
  --url https://api.conekta.io/payouts/batches/2026-06-02 \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Incluye el arreglo disbursements con cada pago individual del grupo (real o proyectado) y el beneficiario y la instrucción asociados:

{
  "date": "2026-06-02",
  "status": "upcoming",
  "funding_batch_id": null,
  "total_amount": 2925000,
  "total_fees": 0,
  "is_projection": true,
  "disbursements": [
    {
      "id": null,
      "status": "pending",
      "amount": 1250000,
      "fee_charged": 0,
      "is_projection": true,
      "payee": { "id": "payee_abc123", "name": "Mkt Solutions SA", "alias": "mkt-solutions" },
      "rule": { "id": "payout_rule_xyz789", "rule_type": "recurrent", "frequency": "monthly", "name": "Nómina mensual" }
    }
  ]
}

Si la fecha es futura y ninguna instrucción activa proyecta ejecución ese día, la respuesta es 404.

Dispersiones

Todas las dispersiones del negocio

curl --request GET \
  --url 'https://api.conekta.io/payouts/disbursements?status=completed' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Parámetros de consulta:

Cada elemento incluye el beneficiario embebido:

{
  "id": "external_payout_transaction_31A4VsoUJ7ddQ6s9y",
  "status": "completed",
  "amount": 150000,
  "fee_charged": 450,
  "created_at": 1780502641,
  "executed_at": 1780243439,
  "settled_at": 1780243479,
  "tracking_key": "STP1234567890123456",
  "failure_reason": null,
  "rule": { "id": "6a188130ff51790001e27a00", "rule_type": "recurrent", "frequency": "monthly", "name": "Nómina mensual" },
  "payee": { "id": "payee_317roDjGQMta9DYVs", "name": "Juan Pérez García", "alias": "proveedor-norte" }
}

Historial de dispersiones de un beneficiario

curl --request GET \
  --url 'https://api.conekta.io/payouts/payees/PAYEE_ID/disbursements' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Acepta los mismos filtros (status, rule_type, created_from, created_to, page, limit). A diferencia del endpoint anterior, no incluye el objeto payee (ya lo tienes si estás consultando por PAYEE_ID).

Detalle de una dispersión

curl --request GET \
  --url 'https://api.conekta.io/payouts/payees/PAYEE_ID/disbursements/external_payout_transaction_xxxxxxxx' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Campos de una dispersión:

Errores:

Reintentar una dispersión fallida por saldo insuficiente

Una dispersión que falla por saldo insuficiente no se arrastra sola al día siguiente salvo que la instrucción que la generó tenga activo auto_retry_on_insufficient_funds. Tienes tres formas de reintentarla:

Reintento manual — una dispersión:

curl --request POST \
  --url https://api.conekta.io/v1/payouts/instructions/RULE_ID/retry \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Reintento manual — todas las elegibles de hoy:

curl --request POST \
  --url https://api.conekta.io/v1/payouts/instructions/retry \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Solo son elegibles instrucciones con execution_date de hoy y beneficiario validated_active. Ambos responden 422 con instruction_not_eligible si la instrucción no aplica (ya se ejecutó, se canceló, o el beneficiario no está validado), y 429 si excedes el throttle (1 reintento por dispersión cada 60 segundos, 1 reintento masivo por negocio cada 5 minutos).

Reintento automático: activa auto_retry_on_insufficient_funds: true (default false) al crear o editar la instrucción o la regla que la genera. Cada fallo por saldo crea una dispersión nueva para el siguiente día hábil, hasta 5 reintentos — cada recreación dispara payout.retrying.

📘

El reintento manual no consume el tope automático

Puedes seguir reintentando a mano aunque la cadena de reintento automático ya se haya agotado — el contador de 5 días solo cuenta las recreaciones automáticas, no los reintentos que disparas por panel o API.

Notificaciones

Agrega un Webhook a tu cuenta para recibir actualizaciones de estado de tus dispersiones y beneficiarios sin tener que hacer polling.

Eventos de una dispersión:

Eventos de un beneficiario:

Consulta Eventos de Conekta para el catálogo completo y el formato general del payload de cada tipo.

❗

Importante

Verifica siempre la firma de cada notificación antes de actuar sobre ella — ver Verificar firmas de Webhooks. Un webhook de dispersiones sin verificar puede ser falsificado por un tercero para simular que un pago falló o se completó.

Related

• Resumen — Dispersiones a terceros vía SPEI — visión general del flujo completo.
• Gestión de beneficiarios — cómo dar de alta y consultar beneficiarios.
• Tipos de dispersión — cómo configurar qué se paga y cuándo.
• Verificar firmas de Webhooks — obligatorio antes de procesar cualquier notificación.