Pagamenti

Inviare fondi dal suo saldo a un portafoglio mobile o a un conto bancario.

Creare un pagamento

POST /v1/payouts

Passi un Idempotency-Key — qui conta ancora più che nell'incasso: un pagamento ripetuto senza idempotenza pagherebbe due volte.

Campo	Obbligatorio	Descrizione
asset_id	sì	L'asset, tramite il suo identificativo
amount_minor	sì	Stringa, in unità minori
country	sì	Paese dell'operazione (ISO 3166-1 alpha-2)
platform_id	sì	La piattaforma di pagamento (GET /v1/corridors)
recipient	sì	Il destinatario — vedi sotto
platform_account_handle	—	Il sottoconto addebitato. Vuoto = il primario del corridoio
rail	—	Forza un rail preciso
client_ref	—	Il suo riferimento
description	—	Testo libero

Il destinatario è tipizzato

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

identifier_type dice che genere di indirizzo lei possiede (msisdn, iban, un alias…) e identifier lo porta. È ciò che permette a una piattaforma con più rail di risolvere senza che lei debba nominarne uno.

phone da solo resta pienamente accettato e si interpreta come (msisdn, phone). Fornire entrambe le forme, o un tipo senza valore, è rifiutato — mai indovinato.

Prima il saldo

Un pagamento viene addebitato sul suo saldo disponibile:

GET /v1/balances

I saldi sono restituiti per asset e per (piattaforma, paese), con il disponibile, il sospeso e il riservato. Il riservato copre le uscite già impegnate: non è spendibile.

I saldi non si sommano mai tra asset. Su questa piattaforma non esiste conversione di valuta, quindi un totale su tutti gli asset non avrebbe senso.

Un pagamento che superasse il disponibile è rifiutato subito, nella risposta stessa: 422 con il codice insufficient_funds. Non resta mai in attesa di fondi — lo scoperto non esiste.

Chiedere un prelievo dal suo saldo

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

È una richiesta, non un pagamento. Nessun denaro si muove e nulla viene riservato: l'operazione si apre nello stato requested e una persona la decide nella dashboard. È la separazione maker-checker — la chiave API chiede, un proprietario del conto decide. Non esiste deliberatamente alcun annullamento: una richiesta in attesa non trattiene nulla, quindi viene rifiutata dal lato di chi decide.

L'importo è LORDO: le commissioni di prelievo vengono dedotte da esso, non aggiunte. Senza una tabella di commissioni configurata per l'asset, la richiesta è rifiutata con 409 — un prelievo gratuito è una riga a zero inserita apposta, mai un'assenza.

Monitoraggio

payout.success, payout.failed e payout.cancelled arrivano via webhook; GET /v1/payouts/{id} dà lo stato su richiesta.