Pagamentos

Enviar fundos do seu saldo para uma carteira móvel ou uma conta bancária.

Criar um pagamento

POST /v1/payouts

Passe um Idempotency-Key — conta ainda mais do que na cobrança: um pagamento reenviado sem idempotência pagaria duas vezes.

Campo	Obrigatório	Descrição
asset_id	sim	O activo, pelo seu identificador
amount_minor	sim	Cadeia, em unidades menores
country	sim	País da operação (ISO 3166-1 alfa-2)
platform_id	sim	A plataforma de pagamento (GET /v1/corridors)
recipient	sim	O destinatário — ver abaixo
platform_account_handle	—	A subconta debitada. Vazio = a primária do corredor
rail	—	Força um rail preciso
client_ref	—	A sua referência
description	—	Texto livre

O destinatário é tipado

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

identifier_type diz que espécie de endereço detém (msisdn, iban, um alias…) e identifier transporta-o. É o que permite a uma plataforma com vários rails resolver sem que tenha de nomear nenhum.

phone sozinho continua plenamente aceite e lê-se como (msisdn, phone). Fornecer as duas formas, ou um tipo sem valor, é recusado — nunca adivinhado.

O saldo primeiro

Um pagamento é debitado no seu saldo disponível:

GET /v1/balances

Os saldos são devolvidos por activo e por (plataforma, país), com o disponível, o pendente e o reservado. O reservado cobre as saídas já comprometidas: não é gastável.

Os saldos nunca se somam entre activos. Não existe conversão de moeda nesta plataforma, pelo que um total de todos os activos não faria sentido.

Um pagamento que ultrapassasse o disponível é recusado de imediato, na própria resposta: 422 com o código insufficient_funds. Nunca fica à espera de fundos — não existe descoberto.

Pedir um levantamento do seu saldo

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

É um pedido, não um pagamento. Nenhum dinheiro se move e nada é reservado: a operação abre no estado requested e uma pessoa decide-a no painel. É a separação maker-checker — a chave de API pede, um proprietário da conta decide. Não existe deliberadamente qualquer anulação: um pedido pendente não retém nada, por isso é recusado do lado de quem decide.

O montante é BRUTO: as comissões de levantamento são deduzidas dele, não acrescentadas. Sem uma tabela de comissões configurada para o activo, o pedido é recusado com 409 — um levantamento gratuito é uma linha a zero escrita de propósito, nunca uma ausência.

Acompanhamento

payout.success, payout.failed e payout.cancelled chegam por webhook; GET /v1/payouts/{id} dá o estado a pedido.