Cash-out
Envia um pagamento para uma chave PIX (BRL), endereço de carteira cripto ou CLABE (MXN/SPEI). O saldo é debitado imediatamente, mas a liquidação é assíncrona — a resposta inicial retorna 202 Accepted com status: pending e a confirmação chega via webhook.
Esta rota exige assinatura HMAC. Inclua os headers X-Signature, X-Timestamp e X-Nonce além do Bearer token. Ver Autenticação → HMAC.
Headers
Body
external_idstringobrigatórioexternal_id retorna a mesma transação. amountnumberobrigatóriocurrencystringobrigatórioBRL, MXN, USDT, USDC, BTC, ETH, SOL, BNB. keystringobrigatóriokey_typestringcpf, cnpj, email, phone, random. Para cripto/SPEI: omitir. networkstringtron, ethereum, bsc, polygon, solana, bitcoin. Obrigatório quando currency é cripto.
network≠chain:networké a rede onde a tx é broadcast (pode ser uma L2 comoarbitrum,base,optimism);chainé a blockchain de origem (livro-razão). Para Tron/BTC/Solana/BSC ambos coincidem; para ETH/USDC em L2, podem diferir.
namestringbank_codestringdescriptionstringpostback_urlstringRate limit
6000 reqs/min por credencial.
Resposta
202 Accepted — operação aceita, processamento assíncrono. Aguarde o webhook cashout.confirmed (sucesso) ou cashout.failed (falha — saldo refundado automaticamente).
Erros
| Código | HTTP | Descrição |
|---|---|---|
MISSING_REQUIRED_FIELD | 400 | Campo obrigatório ausente — details.field |
MISSING_SIGNATURE / INVALID_SIGNATURE | 401 | Header HMAC ausente ou inválido |
INVALID_TIMESTAMP | 401 | X-Timestamp fora da janela ±5 min |
REPLAY_DETECTED | 401 | X-Nonce já usado nos últimos 5 min |
INVALID_AMOUNT | 422 | Valor inválido |
INVALID_CURRENCY | 422 | Moeda não suportada |
INVALID_PIX_KEY | 422 | Chave PIX malformada ou não encontrada no DICT |
UNSUPPORTED_CHAIN | 422 | network não suportado para a moeda |
INSUFFICIENT_FUNDS | 422 | Saldo insuficiente para amount + fee |
BELOW_MIN_LIMIT | 409 | Abaixo do mínimo — details.min_amount |
EXCEEDS_MAX_LIMIT | 409 | Acima do máximo — details.max_amount |
LIMIT_EXCEEDED | 409 | Limite diário/mensal atingido |
DUPLICATE_EXTERNAL_ID | 409 | external_id já utilizado |
ACCOUNT_UNDER_REVIEW | 403 | Conta sob análise — operação suspensa |
PROVIDER_ERROR | 502 | Erro no provedor — retryable |
PIX (BRL)
Cripto — body usa network:
SPEI (MXN) — body usa CLABE + name + bank_code:
Fluxo assíncrono
- Você envia o request com HMAC válido
- API retorna
202 Acceptedcomstatus: pending(saldo já debitado) - Servidor processa contra o provedor (PIX/blockchain/SPEI)
- Sucesso → webhook
cashout.confirmedcomhash(PIX e2e_id) outx_hash(blockchain) - Falha → webhook
cashout.failedcomerror_codeespecífico, saldo refundado automaticamente
Para cashout cripto, error_code possíveis no webhook: TRON_ENERGY_FAIL, INSUFFICIENT_BALANCE, NO_HOT_WALLET, INVALID_ADDRESS, BLACKLISTED, BLOCKCHAIN_REVERT, BROADCAST_FAIL, UNKNOWN.
