Gestión de beneficiarios

Un beneficiario (payee) es el destinatario de los fondos que quieres dispersar. Antes de poder asociarle una instrucción de dispersión, el beneficiario debe pasar por una validación automática de cuenta.

Agregar API Keys y la versión de API

Necesitas tu API Key Privada. Puedes encontrarla en Panel en el módulo de Desarrolladores. Si requieres más información consulta API Keys — Testing.

Todas las llamadas requieren el header Accept: application/vnd.conekta-v2.3.0+json y tu API Key como Bearer token.

🚧

Sandbox vs. producción

Los ejemplos de esta página usan una API Key de prueba (key_ZLy4...). Usa una API Key de producción solo cuando estés listo para dispersar dinero real — ver API Keys — Production.

Crear un beneficiario

curl --request POST \
  --url https://api.conekta.io/payouts/payees \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: application/json' \
  --data '{
    "alias": "proveedor-norte",
    "name":  "Juan Pérez García",
    "clabe": "012180XXXXXXXXXXXX",
    "rfc":   "PEPJ800101AB1",
    "email": "[email protected]",
    "max_amount_limit": 2000000
  }'

Parámetros:

Respuesta 201 Created:

{
  "id": "payee_xxxxxx",
  "object": "external_payee",
  "created_at": 1716739200,
  "updated_at": 1716739200,
  "name": "Juan Pérez García",
  "alias": "proveedor-norte",
  "clabe": "012180XXXXXXXXXXXX",
  "bank_code": "012",
  "rfc": "PEPJ800101AB1",
  "email": "[email protected]",
  "validation_status": "pending_validation",
  "livemode": false,
  "max_amount_limit": 2000000
}

❗

Nota de seguridad

La respuesta real de la API incluye la CLABE completa — Conekta la necesita para operar el SPEI. Este ejemplo la enmascara solo para esta documentación pública; no la registres en logs ni la muestres en interfaces de cliente sin enmascarar.

🚧

Validación asíncrona

La respuesta se recibe antes de que termine la validación de la cuenta. El beneficiario nace en pending_validation y cambia de estado automáticamente al confirmarse (normalmente en menos de dos minutos). Sólo un beneficiario en validated_active puede recibir pagos.

⚠️

max_amount_limit va en centavos, como entero

Igual que el amount de una instrucción de dispersión, max_amount_limit se manda y se recibe como número entero en centavos MXN (2000000 = $20,000.00) — nunca como string ni con decimales. Un valor que no sea entero responde 422 invalid_max_amount_limit_format.

Errores:

Cargar beneficiarios en lote

Si necesitas dar de alta muchos beneficiarios a la vez, puedes subir un archivo CSV. Cada fila se procesa de forma asíncrona.

curl --request POST \
  --url https://api.conekta.io/payouts/payees/bulk \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: multipart/form-data' \
  --form '[email protected]'

Formato del CSV (el archivo debe incluir las columnas name, alias, clabe, rfc y max_amount_limit — si falta alguna, se rechaza el archivo completo con missing_columns; email es la única columna opcional. El valor de rfc sí puede venir vacío por fila, igual que es opcional en el POST individual; max_amount_limit necesita valor en cada fila):

name,alias,clabe,rfc,email,max_amount_limit
Juan Pérez García,proveedor-norte,012180XXXXXXXXXXXX,PEPJ800101AB1,[email protected],2000000
María López Ruiz,proveedor-sur,012180XXXXXXXXXXXX,,,3000000

El archivo real contiene la CLABE completa de cada beneficiario — trátalo como dato sensible: transmítelo por HTTPS (ya obligatorio en la API), no lo dejes en almacenamiento compartido sin cifrar, y bórralo de tu servidor una vez confirmado el enqueued. Una fila con max_amount_limit en blanco se rechaza igual que un alta individual sin el campo — aparece en errors con el motivo correspondiente, no se encola.

Respuesta 202 Accepted:

{ "enqueued": 2, "errors": [], "summary": {} }

Si alguna fila no pudo encolarse, se incluye en errors con el motivo y un code clasificable, y summary agrupa el conteo de errores por code:

{
  "enqueued": 1,
  "errors": [
    { "line": 2, "alias": "proveedor-sur", "error": "clabe has already been taken", "code": "clabe_already_registered" }
  ],
  "summary": { "clabe_already_registered": 1 }
}

summary solo trae el conteo por code — el texto de un resumen tipo "2 de 10 no se crearon porque..." lo arma tu integración a partir de ese conteo, no viaja armado desde la API.

Listar beneficiarios

curl --request GET \
  --url 'https://api.conekta.io/payouts/payees?validation_status=validated_active&limit=20' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB'

