Payouts

Dispersa fondos de tu saldo NIIO 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.

Requisitos

• Payout habilitado para tu comercio — se activa por cuenta; si aún no lo tienes, contacta a NIIO 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).
• Saldo suficiente — el payout debita tu saldo más el fee. 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 tope por transacción (limits.maxAmountCop).

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. NIIO enruta internamente al proveedor bancario adecuado según el método y el monto — tú no eliges el proveedor.

Crear un payout

Ejemplo: envío por llave Bre-B

curl https://api.prod.niiopay.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.niiopay.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"
  }'

Respuesta

{
  "success": true,
  "data": {
    "payoutId": "clpay123abc456def",
    "status": "PENDING",
    "amount": 100000,
    "feeAmount": 500,
    "recipientName": "María Gómez",
    "network": "breb",
    "providerPayoutId": "mm_abc123",
    "createdAt": "2024-01-15T12:00:00.000Z",
    "completedAt": null
  }
}

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, NIIO 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

Errores comunes