Pagar o cliente

Paga o cliente por Pix com o USDC do saldo da loja. Você informa o valor em reais; a plataforma converte pela cotação do momento. A taxa é descontada do valor, como no saque Pix: o valor pedido sai do seu saldo e o cliente recebe cerca de valor − taxa.

POST /crypto/payouts → 202

Requer scope CRYPTO_WRITE e o header Idempotency-Key.

Pagar o cliente

curl -X POST https://api.gestaotechnology.com/api/crypto/payouts \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pagamento-98765" \
  -d '{
    "customerId": "cliente-42",
    "amount": 1100,
    "pixKey": "12345678901",
    "pixKeyType": "CPF"
  }'

Campo	Regra
customerId	Id ou externalRef do cliente. Precisa estar ACTIVE.
amount	Reais em centavos. Sai do seu saldo; a taxa é descontada dele. Respeita o limite por saque e o diário da sua loja.
pixKey	Qualquer chave Pix: o Pix sai da conta do cliente no provedor, e 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 CPF do cliente). Recusa do provedor: 422 provider_rejected.
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.

Limite: 30 pedidos por minuto (429). Sem saldo, 422 insufficient_balance antes de qualquer chamada ao provedor.

Resposta (202):

{
  "payoutId": "a2ff86ec-b389-4d75-8e92-52b08740a912",
  "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
  "status": "PROCESSING",
  "amountBrl": 1100,
  "amountUsdc": "1.920000",
  "chargedUsdc": "2.000000",
  "rate": "5.400000",
  "deliveredBrl": null,
  "fee": 60,
  "approximate": true,
  "createdAt": "2026-10-10T17:22:51.352Z",
  "paidAt": null
}

Campo	O que é
amountBrl	Valor pedido (sai do saldo da loja).
fee	Taxa em centavos, descontada do valor. O cliente recebe cerca de amountBrl − fee.
amountUsdc	USDC enviado no Pix, cotado em rate (reais por USDC).
chargedUsdc	USDC que sai do saldo da loja: amountUsdc mais a taxa em USDC. Também vem nos webhooks crypto.payout.*.
deliveredBrl	O que de fato chegou na conta do cliente. Preenchido quando o saque é pago.

Valor mínimo

O valor que chega no Pix (amount − fee) precisa ser de pelo menos R$ 10,00. Abaixo disso a resposta é 422 amount_below_minimum; se a taxa consome todo o valor, 422 WITHDRAW_FEE_EXCEEDS_AMOUNT. Nos dois casos nada é reservado.

O valor entregue pode diferir alguns centavos

approximate: true indica que a conversão final é feita pelo provedor no momento do Pix. No exemplo, R$ 11,00 pedidos com R$ 0,60 de taxa: o cliente recebe cerca de R$ 10,40.

Repetir com segurança

Se a chamada der timeout, repita com a mesma Idempotency-Key e o mesmo corpo: você recebe o mesmo saque, sem pagar duas vezes. Use uma chave nova só para um saque novo. Ver Idempotência.

GET /crypto/payouts/:payoutId → 200

Requer scope CRYPTO_READ. Mesmo formato da resposta acima, com o status atual.

Consultar pagamento

curl -s https://api.gestaotechnology.com/api/crypto/payouts/a2ff86ec-b389-4d75-8e92-52b08740a912 \
  -H "X-Api-Key: <SECRET_KEY>"

Fluxo

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant P as Provedor cripto
  participant C as Conta do cliente
  S->>G: POST /crypto/payouts + Idempotency-Key
  G->>G: confere cliente, chave, mínimo, limite e cotação
  G->>G: reserva o valor no saldo da loja
  G-->>S: 202 PROCESSING
  G-->>S: webhook crypto.payout.processing
  G->>P: envia o USDC (valor − taxa) e pede o Pix
  P->>C: Pix em reais
  G-->>S: webhook crypto.payout.paid (deliveredBrl)

Normalmente de 2 a 10 minutos. Se o Pix não sai ou volta, o USDC retorna e a reserva volta inteira para o saldo da loja, sem taxa: chega crypto.payout.failed.

Status do pagamento

Status	Significado	Saldo
PROCESSING	Em andamento.	Valor reservado.
PAID	Pix entregue. deliveredBrl e paidAt preenchidos.	Valor sai do saldo.
FAILED	Não foi possível pagar. O webhook traz o motivo.	Reserva devolvida, sem taxa.
REVIEW	Situação fora do normal, em análise pelo suporte.	Valor segue reservado até a análise.

Passo a passo com webhooks: Guia › Cripto: pagar o cliente.