7. Cripto — sacar o saldo da loja

Leva o saldo USDC da loja para qualquer chave Pix, pela API ou pelo painel. O Pix sai de uma conta no nome da empresa, por isso este é o único fluxo cripto que exige o cadastro cripto da loja (KYC da empresa no provedor). A taxa é descontada do valor, como no pagamento ao cliente.

Nos exemplos, a taxa de saque da loja é R$ 3,00 em R$ 100,00.

sequenceDiagram
  participant P as Painel
  participant S as Seu sistema
  participant G as Plataforma
  participant E as Conta da empresa
  P->>G: KYC › aba Cripto: PF ou PJ, termos e documentos
  Note over G: aprovado: conta da empresa pronta no provedor
  S->>G: POST /crypto/withdrawals + Idempotency-Key
  G-->>S: 202 PROCESSING + webhook crypto.withdrawal.processing
  G->>E: Pix (cerca de amountBrl − fee)
  G-->>S: webhook crypto.withdrawal.paid

Passo 1 — Cadastro cripto da loja (uma vez, no painel)

Verificação KYC › aba Cripto.
Escolha PJ (CNPJ) ou PF (CPF). A identidade é o documento cadastrado da empresa.
Aceite os termos e envie os documentos pelos links.
Aguarde a aprovação; a aba mostra o cadastro ativo.

Não existe rota de API para esse cadastro: ele é feito por uma pessoa da empresa no painel.

Passo 2 — Tentou sacar antes da aprovação? `409`

curl -X POST https://api.gestaotechnology.com/api/crypto/withdrawals \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-loja-2026-10-15" \
  -d '{ "amountBrl": 10000, "pixKey": "12345678000199", "pixKeyType": "CNPJ" }'

{
  "error": "merchant_wallet_not_ready",
  "message": "Conclua o cadastro cripto da empresa para sacar",
  "status": "PENDING",
  "kycLink": "https://kyc.exemplo/…",
  "tosLink": "https://termos.exemplo/…"
}

Nada foi reservado. Leve o status para a sua tela e direcione quem cuida do financeiro para o painel. Depois da aprovação, repita a mesma chamada.

Passo 3 — Conferir o valor (opcional, recomendado)

Antes do POST, mostre ao usuário quanto ele pode sacar e quanto chega no Pix. A cotação não tem efeito e usa a mesma conta do saque:

curl https://api.gestaotechnology.com/api/crypto/withdrawals/quote -H "X-Api-Key: <SECRET_KEY>"

curl "https://api.gestaotechnology.com/api/crypto/withdrawals/quote?amountBrl=10000" -H "X-Api-Key: <SECRET_KEY>"

Com quote.ok: true, siga para o saque. Com false, mostre quote.message. Detalhes em Saque da loja.

Passo 4 — Sacar

Com o cadastro aprovado, a mesma chamada responde:

{
  "withdrawalId": "5c1e9a7d-3f0b-4b8e-9d2a-7a1f0c2e4b61",
  "status": "PROCESSING",
  "amountBrl": 10000,
  "grossUsdc": "18.867925",
  "netUsdc": "18.190000",
  "rate": "5.330000",
  "fee": 300,
  "pixKey": "12.***.***/0001-99",
  "deliveredBrl": null,
  "createdAt": "2026-10-15T17:00:00.000Z",
  "paidAt": null
}

grossUsdc sai do saldo; netUsdc vai no Pix (R$ 97,00 a 5,33 reais por USDC).
Qualquer chave, pela API ou pelo painel: o destino é decisão da loja. O provedor confere se a chave pertence ao documento do dono: a própria chave CPF/CNPJ; nas outras, o recipientDocument (chave de outra pessoa) ou o documento da empresa.

Passo 5 — Webhooks

{
  "event": "crypto.withdrawal.processing",
  "occurredAt": "2026-10-15T17:00:00.400Z",
  "data": {
    "withdrawalId": "5c1e9a7d-3f0b-4b8e-9d2a-7a1f0c2e4b61",
    "status": "PROCESSING",
    "amountBrl": 10000,
    "grossUsdc": "18.867925",
    "netUsdc": "18.190000",
    "rate": "5.330000",
    "fee": 300
  }
}

{
  "event": "crypto.withdrawal.paid",
  "occurredAt": "2026-10-15T17:05:20.000Z",
  "data": {
    "withdrawalId": "5c1e9a7d-3f0b-4b8e-9d2a-7a1f0c2e4b61",
    "status": "PAID",
    "amountBrl": 10000,
    "netUsdc": "18.190000",
    "rate": "5.330000",
    "deliveredBrl": 9695,
    "fee": 300
  }
}

Se o Pix não sair ou voltar, chega crypto.withdrawal.failed (status: "FAILED", reason) e o valor reservado volta inteiro para o saldo.

Sem webhook? GET /crypto/withdrawals/5c1e9a7d-3f0b-4b8e-9d2a-7a1f0c2e4b61, ou a lista GET /crypto/withdrawals?status=PROCESSING.

Erros comuns

Resposta	Quando	O que fazer
`409 merchant_wallet_not_ready`	Cadastro cripto da loja não aprovado.	Conclua no painel.
`422 pix_key_not_owned`	O provedor não aceitou a chave para o titular informado.	Confira a chave e, se for de outra pessoa, o `recipientDocument`.
`429`	Mais de 30 pedidos por minuto.	Espere e repita com a mesma `Idempotency-Key`.
`422 amount_below_minimum`	`amountBrl − fee` abaixo de R$ 10,00.	Aumente o valor.
`422 insufficient_balance` / `limit_exceeded`	Saldo ou limite.	Ajuste o valor.
`422 provider_cost_exceeds_fee`	A taxa não cobre o custo do provedor.	Fale com a Gestão Intermediações.
`503 provider_unavailable`	Provedor ou cotação fora.	Repita com a mesma `Idempotency-Key`.

Referência: Sacar o saldo da loja, Cadastro cripto da loja.