Sacar o saldo da loja

Saca o saldo USDC da loja para qualquer chave Pix, pela API ou pelo painel: o Pix sai da conta da própria loja no provedor, e o destino é decisão (e responsabilidade) da loja. Funciona como pagar o cliente, com a taxa descontada do valor, mas o Pix sai de uma conta no nome da empresa. Por isso exige o cadastro cripto da loja aprovado.

`GET /crypto/withdrawals/quote` → `200`

Cotação do saque, sem efeito: não reserva saldo nem fala com o banco do cliente. Usa exatamente a mesma conta do POST, então serve para mostrar ao usuário quanto ele pode sacar e quanto chega no Pix antes de enviar. Requer scope CRYPTO_READ. Limite: 60 chamadas por minuto.

Sem parâmetros, devolve o saldo em reais e a faixa de valores aceitos agora:

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

{
  "currency": "USDC",
  "availableUsdc": "18.867925",
  "availableBrl": 10056,
  "rate": "5.330000",
  "sellRate": "5.300000",
  "minAmountBrl": 1031,
  "maxAmountBrl": 10056
}

Com amountBrl (centavos), devolve a prévia daquele valor em quote (a faixa não vem):

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

{
  "currency": "USDC",
  "availableUsdc": "18.867925",
  "availableBrl": 10056,
  "rate": "5.330000",
  "sellRate": "5.300000",
  "quote": { "amountBrl": 10000, "ok": true, "fee": 300, "netBrl": 9700, "debitUsdc": "18.761726", "sendUsdc": "18.300000" }
}

Campo	Significado
`availableUsdc` / `availableBrl`	Saldo disponível; em reais é aproximado (cotação de mercado `rate`, para baixo).
`minAmountBrl` / `maxAmountBrl`	Menor e maior `amountBrl` aceitos agora (taxa, mínimo do Pix, saldo, limites). `null`: nenhum valor passa. Só sem `amountBrl`.
`quote.ok`	`true`: o `POST` com esse valor passa (salvo mudança de saldo ou cotação até lá). `false`: vem `error` e `message` com o mesmo código que o `POST` daria (`amount_below_minimum`, `WITHDRAW_FEE_EXCEEDS_AMOUNT`, `insufficient_balance`, `limit_exceeded`, `provider_cost_exceeds_fee`, `refund_under_review`).
`quote.fee` / `quote.netBrl`	Taxa e o que sai no Pix (`amountBrl − fee`), em centavos. O valor entregue final pode variar alguns centavos com a cotação de venda.
`quote.debitUsdc` / `quote.sendUsdc`	USDC que sai do saldo e que vai para o Pix.

Cotação indisponível no provedor: 503 provider_unavailable, como no POST.

`POST /crypto/withdrawals` → `202`

Requer scope CRYPTO_WRITE e o header Idempotency-Key.

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"
  }'

Campo	Regra
`amountBrl`	Reais em centavos. Sai do saldo da loja; a taxa é descontada dele.
`pixKey`	Qualquer chave Pix. O provedor confere no DICT se a chave pertence ao documento do dono (a própria chave CPF/CNPJ; nas outras, o `recipientDocument` ou, sem ele, o documento da empresa). Recusa: `422 pix_key_not_owned`.
`pixKeyType`	`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `RANDOM`.
`recipientDocument`	Opcional. CPF ou CNPJ (com ou sem máscara) do dono de uma chave e-mail, telefone ou aleatória de outra pessoa. Ignorado em chave CPF/CNPJ. Inválido: `400`. Faz parte do corpo da idempotência.

Campos desconhecidos no corpo são recusados com 400. Limite: 30 pedidos por minuto (429).

Resposta (202):

{
  "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-15T13:02:11.481Z",
  "paidAt": null
}

Campo	O que é
`amountBrl`	Valor pedido.
`grossUsdc`	USDC que sai do saldo da loja.
`fee`	Taxa em centavos, descontada do valor. A empresa recebe cerca de `amountBrl − fee`.
`netUsdc`	USDC enviado no Pix, cotado em `rate`.
`pixKey`	Chave mascarada; a chave inteira nunca volta na API.
`deliveredBrl`	O que chegou na conta. Preenchido quando o saque é pago.

O mínimo é o mesmo do pagamento ao cliente: amountBrl − fee precisa ser de pelo menos R$ 10,00 (422 amount_below_minimum).

Antes do cadastro cripto da loja

Sem o cadastro aprovado, a resposta é 409 merchant_wallet_not_ready com o status do cadastro e os links. Nada é reservado. Ver Cadastro cripto da loja.

`GET /crypto/withdrawals/:withdrawalId` → `200`

Requer scope CRYPTO_READ. Mesmo formato da resposta acima, com o status atual. De outra empresa ou inexistente → 404 withdrawal_not_found.

`GET /crypto/withdrawals` → `200`

Requer scope CRYPTO_READ. Do mais recente para o mais antigo, paginado por cursor.

Query	Tipo	Regras
`limit`	int	1 a 100, padrão `31`
`cursor`	uuid	`nextCursor` da página anterior
`status`	enum	`PROCESSING`, `PAID`, `FAILED` ou `REVIEW`

{ "items": [ { "withdrawalId": "5c1e9a7d-…", "status": "PAID", "amountBrl": 10000, "…": "…" } ], "nextCursor": null }

Fluxo

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant P as Provedor cripto
  participant E as Conta da empresa
  S->>G: POST /crypto/withdrawals + Idempotency-Key
  G->>P: confere o cadastro cripto da loja
  G->>G: reserva o valor no saldo da loja
  G-->>S: 202 PROCESSING + webhook crypto.withdrawal.processing
  G->>P: USDC (valor − taxa) para a conta da empresa no provedor
  G->>P: Pix da conta da empresa para a chave informada
  P->>E: Pix em reais
  G-->>S: webhook crypto.withdrawal.paid (deliveredBrl)

Se o Pix não sai ou volta, o USDC retorna e a reserva volta inteira para o saldo, sem taxa: chega crypto.withdrawal.failed.

Status	Significado	Saldo
`PROCESSING`	Em andamento.	Valor reservado.
`PAID`	Pix entregue.	Valor sai do saldo.
`FAILED`	Não foi possível pagar.	Reserva devolvida, sem taxa.
`REVIEW`	Em análise pelo suporte.	Valor segue reservado até a análise.

Passo a passo com webhooks: Guia › Cripto: sacar o saldo da loja.

Sacar o saldo da loja

GET /crypto/withdrawals/quote → 200

POST /crypto/withdrawals → 202