6. Cripto — pagar o cliente

Paga o cliente por Pix com o saldo disponível da loja. A taxa é descontada do valor: você pede amount, esse valor sai do saldo e o cliente recebe cerca de amount − fee.

Nos exemplos, a taxa de saque da loja é 1% + R$ 0,49 (R$ 0,60 em R$ 11,00).

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant C as Conta do cliente
  S->>G: GET /crypto/balance (opcional)
  S->>G: POST /crypto/payouts + Idempotency-Key
  G-->>S: 202 PROCESSING
  G-->>S: webhook crypto.payout.processing
  G->>C: Pix (cerca de amount − fee)
  G-->>S: webhook crypto.payout.paid (deliveredBrl)
  Note over G,S: se o Pix voltar: crypto.payout.failed e a reserva volta inteira

Antes de pedir

O cliente precisa estar ACTIVE.
Mínimo: amount − fee ≥ R$ 10,00. Com a taxa do exemplo, o menor pedido fica em cerca de R$ 10,60.
Limites por saque e diário da sua loja.
Saldo: available precisa cobrir o valor.

Passo 1 — Pedir

A Idempotency-Key é obrigatória: use o id do pagamento no seu sistema. A chave Pix pode ser qualquer uma: o Pix sai da conta do cliente. Se for e-mail, telefone ou aleatória de outra pessoa, mande o CPF/CNPJ do dono em recipientDocument.

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

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

amountUsdc é o USDC enviado no Pix (R$ 10,40 a 5,40 reais por USDC). Timeout ou erro de rede? Repita com a mesma Idempotency-Key e o mesmo corpo: você recebe este mesmo saque, sem pagar duas vezes.

Passo 2 — Webhooks

{
  "event": "crypto.payout.processing",
  "occurredAt": "2026-10-15T16:00:00.500Z",
  "data": {
    "payoutId": "a2ff86ec-b389-4d75-8e92-52b08740a912",
    "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
    "status": "PROCESSING",
    "amountBrl": 1100,
    "amountUsdc": "1.920000",
    "rate": "5.400000"
  }
}

De 2 a 10 minutos depois:

{
  "event": "crypto.payout.paid",
  "occurredAt": "2026-10-15T16:04:12.000Z",
  "data": {
    "payoutId": "a2ff86ec-b389-4d75-8e92-52b08740a912",
    "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
    "status": "PAID",
    "amountBrl": 1100,
    "amountUsdc": "1.920000",
    "rate": "5.400000",
    "deliveredBrl": 1037,
    "fee": 60
  }
}

deliveredBrl é o que chegou na conta do cliente: pode diferir alguns centavos de amount − fee, porque a conversão final é feita no momento do Pix.

Se o Pix não sair ou voltar:

{
  "event": "crypto.payout.failed",
  "occurredAt": "2026-10-15T16:06:30.000Z",
  "data": {
    "payoutId": "a2ff86ec-b389-4d75-8e92-52b08740a912",
    "customerId": "aaa61c8a-f702-4f02-aa16-0a803a232e0e",
    "status": "FAILED",
    "reason": "pix_failed_returned",
    "amountBrl": 1100
  }
}

A reserva volta inteira para o saldo, sem taxa. Para tentar de novo, faça um pedido novo, com outra Idempotency-Key.

Passo 3 — Consultar (reserva do webhook)

Enquanto estiver PROCESSING, consulte a cada minuto se o webhook não chegar:

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

REVIEW significa situação fora do normal em análise pela Gestão Intermediações: o valor segue reservado. Não faça outro pedido para o mesmo pagamento; aguarde crypto.payout.paid ou crypto.payout.failed.

Erros comuns

Todas as recusas abaixo acontecem antes de reservar saldo.

Resposta	Quando	O que fazer
`400 idempotency_key_required`	Sem o header ou fora do formato.	Envie `Idempotency-Key` (8 a 160 caracteres `A-Z a-z 0-9 _ -`).
`400 invalid_pix_key`	Chave não bate com o tipo.	Corrija `pixKey`/`pixKeyType`.
`403 kyc_required`	Cliente não está `ACTIVE`.	Aguarde a aprovação do cliente.
`409 idempotency_conflict`	Mesma chave com corpo diferente.	Use outra chave para outro pagamento.
`422 amount_below_minimum`	`amount − fee` abaixo de R$ 10,00.	Aumente o valor.
`422 insufficient_balance`	Saldo disponível insuficiente.	Aguarde depósitos ficarem disponíveis.
`422 limit_exceeded`	Acima do limite por saque ou diário.	Divida o valor ou peça ajuste.
`422 provider_rejected`	O provedor não aceitou a chave para o titular.	Confira a chave e, se for de outra pessoa, o `recipientDocument`.
`429`	Mais de 30 pedidos por minuto.	Espere e repita com a mesma chave.
`422 provider_cost_exceeds_fee`	A taxa da loja não cobre o custo do provedor nesse saque.	Fale com a Gestão Intermediações.
`503 provider_unavailable`	Cotação indisponível.	Repita em instantes com a mesma chave.

Referência: Pagar o cliente, Erros.