ZypfyDocs Acessar painel
Guia de integração

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

  1. Seu IP está na whitelist da conta (a mesma do saque PIX — Credenciais → IPs autorizados). Fora dela: HTTP 403 — Unauthorized IP address.
  2. Seu saldo disponível cobre o amount. Consulte via GET /api/accounts/balance. Caso contrário: INSUFFICIENT_BALANCE.
  3. Seu token Bearer está válido. Veja Autenticação.

Moedas e redes

coinMoedaRede (fixa)Formato do wallet
usdtUSDTBNB Smart Chain (BEP20)EVM 0x… (40 hex)
btcBitcoinBitcoinbc1… / 1… / 3…
ethEthereumEthereumEVM 0x… (40 hex)
solSolanaSolanabase58 (32–44 chars)
xmrMoneroMonerocomeç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

código
POST https://api.zypfy.com/api/withdrawals/crypto/withdraw

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

Exemplo — USDT (rede BEP20)

json
{
  "amount": 200.00,
  "external_id": "cw-0001",
  "coin": "usdt",
  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "clientCallbackUrl": "https://minhaloja.com/webhooks/crypto-withdrawal"
}

Exemplo — Monero (XMR)

json
{
  "amount": 150.00,
  "external_id": "cw-0003",
  "coin": "xmr",
  "wallet": "44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A"
}

Campos

CampoObrigatório?Notas
amountSimValor bruto em BRL a debitar. As taxas são descontadas dentro desse valor.
external_idSimIdentificador único do seu lado (chave de idempotência).
coinSimusdt, btc, eth, sol ou xmr. A rede é derivada da moeda.
walletSimEndereço de destino, válido para a moeda (ver tabela acima).
clientCallbackUrlNãoURL HTTPS para o webhook de conclusão. Se omitido, usa o webhook de saque do portal.

Resposta 201 Created

json
{
  "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)

código
   ┌────────────┐
   │  PENDING   │  ← resposta inicial (aguardando aprovação)
   └─────┬──────┘
         │  (aprovação interna → envio à rede)
         ├───► COMPLETED  ──► webhook enviado (com tx_hash on-chain)
         └───► FAILED     ──► webhook enviado, saldo devolvido automaticamente

O 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":

json
{
  "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:

código
GET /api/transactions/withdraw?external_id=cw-0001

Para 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ódigoHTTPSignificadoRemediação
EXTERNAL_ID_REQUIRED400Falta external_idEnviar um external_id único.
COIN_UNSUPPORTED400Moeda não suportadaUsar usdt, btc, eth, sol ou xmr.
WALLET_INVALID400Endereço inválido para a moedaConferir o formato na tabela de moedas/redes.
INSUFFICIENT_BALANCE400Saldo menor que amountConferir em /api/accounts/balance antes.
COIN_DISABLED / CRYPTO_DISABLED403Moeda/saque cripto desabilitado no momentoConsultar GET /api/withdrawals/crypto/config.
CRYPTO_DAILY_LIMIT403Acima do limite diário de saque criptoAguardar a janela de 24h ou falar com o suporte.
DUPLICATE_EXTERNAL_ID409external_id já usado (corrida)Usar novo external_id ou tratar como idempotente.
Unauthorized IP address.403IP fora da whitelistAdicionar IP em Credenciais → IPs autorizados.

Boas práticas

  1. 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).
  2. Sempre chame GET /api/accounts/balance antes — evita INSUFFICIENT_BALANCE.
  3. Derive external_id do ID do seu pedido — protege contra duplicatas em retentativas.
  4. Configure o webhook de saque — é a fonte da verdade para o status final. A resposta 201 significa "aceito", não "liquidado".
  5. Se o webhook não chegar, reconcilie por polling via GET /api/transactions/withdraw?external_id=seu_id.