Depósito

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

`POST /crypto/deposits` → `201`

Requer scope CRYPTO_WRITE.

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

Campo	Regra
`customerId`	Id ou `externalRef` do cliente. Precisa estar `ACTIVE`.
`amount`	Reais em centavos.

Resposta (201):

{
  "depositIntentId": "610784d8-baa6-4daa-91c6-a45a16303c4a",
  "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
  "brCode": "00020126670014br.gov.bcb.pix…6304EAAC",
  "amount": 2000,
  "expiresAt": "2026-10-11T15:24:13.157Z"
}

Mostre o brCode como QR Code ou copia e cola e peça para o cliente pagar exatamente o valor. O pedido vale 24 horas. Se o cliente ainda não foi aprovado, a resposta é 403 kyc_required com o status e os links.

Como o Pix recebido é casado com o pedido

`match`	Quando
`EXACT`	Valor igual ao pedido em aberto.
`PARTIAL`	Valor menor que o pedido.
`OVERPAID`	Valor maior que o pedido.
`UNREQUESTED`	Não havia pedido em aberto. O depósito entra do mesmo jeito.

Em todos os casos o valor recebido é creditado. O match serve para você conciliar.

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant C as Cliente
  participant P as Provedor cripto
  S->>G: POST /crypto/deposits (amount)
  G-->>S: brCode + depositIntentId
  S->>C: mostra QR / copia e cola
  C->>P: paga o Pix
  P->>P: converte reais em USDC (carteira do cliente)
  P-->>G: aviso de USDC recebido
  G-->>S: webhook crypto.deposit.paid (saldo pendente)
  G->>P: move o USDC para o caixa da plataforma
  G->>G: saldo pendente vira disponível (taxa descontada)

Leva por volta de 2 minutos entre o Pix e o webhook crypto.deposit.paid. O webhook chega quando o valor entra como saldo pendente; alguns minutos depois ele passa a disponível, já com a taxa descontada. Essa passagem não gera outro webhook: acompanhe pelo state em GET /crypto/deposits ou pelo saldo.

O provedor cripto fica com a parte dele na conversão do Pix para USDC: o amountUsdc já vem líquido desse custo. A taxa da loja (fee, em centavos) é calculada sobre o valor do Pix em reais.

`GET /crypto/deposits/intents/:depositIntentId` → `200`

Requer scope CRYPTO_READ.

{
  "depositIntentId": "610784d8-baa6-4daa-91c6-a45a16303c4a",
  "status": "PAID",
  "amount": 2000,
  "expiresAt": "2026-10-11T15:24:13.157Z",
  "depositId": "11fcaddc-29b8-4353-a756-4073d8ec82d0"
}

Status do pedido: OPEN aguardando, PAID casado com um Pix, EXPIRED passou de 24 h.

`GET /crypto/deposits` → `200`

Requer scope CRYPTO_READ.

Query	Tipo	Regras
`customerId`	string	Filtra por cliente (id ou `externalRef`)
`from`, `to`	string (ISO 8601)	Intervalo de datas
`limit`	int	1 a 100, default `50`

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

netUsdc é o USDC que entrou no seu saldo disponível (amountUsdc menos a taxa da loja); só vem preenchido em SETTLED, nos demais estados é null.

Estados do depósito

stateDiagram-v2
  [*] --> CONFIRMED: Pix convertido em USDC (saldo pendente)
  CONFIRMED --> SETTLING: movendo para o caixa da plataforma
  SETTLING --> SETTLED: saldo disponível
  CONFIRMED --> REVIEW: situação fora do normal
  SETTLING --> REVIEW: situação fora do normal
  REVIEW --> SETTLED: resolvido pelo suporte
  SETTLED --> REFUNDED: Pix devolvido ao cliente

Em CONFIRMED e SETTLING o valor aparece como saldo pending; em SETTLED, available (ver Saldo e taxas). Devoluções geram o webhook crypto.deposit.refunded.

REVIEW é tratado pela equipe da Gestão Intermediações (por exemplo, quando a taxa configurada é maior que o valor recebido, ou a conversão demora além do prazo). O valor não fica disponível até a análise; você não precisa fazer nada além de acompanhar.

Passo a passo com webhooks: Guia › Cripto: receber depósito.