5. Cripto — receber depósito

O cliente deposita pagando o Pix fixo dele (brCode). Pedir o depósito antes é opcional, mas recomendado: o Pix recebido fica ligado ao seu pedido e você recebe o id dele no webhook.

Nos exemplos, a taxa de depósito da loja é 1% + R$ 0,50.

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant C as Cliente
  S->>G: POST /crypto/deposits (opcional)
  G-->>S: 201 depositIntentId + brCode
  S->>C: mostra o QR do brCode
  C->>G: paga R$ 40 no Pix
  Note over G: Pix vira USDC (cerca de 2 min)
  G-->>S: webhook crypto.deposit.paid (saldo pendente)
  Note over G: alguns minutos depois: pendente vira disponível
  S->>G: GET /crypto/deposits ou GET /crypto/balance

Passo 1 — Pedir o depósito (opcional)

Pedir depósito

curl -X POST https://api.gestaotechnology.com/api/crypto/deposits \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -d '{ "customerId": "cliente-42", "amount": 4000 }'

201

{
  "depositIntentId": "610784d8-baa6-4daa-91c6-a45a16303c4a",
  "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
  "brCode": "00020126580014br.gov.bcb.pix…6304E81E",
  "amount": 4000,
  "expiresAt": "2026-10-16T15:30:00.000Z"
}

Cliente ainda não aprovado: 403 kyc_required com o status (e os links, se a sua loja iniciou o KYC). O pedido vale 24 horas.

Passo 2 — Cliente paga o Pix fixo

Mostre o brCode como QR Code e copia e cola, e peça para o cliente pagar o valor combinado, da conta dele. Se o Pix sair de uma conta com outro CPF, o depósito entra do mesmo jeito, mas o webhook traz senderMismatch: true: use o sinal na sua análise de risco.

Valor mínimo do depósito

Depósitos abaixo de cerca de R$ 30 (aproximadamente US$ 5) podem ser devolvidos automaticamente pelo provedor para a conta de quem pagou, sem custo. Nesse caso nada é creditado na sua loja. Oriente seus clientes a depositar a partir desse valor.

Passo 3 — Webhook crypto.deposit.paid

Chega por volta de 2 minutos depois do Pix, quando o valor entra no saldo como pendente:

POST no seu webhook

{
  "event": "crypto.deposit.paid",
  "occurredAt": "2026-10-15T15:33:10.000Z",
  "data": {
    "depositId": "11fcaddc-29b8-4353-a756-4073d8ec82d0",
    "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
    "depositIntentId": "610784d8-baa6-4daa-91c6-a45a16303c4a",
    "amountBrl": 4000,
    "amountUsdc": "7.820000",
    "match": "EXACT",
    "fee": 90,
    "senderMismatch": false
  }
}

Campo	O que é
amountBrl	O Pix recebido, em centavos.
amountUsdc	USDC que chegou, já sem a parte do provedor na conversão.
fee	Taxa da loja em centavos (1% de R$ 40 + R$ 0,50 = R$ 0,90). Descontada quando o valor fica disponível.
match	EXACT, PARTIAL (pagou menos), OVERPAID (pagou mais) ou UNREQUESTED (sem pedido em aberto). O valor recebido é creditado em todos os casos.

Deduplique por depositId.

Passo 4 — Pendente vira disponível

Alguns minutos depois o depósito é liquidado e o saldo passa de pending para available, já com a taxa descontada. Não há outro webhook para essa passagem; se você precisa do saldo disponível antes de pagar, consulte:

Depósitos do cliente

curl -s "https://api.gestaotechnology.com/api/crypto/deposits?customerId=cliente-42&limit=10" \
  -H "X-Api-Key: <SECRET_KEY>"

200

{
  "data": [
    {
      "depositId": "11fcaddc-29b8-4353-a756-4073d8ec82d0",
      "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
      "depositIntentId": "610784d8-baa6-4daa-91c6-a45a16303c4a",
      "state": "SETTLED",
      "match": "EXACT",
      "amountBrl": 4000,
      "amountUsdc": "7.820000",
      "createdAt": "2026-10-15T15:33:09.802Z"
    }
  ]
}

state	Saldo
CONFIRMED, SETTLING	pending
SETTLED	available (taxa descontada)
REVIEW	Em análise pela Gestão Intermediações; não fica disponível até a análise.
REFUNDED	Pix devolvido ao cliente; chega crypto.deposit.refunded.

Ou o saldo direto: GET /crypto/balance → { "currency": "USDC", "available": "…", "pending": "…", "reserved": "…" }.

O que pode acontecer

Situação	O que você vê	O que fazer
Conversão demorando	Nenhum webhook depois de alguns minutos	Aguarde; se passar do prazo, o depósito entra em REVIEW e a Gestão Intermediações acompanha com o provedor.
Taxa maior que o valor recebido	Depósito em REVIEW	A Gestão Intermediações decide; revise a taxa ou o valor mínimo que você aceita.
Depósito abaixo de cerca de R$ 30	Nenhum crédito; o Pix volta ao pagador	Nada a reverter. Peça ao cliente um novo Pix a partir de R$ 30.
Pix devolvido depois do crédito	crypto.deposit.refunded	Reverta o crédito no seu sistema.

Próximo: Pagar o cliente. Referência: Depósito.