Saques Cripto
Um saque cripto envia o saldo do merchant em criptomoeda. O débito é sempre em BRL e a entrega é feita na moeda escolhida (USDT, BTC, ETH, SOL ou XMR). A segurança é a mesma do Saque PIX: token Bearer + whitelist de IP + idempotência por external_id.
Pré-requisitos
- Seu IP está na whitelist da conta (a mesma do saque PIX — Credenciais → IPs autorizados). Fora dela:
HTTP 403 — Unauthorized IP address. - Seu saldo disponível cobre o
amount. Consulte viaGET /api/accounts/balance. Caso contrário:INSUFFICIENT_BALANCE. - Seu token Bearer está válido. Veja Autenticação.
Moedas e redes
coin | Moeda | Rede (fixa) | Formato do wallet |
|---|---|---|---|
usdt | USDT | BNB Smart Chain (BEP20) | EVM 0x… (40 hex) |
btc | Bitcoin | Bitcoin | bc1… / 1… / 3… |
eth | Ethereum | Ethereum | EVM 0x… (40 hex) |
sol | Solana | Solana | base58 (32–44 chars) |
xmr | Monero | Monero | começa com 4 ou 8 |
As moedas efetivamente disponíveis, os limites (mín./máx. em BRL) e as taxas da sua conta ficam em GET /api/withdrawals/crypto/config. Para estimar quanto o destinatário recebe na moeda, use GET /api/withdrawals/crypto/quote?coin=usdt&amount=200.
Endpoint
POST https://api.zypfy.com/api/withdrawals/crypto/withdrawHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Exemplo — USDT (rede BEP20)
{
"amount": 200.00,
"external_id": "cw-0001",
"coin": "usdt",
"wallet": "0x1234567890abcdef1234567890abcdef12345678",
"clientCallbackUrl": "https://minhaloja.com/webhooks/crypto-withdrawal"
}Exemplo — Monero (XMR)
{
"amount": 150.00,
"external_id": "cw-0003",
"coin": "xmr",
"wallet": "44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A"
}Campos
| Campo | Obrigatório? | Notas |
|---|---|---|
amount | Sim | Valor bruto em BRL a debitar. As taxas são descontadas dentro desse valor. |
external_id | Sim | Identificador único do seu lado (chave de idempotência). |
coin | Sim | usdt, btc, eth, sol ou xmr. A rede é derivada da moeda. |
wallet | Sim | Endereço de destino, válido para a moeda (ver tabela acima). |
clientCallbackUrl | Não | URL HTTPS para o webhook de conclusão. Se omitido, usa o webhook de saque do portal. |
Resposta 201 Created
{
"message": "Crypto withdrawal request received. Awaiting approval.",
"withdrawal": {
"transaction_id": "b2c3d4e5f6a789012345678901234567",
"external_id": "cw-0001",
"status": "PENDING",
"amount": 200.00,
"fee": 9.00,
"total": 200.00,
"coin": "usdt",
"network": "BNB Smart Chain (BEP20)",
"coin_amount": 34.512000,
"wallet": "0x1234567890abcdef1234567890abcdef12345678"
}
}Ciclo de vida (status)
┌────────────┐
│ PENDING │ ← resposta inicial (aguardando aprovação)
└─────┬──────┘
│ (aprovação interna → envio à rede)
├───► COMPLETED ──► webhook enviado (com tx_hash on-chain)
└───► FAILED ──► webhook enviado, saldo devolvido automaticamenteO saque é criado como PENDING e enviado à rede após aprovação (a criptomoeda é irreversível). A conclusão (COMPLETED/FAILED) chega pelo webhook e pode ser consultada a qualquer momento em GET /api/transactions/withdraw.
Idempotência
external_id é a chave de idempotência (único por conta). Repetir o mesmo external_id retorna o saque já criado (HTTP 200), nunca duplica. Uma corrida concorrente com o mesmo external_id retorna HTTP 409 (DUPLICATE_EXTERNAL_ID).
Webhook de conclusão
Quando o saque atinge estado final, a Zypfy faz POST na sua clientCallbackUrl com type: "CryptoWithdrawal":
{
"type": "CryptoWithdrawal",
"transaction_id": "b2c3d4e5f6a789012345678901234567",
"external_id": "cw-0001",
"status": "COMPLETED",
"amount": 200.00,
"fee": 9.00,
"total": 200.00,
"coin": "usdt",
"network": "BNB Smart Chain (BEP20)",
"coin_amount": 34.512000,
"tx_hash": "0xabc123...def",
"wallet": "0x1234567890abcdef1234567890abcdef12345678"
}Em falha, status = FAILED, tx_hash = null e vem error_message. A assinatura (X-Webhook-Signature + X-Webhook-Timestamp) e o reenvio automático (até 3 tentativas) funcionam igual aos demais webhooks — veja Verificando a assinatura dos webhooks.
Reconciliação
Consulte o estado atual (inclusive dados on-chain) por identificador único:
GET /api/transactions/withdraw?external_id=cw-0001Para saques cripto, a resposta traz is_crypto: true e os campos crypto_coin, crypto_network, crypto_wallet, crypto_coin_amount e crypto_tx_hash.
Códigos de erro específicos
| Código | HTTP | Significado | Remediação |
|---|---|---|---|
EXTERNAL_ID_REQUIRED | 400 | Falta external_id | Enviar um external_id único. |
COIN_UNSUPPORTED | 400 | Moeda não suportada | Usar usdt, btc, eth, sol ou xmr. |
WALLET_INVALID | 400 | Endereço inválido para a moeda | Conferir o formato na tabela de moedas/redes. |
INSUFFICIENT_BALANCE | 400 | Saldo menor que amount | Conferir em /api/accounts/balance antes. |
COIN_DISABLED / CRYPTO_DISABLED | 403 | Moeda/saque cripto desabilitado no momento | Consultar GET /api/withdrawals/crypto/config. |
CRYPTO_DAILY_LIMIT | 403 | Acima do limite diário de saque cripto | Aguardar a janela de 24h ou falar com o suporte. |
DUPLICATE_EXTERNAL_ID | 409 | external_id já usado (corrida) | Usar novo external_id ou tratar como idempotente. |
Unauthorized IP address. | 403 | IP fora da whitelist | Adicionar IP em Credenciais → IPs autorizados. |
Boas práticas
- Confira o endereço e a rede antes de sacar — envios em cripto são irreversíveis. Cada moeda só sai na sua rede (ex.: USDT só em BEP20).
- Sempre chame
GET /api/accounts/balanceantes — evitaINSUFFICIENT_BALANCE. - Derive
external_iddo ID do seu pedido — protege contra duplicatas em retentativas. - Configure o webhook de saque — é a fonte da verdade para o status final. A resposta 201 significa "aceito", não "liquidado".
- Se o webhook não chegar, reconcilie por polling via
GET /api/transactions/withdraw?external_id=seu_id.