En esta página
Payouts
Dispersa fondos de tu saldo en iion pay a cuentas bancarias o llaves Bre-B en Colombia, con la misma API Key que usas para cobrar. El payout debita de tu saldo y envía el dinero al beneficiario que indiques.
payout:create) y una clave de idempotencia obligatoria. Contacta a iion pay para habilitar payouts en tu cuenta.
Requisitos
- Payout habilitado para tu comercio — se activa por cuenta; si aún no lo tienes, contacta a iion pay para solicitarlo.
- Permiso
payout:create— tu API Key debe tenerlo habilitado (puedes gestionarlo desde tu panel de negocio una vez el payout esté activo en tu cuenta; no viene por defecto). Las consultas (GET) también exigen el permisopayout:create: listar payouts, consultar uno por id y ver el catálogo de métodos. Una llave que solo tienepayout:readrecibe403. - Saldo suficiente — el payout debita el monto de tu saldo, más la comisión si tu contrato define una. Si no alcanza, se rechaza.
- Clave de idempotencia — envía la cabecera
Idempotency-Keyúnica por cada payout.
Métodos disponibles
El catálogo de métodos es dinámico: consúltalo antes de crear un payout. Devuelve los métodos habilitados con el valor exacto de network a enviar, sus requiredFields, el listado de bancos (banks, con el bankCanonicalId que espera el POST y el indicador isDigitalWallet) y el tope por transacción (limits.maxAmountCop).
/api/v1/payout/methods
Cada elemento de banks tiene esta forma. Nequi, Daviplata y Movii traen isDigitalWallet: true; los demás bancos, false.
{ "bankCanonicalId": "nequi", "name": "Nequi", "isDigitalWallet": true }
Un payout con un método fuera de este catálogo se rechaza con 400 PAYOUT_METHOD_NOT_AVAILABLE. Si el payout está deshabilitado globalmente, la respuesta trae enabled: false y lista vacía.
Rieles de dispersión
Eliges el riel con el campo network. iion pay enruta internamente al proveedor bancario adecuado según el método y el monto — tú no eliges el proveedor.
Riel (network) | Descripción | Campos requeridos |
|---|---|---|
BANK |
Transferencia a cuenta bancaria colombiana. | bankCanonicalId, accountNumber y accountType (obligatorio salvo en billeteras; ver Retiro a una billetera) |
BREB |
Envío por llave Bre-B (instantáneo). | keyValue, keyType |
Crear un payout
Crea una dispersión y devuelve su estado inicial. La cabecera Idempotency-Key es obligatoria.
Ejemplo: envío por llave Bre-B
curl https://api.prod.iionpay.com/api/v1/payout \
--request POST \
--header 'X-Api-Key: TU_API_KEY' \
--header 'X-Api-Secret: TU_API_SECRET' \
--header 'Idempotency-Key: a1b2c3d4-e5f6-7890' \
--header 'Content-Type: application/json' \
--data '{
"amount": 100000,
"recipientName": "María Gómez",
"recipientDocType": "CC",
"recipientDocNumber": "1020304050",
"network": "BREB",
"keyValue": "@mariagomez",
"keyType": "ALPHANUMERIC",
"description": "Pago proveedor #55"
}'
Ejemplo: transferencia a cuenta bancaria
curl https://api.prod.iionpay.com/api/v1/payout \
--request POST \
--header 'X-Api-Key: TU_API_KEY' \
--header 'X-Api-Secret: TU_API_SECRET' \
--header 'Idempotency-Key: 9f8e7d6c-1234-5678' \
--header 'Content-Type: application/json' \
--data '{
"amount": 250000,
"recipientName": "Carlos Ruiz",
"recipientDocType": "CC",
"recipientDocNumber": "9080706050",
"network": "BANK",
"bankCanonicalId": "bancolombia",
"accountType": "SAVINGS",
"accountNumber": "12345678901"
}'
Ejemplo: retiro a una billetera (Nequi, Daviplata, Movii)
Si el banco tiene isDigitalWallet: true, no envíes accountType. El accountNumber es el celular del beneficiario.
- Acepta espacios, guiones, puntos, paréntesis y el prefijo
+57o57. - El resultado debe tener 10 dígitos y empezar por 3 (
^3\d{9}$). - Se guarda y se envía el número normalizado. Por ejemplo,
+57 300-123-4567pasa a3001234567. - Si envías
accountTypea una billetera, se ignora.
curl https://api.prod.iionpay.com/api/v1/payout \
--request POST \
--header 'X-Api-Key: TU_API_KEY' \
--header 'X-Api-Secret: TU_API_SECRET' \
--header 'Idempotency-Key: 5c4b3a29-8765-4321' \
--header 'Content-Type: application/json' \
--data '{
"amount": 80000,
"recipientName": "Ana Torres",
"recipientDocType": "CC",
"recipientDocNumber": "1010101010",
"network": "BANK",
"bankCanonicalId": "nequi",
"accountNumber": "300 123 4567"
}'
Respuesta
Un payout nuevo responde 201 con este formato:
{
"success": true,
"data": {
"success": true,
"payoutId": "clpay123abc456def",
"providerPayoutId": "mm_abc123",
"status": "PENDING",
"amount": 100000,
"feeAmount": "0.00",
"message": "Envío en proceso. María Gómez recibirá los fondos pronto."
}
}
feeAmountllega como texto con dos decimales (por ejemplo"0.00").providerPayoutIdpuede llegar ennullsi el débito de tu saldo aún está en confirmación. En ese casomessagedice que el envío está en proceso. El POST respondestatusPENDING, pero la consulta muestraPENDING_ONCHAINhasta que el débito se confirme.- Si repites la petición con la misma
Idempotency-Key, la respuesta también es201, pero con el formato de la consulta, no con este. Para saber si el payout ya existía, mira el cuerpo, no el código HTTP.
feeAmount es "0.00" en la creación y 0 en la consulta. Si tu contrato define una comisión, se debita de tu saldo además del monto. El beneficiario recibe el amount completo.
Idempotencia
La cabecera Idempotency-Key hace que un reintento (por un timeout de red, por ejemplo) no duplique el envío. Si repites una petición con la misma clave, iion pay devuelve el payout ya creado en lugar de dispersar de nuevo. Usa una clave única por cada payout (por ejemplo, un UUID).
Consultar el estado
Obtiene el estado actual de un payout de tu comercio. Exige el permiso payout:create.
{
"success": true,
"data": {
"payoutId": "clpay123abc456def",
"status": "COMPLETED",
"amount": 100000,
"feeAmount": 0,
"recipientName": "María Gómez",
"network": "BREB",
"providerPayoutId": "mm_abc123",
"createdAt": "2026-10-30T12:00:00.000Z",
"completedAt": "2026-10-30T12:00:05.000Z"
}
}
En la consulta, amount y feeAmount son números. Si el payout no existe o no es de tu comercio, la respuesta es 404 con message Payout no encontrado.
Listar payouts
Lista los payouts de tu comercio, del más reciente al más antiguo. Exige el permiso payout:create. Cada elemento de data tiene el formato de la consulta por id.
| Parámetro | Descripción |
|---|---|
status | Opcional. Filtra por un estado exacto, por ejemplo COMPLETED. |
limit | Opcional. Cantidad de resultados. Por defecto 20, máximo 100. |
offset | Opcional. Cantidad de resultados que se saltan, para paginar. |
curl 'https://api.prod.iionpay.com/api/v1/payout?status=COMPLETED&limit=20&offset=0' \
--header 'X-Api-Key: TU_API_KEY' \
--header 'X-Api-Secret: TU_API_SECRET'
Estados
| Estado | Significado |
|---|---|
PENDING_RESERVE | Reserva interna antes de debitar tu saldo. Si el débito falla, el registro normalmente se elimina. Un payout puede quedarse en PENDING_RESERVE con tu saldo ya debitado si la API respondió un 400 que pide contactar a soporte (ver Errores comunes). |
PENDING_ONCHAIN | El débito de tu saldo está en confirmación. |
PENDING | Recibido, pendiente de procesar. |
PROCESSING | En proceso de dispersión con el banco. |
COMPLETED | Fondos entregados al beneficiario. Estado final. |
FAILED | La dispersión falló. Si tu saldo ya se debitó, pasa a REFUNDED o a STUCK_REFUND_FAILED. Puede pasar a NEEDS_REVIEW (ver abajo). |
REFUNDED | El débito volvió a tu saldo tras un fallo. No es necesariamente final: puede pasar a NEEDS_REVIEW (ver abajo). |
STUCK_REFUND_FAILED | La devolución automática a tu saldo falló. El equipo de soporte la revisa. Puede pasar a NEEDS_REVIEW (ver abajo). |
NEEDS_REVIEW | El resultado de la dispersión no es claro. Una persona lo revisa. No crees otro payout para el mismo pago mientras tanto. |
FAILED, REFUNDED y STUCK_REFUND_FAILED pueden cambiar a NEEDS_REVIEW. Pasa cuando el banco confirma tarde que sí entregó los fondos. En ese caso el beneficiario pudo recibir el dinero aunque tu saldo ya se devolvió. Una persona revisa el caso. No crees otro payout para el mismo pago y vuelve a consultar el estado antes de conciliar.
Errores comunes
| Código HTTP | Causa |
|---|---|
400 | Validación, falta Idempotency-Key, el monto excede el tope, el método no está en el catálogo (PAYOUT_METHOD_NOT_AVAILABLE — consulta GET /payout/methods), la Idempotency-Key es de otra wallet (PAYOUT_SOURCE_MISMATCH), o la dispersión falló. |
400 | Retiro a cuenta bancaria sin accountType (banco que no es billetera): Indica el tipo de cuenta (ahorros o corriente). No se debita saldo. |
400 | Retiro a una billetera con un celular inválido: Para {banco} escribe el número de celular de 10 dígitos que empieza por 3. No se debita saldo. |
401 | API Key o Secret inválido. |
403 | El payout no está habilitado para tu comercio, o tu API Key no tiene el permiso payout:create. Aplica también a las consultas (GET). También: KYB_REQUIRED (completa la vinculación de tu empresa para retirar más del umbral del mes), OUTFLOW_ON_HOLD (tus salidas de dinero están en revisión) y message La wallet Business no está disponible. (sin error.code; aplica también a las consultas). |
503 | El payout está temporalmente deshabilitado o no hay proveedor disponible. |
PENDING_RESERVE. Ante un 400, consulta GET /api/v1/payout antes de reintentar. Si el message es Error procesando el envío. Estamos revisando el caso, contacta a soporte., contacta a soporte y no crees otro payout. Si reintentas, no cambies la Idempotency-Key: con la misma clave la API devuelve el payout ya guardado y no dispersa otra vez.