Payouts
Pagando saldos liquidados para uma wallet — o step-up 2FA para sessões do dashboard, API keys com step-up, a taxa de rede fixa e o ciclo de vida do payout.
Última atualização 27 de out. de 2026
Um payout envia parte ou todo o saldo disponível de uma conta (GET /api/v1/crypto/balances?mode=) em uma rede e um token para um endereço externo, a partir da hot wallet.
curl -X POST "$API/api/v1/crypto/payouts" \
-H "authorization: Bearer $KEY" -H 'content-type: application/json' -H 'idempotency-key: po-2026-10-27-halden' \
-d '{ "account": "halden_type", "network": "POLYGON_AMOY", "token": "USDT",
"amount": "50.00", "destination_address": "0x…" }'Quem pode fazer payouts
Payouts exigem crypto-payouts:create e são recusados enquanto um admin da plataforma está impersonando o usuário. Além disso, todo payout passa por step-up:
- Dashboard (sessão com cookie): cada payout leva um código TOTP novo (
totp_code). O usuário precisa ter a autenticação de dois fatores ativada (Settings → Security); caso contrário, o diálogo New payout aponta para lá. Os códigos são de uso único, e 5 códigos errados em 15 minutos bloqueiam os step-ups (429 STEP_UP_LOCKED). Um código errado ou reutilizado é403. - API keys dispensam o código por payout, então o step-up passa para o momento em que a key é criada: criar uma key com
crypto-payouts:create(oucrypto-payouts:manage, ou*:*) exige uma sessão de navegador sem impersonação, com 2FA e umtotp_codeválido. Só essas keys têmpayoutStepUpAt; qualquer outra key responde403 STEP_UP_REQUIRED. Keys criadas antes dessa regra perderam a capacidade de fazer payouts. A CLI do operador (mint:api-key) também o define.
Valor e taxa
Uma taxa de rede fixa por payout sai do valor (net_amount = amount − fee) e é lançada como REVENUE:PAYOUT_NETWORK_FEE: CRYPTO_PAYOUT_FEE_POLYGON (padrão 0.10), CRYPTO_PAYOUT_FEE_BSC (0.15), CRYPTO_PAYOUT_FEE_BASE (0.10). O valor precisa ser maior que a taxa. O destino precisa ser um endereço válido que não seja um dos endereços do próprio gateway (contratos são permitidos, ao contrário dos refunds).
Ciclo de vida
| Status | Significado |
|---|---|
QUEUED | Criado: o valor é bloqueado no ledger (MERCHANT_LOCKED) na mesma transação, então um payout acima do saldo é 409 INSUFFICIENT_BALANCE e não cria nada. |
BROADCAST | Assinado e enviado pelo worker assim que a hot wallet consegue cobrir net_amount e o gas (caso contrário, ele espera os sweeps). A transação é registrada no journal antes do broadcast, então um crash reenvia os mesmos bytes; após 180 s sem recibo ela é substituída com o mesmo nonce e fees +20 %. |
COMPLETED | A transação atingiu o limiar de confirmações da rede; o bloqueio é liberado para o payout (payout.completed). |
FAILED | Revertida ou descartada: o bloqueio volta para o saldo disponível e o gas é lançado como despesa (payout.failed). |
A página Payouts do dashboard mostra os saldos no topo, o histórico abaixo (contagem de confirmações ao vivo enquanto BROADCAST) e New payout (saldo de origem, valor, destino pré-preenchido com o endereço de liquidação da conta, TOTP).
[!WARNING] Quando uma invoice não tem
merchant, a conta PLATFORM da organização é a vendedora: o seu líquido é creditado emPARTNER_PAYABLEjunto com o markup, o único saldo de onde saem os payouts da PLATFORM. Assim, todo payout sai do saldo que o dashboard mostra como disponível.