Tipos de dispersión

Una instrucción de dispersión (el objeto payout_rule en la API) le dice a Conekta cuánto pagarle a un beneficiario y con qué periodicidad. El beneficiario debe estar validated_active para poder asociarle una.

Tipos de dispersión

Todas las instrucciones de dispersión comparten los mismos campos base (payee_id, amount, priority, name, concept, external_reference) y agregan campos propios según el tipo.

Crear una instrucción de dispersión

curl --request POST \
  --url https://api.conekta.io/payout_rules \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: application/json' \
  --data '{
    "rule_type": "one_time",
    "payee_id": "payee_xxx",
    "amount": "100.00",
    "priority": 1,
    "name": "Liquidación proveedor",
    "concept": "Pago factura mayo"
  }'

Parámetros comunes:

Parámetros según rule_type:

Ejemplos

Pago puntual (próximo proceso nocturno):

{ "rule_type": "one_time", "payee_id": "payee_xxx", "amount": "100.00", "name": "Liquidación proveedor" }

Pago en una fecha específica:

{ "rule_type": "scheduled", "payee_id": "payee_xxx", "amount": "500.00", "scheduled_date": "2026-06-15", "name": "Bono anual" }

Nómina mensual, día 15:

{ "rule_type": "recurrent", "payee_id": "payee_xxx", "amount": "1500.00", "frequency": "monthly", "recurrence_day": [15], "start_date": "2026-06-01", "name": "Nómina mensual" }

Renta el último día de cada mes:

{ "rule_type": "recurrent", "payee_id": "payee_xxx", "amount": "1500.00", "frequency": "monthly", "last_day_of_month": true, "name": "Renta fin de mes" }

Nómina quincenal real (día 15 y último día del mes):

{ "rule_type": "recurrent", "payee_id": "payee_xxx", "amount": "2000.00", "frequency": "monthly", "recurrence_day": [15], "last_day_of_month": true, "name": "Nómina quincenal" }

Pago semanal (lunes, miércoles y viernes):

{ "rule_type": "recurrent", "payee_id": "payee_xxx", "amount": "800.00", "frequency": "weekly", "recurrence_day": [1,3,5], "name": "Servicios L/M/V" }

Pago puntual con referencia propia para reconciliación:

{ "rule_type": "one_time", "payee_id": "payee_xxx", "amount": "100.00", "name": "Liquidación proveedor", "external_reference": "1234567" }

🚧

external_reference en instrucciones recurrent

Cada ejecución de una instrucción recurrent genera una dispersión distinta, pero si defines external_reference en la instrucción, todas sus ejecuciones lo reenvían igual (a diferencia del valor interno por default, que es único por dispersión). Aún no está confirmado con el banco si reenviar la misma referencia en ejecuciones distintas tiene algún efecto (deduplicación, límites). Si vas a usar external_reference en una instrucción recurrent, valida el comportamiento en pruebas antes de habilitarlo en producción.

Respuesta 201 Created:

{
  "id": "6a188111ff51790001e279fb",
  "object": "payout_rule",
  "rule_type": "one_time",
  "payee_id": "payee_317roDjGQMta9DYVo",
  "amount": "100.0",
  "priority": 1,
  "status": "scheduled",
  "name": "Liquidación proveedor",
  "concept": "Pago factura mayo",
  "created_at": 1779990801,
  "updated_at": 1779990801
}

El status inicial es "scheduled" para instrucciones one_time y scheduled, y "active" para instrucciones recurrent.

Errores:

Listar instrucciones de dispersión

# Todas las instrucciones del negocio
curl --request GET \
  --url https://api.conekta.io/payout_rules \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

# Solo las instrucciones de un beneficiario
curl --request GET \
  --url 'https://api.conekta.io/payout_rules?payee_id=PAYEE_ID' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

El resultado viene ordenado por priority descendente y luego por antigüedad. Este es el orden de listado — no necesariamente el orden en que se ejecutan las instrucciones cada noche (ver más abajo).

Obtener una instrucción de dispersión

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

Actualizar una instrucción de dispersión

Puedes actualizar amount, priority, payee_id, name, concept, external_reference y los campos propios del tipo (scheduled_date, frequency, recurrence_day, last_day_of_month, start_date, end_date). El rule_type no se puede cambiar una vez creada la instrucción.

curl --request PATCH \
  --url https://api.conekta.io/payout_rules/RULE_ID \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: application/json' \
  --data '{ "amount": "200.00", "priority": 3 }'

Eliminar una instrucción de dispersión

curl --request DELETE \
  --url https://api.conekta.io/payout_rules/RULE_ID \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Respuesta 200 OK:

{ "id": "6a188111ff51790001e279fb", "object": "payout_rule", "rule_type": "one_time", "deleted": true }

🚧

Restricción para instrucciones one_time

Una instrucción one_time solo puede eliminarse mientras sigue en estado scheduled (aún no se ejecutó). Si ya se ejecutó (completed) o falló (failed), el endpoint devuelve 422. Las instrucciones scheduled y recurrent no tienen esta restricción.

Cómo se prioriza la ejecución

📘

priority no determina este orden

El campo priority solo afecta el orden en que listas tus instrucciones de dispersión — no el orden en que se ejecutan cada noche. Si necesitas garantizar que un pago salga antes que otro cuando el saldo no alcanza para todos, usa el criterio real descrito abajo (tipo de dispersión y monto), no priority.

Cada noche, Conekta evalúa las instrucciones que aplican para ese día en este orden:

1. Instrucciones scheduled, luego recurrent, luego one_time — en ese orden de tipo, no mezcladas entre sí.
2. Dentro de cada tipo, de menor a mayor monto (amount ascendente) — no por priority.

Si el saldo disponible no alcanza para todas, las instrucciones se van aplicando en ese orden hasta agotar el saldo; las que no entran quedan pendientes por saldo insuficiente y se reintentan automáticamente en cuanto se recibe un fondeo adicional — no es necesario volver a crear la instrucción.

🚧

Orden entre distintos días

Lo anterior describe el orden dentro de una misma corrida nocturna. Una instrucción que quedó pendiente por falta de saldo se recoge en la siguiente corrida por antigüedad (la más antigua primero), sin volver a aplicar la jerarquía por tipo frente a las instrucciones nuevas de ese día — por ejemplo, una instrucción one_time de ayer que quedó pendiente se procesa antes que una scheduled de hoy, simplemente por ser más vieja. Este comportamiento entre días está bajo revisión de producto y puede cambiar; si tu integración depende del orden exacto entre corridas, confirma con tu Ejecutivo de Cuentas antes de construir sobre él.

Related

• Resumen — Dispersiones a terceros vía SPEI — visión general del flujo completo.
• Gestión de beneficiarios — cómo dar de alta al beneficiario que necesitas antes de crear una instrucción de dispersión.
• Seguimiento de dispersiones — cómo ver si una instrucción ya se ejecutó y con qué resultado.