Guía de Integración: SPEI Out (Payouts) en OrkestaPay

Audiencia: Desarrolladores que integran envíos de pago SPEI desde su plataforma hacia cuentas bancarias de terceros usando la API de OrkestaPay.

Descripción general

Un payout SPEI (también llamado SPEI out) es una transferencia bancaria saliente desde tu cuenta OrkestaPay hacia la cuenta CLABE de un beneficiario registrado.

El flujo completo consta de 3 pasos:

1. Autenticación  →  2. Registrar beneficiario  →  3. Crear payout

Cada paso requiere el resultado del anterior: el token de autenticación se usa en todas las llamadas, y el beneficiary_id obtenido en el paso 2 es requerido en el paso 3.

Prerequisitos

• Credenciales de acceso al API de OrkestaPay (Client ID y Client Secret).
• Acceso al entorno sandbox: https://api.sand.orkestapay.com
• CLABE de 18 dígitos válida del beneficiario destino.

⚠️

Todos los ejemplos de esta guía apuntan al entorno sandbox. Para producción, sustituye el dominio por el que OrkestaPay te indique.

Paso 1 — Autenticación

Antes de llamar a cualquier servicio, debes obtener un token de acceso (Bearer Token).

Consulta el proceso detallado en la documentación oficial:
🔗 https://docs.orkestapay.com/docs/autenticación

Una vez autenticado, recibirás un access_token que deberás incluir en el header Authorization: Bearer <TOKEN> de todas las llamadas siguientes.

💡

Tip: Los tokens tienen tiempo de expiración. Implementa lógica de refresco automático o verifica la vigencia antes de cada llamada para evitar errores 401 Unauthorized.

Paso 2 — Registrar beneficiario

Un beneficiario representa la cuenta bancaria destino a donde se enviarán los fondos. Debes registrarlo una sola vez; después puedes reutilizar su beneficiary_id para múltiples payouts.

Endpoint

POST https://api.sand.orkestapay.com/v1/payouts/beneficiaries

Headers requeridos

Body de la petición

{
  "holder_name": "Gustavo Lopez Diaz",
  "rfc": "VIRO940914D34",
  "alias": "Cuenta de ventas",
  "payment_account": {
    "clabe": "002445123415512335",
    "type": "BANKING_CLABE"
  }
}

Ejemplo cURL

curl --location 'https://api.sand.orkestapay.com/v1/payouts/beneficiaries' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "holder_name": "Gustavo Lopez Diaz",
    "rfc": "VIRO940914D34",
    "alias": "Cuenta de ventas",
    "payment_account": {
      "clabe": "002445123415512335",
      "type": "BANKING_CLABE"
    }
  }'

Respuesta exitosa (200 OK)

{
  "beneficiary_id": "1940751e-946b-44f5-9063-d73642fd6308",
  "holder_name": "Gustavo Lopez Diaz",
  "rfc": "VIRO940914D34",
  "alias": "Cuenta de ventas",
  "payment_account": {
    "type": "BANKING_CLABE",
    "clabe": "719452345234523452",
    "account_number": "4523452345",
    "bank_name": "CAME"
  },
  "active": true,
  "created_at": "1782226445462",
  "last_update": "1782226445462"
}

🔑

Importante: Guarda el campo beneficiary_id — lo necesitarás en el siguiente paso. Los campos created_at y last_update son timestamps Unix en milisegundos.

Paso 3 — Crear payout (SPEI out)

Con el beneficiary_id obtenido en el paso anterior, ya puedes enviar la instrucción de transferencia.

Endpoint

POST https://api.sand.orkestapay.com/v1/payouts

Headers requeridos

Body de la petición

{
  "beneficiary_id": "1940751e-946b-44f5-9063-d73642fd6308",
  "amount": 100,
  "currency": "MXN",
  "description": "Pagos por servicios",
  "reference": "2026051"
}

Ejemplo cURL

curl --location 'https://api.sand.orkestapay.com/v1/payouts' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "beneficiary_id": "1940751e-946b-44f5-9063-d73642fd6308",
    "amount": 100,
    "currency": "MXN",
    "description": "Pagos por servicios",
    "reference": "2026051"
  }'

Respuesta exitosa (200 OK)

{
  "payout_id": "b212f57a-56e3-43a5-ab79-79b1bad06dbe",
  "merchant_id": "mch_23dd163e342d4fd5812068f86031df8b",
  "beneficiary_id": "1940751e-946b-44f5-9063-d73642fd6308",
  "beneficiary": {
    "id": "1940751e-946b-44f5-9063-d73642fd6308",
    "holder_name": "Gustavo Lopez Diaz",
    "rfc": "VIRO940914D34",
    "alias": "Cuenta de ventas",
    "payment_account": {
      "type": "BANKING_CLABE",
      "clabe": "719452345234523452",
      "account_number": "4523452345",
      "bank_name": "CAME"
    },
    "active": true,
    "created_at": "1782226445462",
    "last_update": "1782226445462"
  },
  "amount": 100,
  "currency": "MXN",
  "description": "Pagos por servicios",
  "status": "PROCESSING",
  "reference": "2026062",
  "created_at": "1782228159039",
  "last_update": "1782228159039"
}

🔑

Importante: Guarda el payout_id para poder rastrear el estado del pago y correlacionarlo con las notificaciones de webhook.

Estados del payout

El campo status en la respuesta indica en qué etapa se encuentra la transferencia:

Confirmación por Webhook

Una vez que el banco procesa la transferencia, OrkestaPay notifica el resultado a tu sistema mediante un webhook. El evento incluirá el payout_id para que puedas identificar a qué pago corresponde la notificación.

Asegúrate de:

1. Tener configurada una URL de webhook en tu panel de OrkestaPay.
2. Validar la autenticidad de las notificaciones recibidas.
3. Responder con un HTTP 200 para confirmar la recepción.

Resumen del flujo

┌─────────────────────────────────────────────────────────────┐
│                    Flujo SPEI Out                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. POST /auth        → access_token                        │
│         │                                                   │
│         ▼                                                   │
│  2. POST /payouts/beneficiaries  → beneficiary_id           │
│         │                                                   │
│         ▼                                                   │
│  3. POST /payouts     → payout_id  (status: PROCESSING)     │
│         │                                                   │
│         ▼                                                   │
│  4. Webhook recibido  → status final del pago               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Buenas prácticas

• Persiste los IDs relevantes: Guarda beneficiary_id y payout_id en tu base de datos para trazabilidad y reconciliación.
• Reutiliza beneficiarios: Si envías pagos frecuentes al mismo destino, registra el beneficiario una sola vez y reutiliza su beneficiary_id.
• Referencias únicas: Usa una reference diferente por pago para facilitar la conciliación bancaria.
• Manejo de errores: Implementa reintentos con backoff exponencial para errores 5xx. Para errores 4xx, revisa y corrige el request antes de reintentar.
• Ambientes separados: Usa variables de entorno para manejar las URLs y credenciales de sandbox vs. producción.

Referencias

• 📘 Documentación del API (crear payout): https://docs.orkestapay.com/reference/create-payout
• 🔐 Guía de autenticación: https://docs.orkestapay.com/docs/autenticación