Parámetros de consulta (opcionales):

Respuesta 200 OK:

{
  "data": [
    {
      "id": "payee_xxxxxx",
      "object": "external_payee",
      "name": "Juan Pérez García",
      "alias": "proveedor-norte",
      "clabe": "012180XXXXXXXXXXXX",
      "bank_code": "012",
      "rfc": "PEPJ800101AB1",
      "email": "[email protected]",
      "validation_status": "validated_active",
      "livemode": false
    }
  ],
  "pagination": {
    "pageIndex": 1,
    "totalPages": 3,
    "totalItems": 42,
    "itemsPerPage": 20,
    "hasPreviousPage": false,
    "hasNextPage": true
  }
}

Resumen de estados

Útil para mostrar en un dashboard cuántos beneficiarios tienes en cada estado.

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

{
  "validated_active":   12,
  "pending_validation":  8,
  "validated_inactive":  6,
  "rejected":            4
}

Obtener un beneficiario

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

Si el beneficiario está rejected, la respuesta incluye validation_rejection_reason con el motivo del rechazo.

Editar o activar/desactivar un beneficiario

Un mismo PATCH soporta tres operaciones independientes, que puedes combinar en el mismo request:

Editar metadata y cambiar estado no disparan una nueva validación de cuenta — reintentar validación sí, a propósito.

curl --request PATCH \
  --url https://api.conekta.io/payouts/payees/PAYEE_ID \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: application/json' \
  --data '{ "alias": "proveedor-norte-v2", "email": "[email protected]" }'

Parámetros (todos opcionales):

📘

Advertencia no bloqueante al bajar el límite

Si el nuevo max_amount_limit queda por debajo del amount de una instrucción de dispersión activa hacia ese beneficiario, la respuesta 200 incluye warnings:

JSON

{ "warnings": [{ "code": "active_rule_amount_exceeds_new_limit", "rule_id": "6a188111ff51790001e279fb", "rule_amount": 50000 }] }

Es solo informativo — el límite se guarda igual. Esa instrucción quedará skipped en su próxima ejecución hasta que ajustes el límite o el monto de la regla — ver Límite máximo por beneficiario.

📘

Desactivar un beneficiario

Un beneficiario validated_inactive deja de recibir pagos automáticamente: sus instrucciones de dispersión siguen existiendo pero se omiten en el proceso nocturno. Es la forma recomendada de pausar pagos a alguien sin perder la configuración.

📘

Editar un beneficiario pending_validation o rejected

La restricción de estado solo aplica al cambio de validation_status. Puedes actualizar alias, rfc o email de un beneficiario sin importar en qué estado esté — incluido uno que todavía está en validación o que fue rechazado.

Errores:

Reintentar la validación de un beneficiario rechazado

Un beneficiario rejected (CLABE mala o name que no coincide con el titular de la cuenta) antes no tenía forma de corregirse — la única salida era eliminarlo y crear uno nuevo. Un PATCH con clabe y/o name sobre un beneficiario rejected lo regresa a pending_validation y lo vuelve a someter a validación desde cero.

curl --request PATCH \
  --url https://api.conekta.io/payouts/payees/PAYEE_ID \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_ZLy4TfHN2wM9pXqRkD8jV3sB' \
  --header 'Content-Type: application/json' \
  --data '{ "clabe": "012180XXXXXXXXXXXX" }'

Respuesta 200 OK: el beneficiario con validation_status: "pending_validation" — sigue el mismo ciclo que un alta nueva, incluido el webhook payee.payout_method.updated cuando termine.

Errores:

📘

Solo se re-somete si el valor realmente cambia

Si envías el mismo clabe/name que ya tenía, no se dispara una nueva validación. Y si la CLABE nueva ya está registrada en otro beneficiario tuyo, el PATCH responde 422 (clabe_already_registered) sin volver a someter nada a validación.

Eliminar un beneficiario

Elimina (soft delete) al beneficiario. Funciona en cualquier estado, salvo que tenga instrucciones de dispersión activas.

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

Errores:

Un beneficiario rejected no admite activarse (no puedes llevarlo a validated_active/validated_inactive vía validation_status), pero sí puedes editar su alias/rfc/email, o eliminarlo. Al eliminarlo, su alias queda liberado para que puedas registrar uno nuevo con el mismo identificador.

Related

• Resumen — Dispersiones a terceros vía SPEI — visión general del flujo completo.
• Tipos de dispersión — cómo asociar una instrucción de dispersión a un beneficiario ya validado.
• Seguimiento de dispersiones — cómo consultar el historial de pagos de un beneficiario.
• API Keys — Testing — cómo obtener tu llave de prueba.