Pagos

Enviar fondos desde su saldo a un monedero móvil o a una cuenta bancaria.

Crear un pago

POST /v1/payouts

Pase un Idempotency-Key — importa aún más que en el cobro: un pago reenviado sin idempotencia pagaría dos veces.

Campo	Obligatorio	Descripción
asset_id	sí	El activo, por su identificador
amount_minor	sí	Cadena, en unidades menores
country	sí	País de la operación (ISO 3166-1 alfa-2)
platform_id	sí	La plataforma de pago (GET /v1/corridors)
recipient	sí	El destinatario — véase abajo
platform_account_handle	—	La subcuenta a cargar. Vacío = la primaria del corredor
rail	—	Fuerza un rail concreto
client_ref	—	Su referencia
description	—	Texto libre

El destinatario va tipado

"recipient": {
  "name": "Mouhamadou Sy",
  "identifier_type": "msisdn",
  "identifier": "+221771234567"
}

identifier_type dice qué clase de dirección tiene usted (msisdn, iban, un alias…) e identifier la lleva. Es lo que permite a una plataforma con varios rails resolver sin que usted tenga que nombrar ninguno.

phone a secas sigue plenamente aceptado y se interpreta como (msisdn, phone). Dar las dos formas, o un tipo sin valor, se rechaza — nunca se adivina.

Primero el saldo

Un pago se carga sobre su saldo disponible:

GET /v1/balances

Los saldos se devuelven por activo y por (plataforma, país), con el disponible, el pendiente y el reservado. El reservado cubre las salidas ya comprometidas: no es gastable.

Los saldos nunca se suman entre activos. No existe conversión de divisa en esta plataforma, así que un total de todos los activos no significaría nada.

Un pago que superara el disponible se rechaza de inmediato, en la propia respuesta: 422 con el código insufficient_funds. Nunca queda a la espera de fondos — no existe el descubierto.

Solicitar una retirada de su saldo

POST /v1/payout-requests
GET  /v1/payout-requests
GET  /v1/payout-requests/{id}

Es una solicitud, no un pago. No se mueve dinero y no se reserva nada: la operación se abre en estado requested y una persona la decide en el panel. Es la separación maker-checker — la clave de API solicita, un propietario de la cuenta decide. No existe deliberadamente ninguna anulación: una solicitud pendiente no retiene nada, así que se rechaza del lado de quien decide.

El importe es BRUTO: las comisiones de retirada se deducen de él, no se suman. Sin una tabla de comisiones configurada para el activo, la solicitud se rechaza con 409 — una retirada gratuita es una línea a cero escrita a propósito, nunca una ausencia.

Seguimiento

payout.success, payout.failed y payout.cancelled llegan por webhook; GET /v1/payouts/{id} da el estado a petición.