1. Payout
API
Español
  • Español
  • English
  • Introducción
    • API Kambia
    • Credenciales
    • Autenticación
    • Verificación
      POST
  • Servicios
    • Catálogo de códigos
    • Payout
      • Notificaciones
      • Create payout
        POST
      • Get payout
        GET
    • Débito automático
      • Cómo funciona
      • Modelo de autorización
      • Notificaciones
      • Affiliation
      • Charge
  1. Payout

Create payout

POST
/{{api_version}}/payout/{{merchant_id}}
Descripción
Crea una solicitud de transferencia bancaria
Autenticación
Revisa la sección aquí
Rechazos y duplicados
Un rechazo definitivo responde 4xx con message y error_code: "Invalid bank details" / INVALID_BANK_DETAILS (revisar los datos del titular o de la cuenta) o "Payout rejected" / PAYOUT_REJECTED (rechazo por otro motivo). En ninguno de los dos casos hay salida de dinero.
El message empieza con ese texto fijo y puede seguir con el motivo después de dos puntos ("Invalid bank details: account closed"). Decidan por error_code o por el inicio del texto, nunca comparando el message completo.
Cada desembolso lleva un order_id nuevo y único. Kambia no deduplica por order_id: si reenvían el mismo POST no podemos garantizar que no salga un segundo desembolso real. Ante un timeout o una respuesta perdida no reintenten: consulten el estado.
La consulta de estado es por payout_id, no por order_id, así que guarden el payout_id que devuelve el create. Si reciben error_code PAYOUT_RESULT_UNKNOWN el resultado no está confirmado: no reenvíen, consulten.
Modo demo (notificaciones automáticas)
Para facilitar las pruebas de integración del webhook, la API detecta automáticamente ciertos prefijos en el order_id y envía la notificación correspondiente al payout_webhook del merchant ~500 ms después de crear el payout.
Prefijos reservados
order_id empieza porEstado enviado en el webhook
DEMO_SUCCESSSUCCESS
DEMO_REJECTEDREJECTED
El sufijo es libre: DEMO_SUCCESS_001, DEMO_REJECTED_test, etc.
Comportamiento
La respuesta del create es idéntica a la de un payout normal (status: "PENDING").
El webhook tiene el mismo formato y firma (x-kambia-signature) que una notificación real.
En SUCCESS demo se incluye receipt_url: "https://demo.kambia.app" (enlace de prueba).

Request

Body Params application/jsonRequired

Examples

Responses

🟢201Created
application/json
Bodyapplication/json

🟠400Missing field
🟠400Invalid field
🟠400Invalid bank details
Response Response Example
201 - Created
{
    "status_code": 201,
    "message": "Payout created successfully",
    "payout": {
        "id": "645",
        "country": "PER",
        "amount": 25000,
        "currency": "PEN",
        "order_id": "CU_1767031321",
        "status": "CREATED",
        "created_at": "2026-01-19T21:31:16.475102"
    }
}
Modified at 2026-10-03 01:09:25
Previous
Notificaciones
Next
Get payout
Built with