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:

Parámetro	Descripción
`tab`	`proximas` (default) — proyecta los próximos 30 días según tus instrucciones activas. `historial` — grupos ya ejecutados. Sin `status` explícito, `historial` muestra los grupos de fechas pasadas en cualquier estado (para que uno atascado en `processing` siga siendo visible) y los de hoy en adelante solo si ya son `completed` o `failed`. Si pasas `status` explícitamente, ese filtro se aplica tal cual, sin este recorte por fecha.
`status`	`upcoming`, `scheduled`, `processing`, `completed`, `failed`. `422` si el valor no es uno de estos cinco. Para `historial`, `upcoming` no aplica y devuelve lista vacía.
`scheduled_from` / `scheduled_to`	Rango de fechas `YYYY-MM-DD`. `422` si la fecha no es parseable.
`page` / `limit`	Paginación. Default `1` / `20`, máximo `100`.

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:

Valor	Significado
`upcoming`	El grupo proyectado más próximo — el siguiente en ejecutarse.
`scheduled`	Grupos proyectados posteriores, o ya creados pero aún no procesados.
`processing`	El fondeo o la dispersión están en curso — incluye el caso en que ninguna instrucción tuvo saldo suficiente ese día: el grupo queda aquí (no en `failed`) esperando un fondeo adicional que lo reactive.
`completed`	Todas las dispersiones del grupo se completaron.
`failed`	Todas las dispersiones del grupo terminaron en falla, sin ninguna recuperable pendiente.

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:

Parámetro	Descripción
`status`	`pending`, `processing`, `completed`, `failed`. Uno o varios separados por coma. `422` si algún valor no es válido.
`rule_type`	`one_time`, `scheduled`, `recurrent`. Uno o varios separados por coma. `422` si algún valor no es válido.
`created_from` / `created_to`	Rango de fechas `YYYY-MM-DD`.
`page` / `limit`	Paginación. Default `1` / `20`, máximo `100`.

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:

Campo	Descripción
`status`	`pending`, `processing`, `completed`, `failed`.
`amount`	Monto en centavos MXN.
`fee_charged`	Comisión cobrada, en centavos MXN.
`executed_at`	Momento en que se envió la instrucción. `null` si aún no se ha ejecutado.
`settled_at`	Momento en que SPEI confirmó la liquidación final. `null` hasta entonces.
`tracking_key`	Clave de rastreo SPEI. Se llena al recibir la confirmación de liquidación — `null` hasta entonces.
`failure_reason`	Motivo de falla, cuando aplica. `null` si no falló.
`rule`	La instrucción de dispersión que la generó. `null` si la instrucción fue eliminada.

Errores:

Código	Motivo
`404 Not Found`	El `external_payout_transaction_xxxxxxxx` no existe, no pertenece al `PAYEE_ID` indicado, o no pertenece a tu negocio.

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:

Evento	Cuándo se dispara
`payout.created`	Al crear la `ExternalPayoutTransaction` — tanto si se va a fondear hoy como si queda pendiente esperando saldo.
`payout.in_transit`	Justo antes de enviar la instrucción a la red SPEI.
`payout.paid_out`	Cuando el banco confirma la liquidación final.
`payout.failed`	Cuando el banco rechaza o revierte la dispersión, o cuando falla por saldo insuficiente u otro error de ejecución.
`payout.retrying`	Cuando una dispersión que había fallado por saldo insuficiente se reintenta tras un fondeo adicional.

Eventos de un beneficiario:

Evento	Cuándo se dispara
`payee.payout_method.created`	Al crear un beneficiario.
`payee.payout_method.updated`	Al editar metadata, cambiar `validation_status`, o cuando termina la validación automática de cuenta (resultado real, no la respuesta inmediata del `POST`).
`payee.payout_method.deleted`	Al eliminar 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ó.

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.

Conceptos

Grupos de dispersión (batches)

Detalle de un grupo

Dispersiones

Todas las dispersiones del negocio

Historial de dispersiones de un beneficiario

Detalle de una dispersión

Notificaciones

Importante

Related