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": "646180157034084695",
    "rfc":   "PEPJ800101AB1",
    "email": "[email protected]"
  }'

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": "**************4695",
  "bank_code": "646",
  "rfc": "PEPJ800101AB1",
  "email": "[email protected]",
  "validation_status": "pending_validation",
  "livemode": false
}

❗

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.

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 (columnas requeridas: name, alias, clabe; opcionales: rfc, email):

name,alias,clabe,rfc,email
Juan Pérez García,proveedor-norte,646180157034084695,PEPJ800101AB1,[email protected]
María López Ruiz,proveedor-sur,646180157034084712,,

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.

Respuesta 202 Accepted:

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

Si alguna fila no pudo encolarse, se incluye en errors con el motivo:

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

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": "**************4695",
      "bank_code": "646",
      "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 dos operaciones independientes, que puedes combinar en el mismo request:

Ninguna de las dos operaciones dispara una nueva validación de cuenta.

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):

📘

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:

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.