Seu cliente paga um Pix, o valor vira USDC (dólar digital) e entra no saldo da sua loja. Quando você quiser pagar o cliente, o USDC sai do seu saldo e chega na conta dele como Pix. O saldo da loja também pode ser sacado por Pix para a conta da própria empresa.
| |
|---|
| Base URL | https://api.gestaotechnology.com/api |
| Autenticação | X-Api-Key: <SECRET_KEY> com scopes CRYPTO_READ e CRYPTO_WRITE |
| Moeda do saldo | USDC |
| O quê | Rota | Quando |
|---|
| Cadastrar cliente | POST /crypto/customers | Uma vez por cliente. Ele faz o KYC e ganha um Pix fixo na sua loja. |
| Receber depósito | POST /crypto/deposits (opcional) | O cliente paga o Pix fixo; o valor entra no saldo da loja. |
| Pagar o cliente | POST /crypto/payouts | Pix para a chave do cliente, com a taxa descontada do valor. |
| Sacar o saldo da loja | GET /crypto/withdrawals/quote → POST /crypto/withdrawals | Pix para a chave da própria empresa. Exige o cadastro cripto da loja. |
| Saldo | GET /crypto/balance | A qualquer momento. |
| Termo | O que é |
|---|
| Loja | A sua empresa na Gestão Intermediações. Dona do saldo USDC. |
| Cliente (pagador) | Pessoa física que deposita e recebe pagamentos. Identificada pelo CPF. |
| USDC | Moeda digital lastreada 1:1 em dólar. Valores com até 6 casas decimais, enviados como texto ("7.820000"). |
Pix fixo (brCode) | Código Pix copia e cola do cliente na sua loja. Não muda e não traz valor embutido: o cliente digita o valor. |
customerId | Id do cliente na plataforma. Onde a API pede o cliente, você também pode mandar a sua referência (externalRef). |
- Empresa ativa na Gestão Intermediações. Empresa suspensa, bloqueada ou pendente recebe
409 merchant_not_ready.
- Cripto liberado para a sua empresa. Quem libera é o administrador da plataforma. Sem isso, toda chamada responde
403 crypto_disabled.
- Chave de API secreta criada no painel, em Credenciais de API, com os scopes
CRYPTO_READ e CRYPTO_WRITE (ver Chaves e scopes). Guarde a chave no servidor; ela nunca vai para o navegador ou o app do cliente.
- Webhook cadastrado no painel, em Webhooks, com os eventos da categoria Cripto (ver Registro e Eventos).
Cadastrar clientes, receber depósitos e pagar clientes não exigem cadastro da loja no provedor cripto. Só o saque do saldo da loja exige: ver Cadastro cripto da loja.
| Assunto | Regra |
|---|
| Autenticação | Header X-Api-Key com a chave secreta em todas as chamadas. Ver Autenticação. |
| Formato | JSON. Envie Content-Type: application/json. |
| Reais | Sempre em centavos, como inteiro: R$ 10,00 = 1000. |
| USDC | Texto com 6 casas: "2.010000". Não converta para ponto flutuante. |
| Datas | ISO 8601 em UTC: 2026-10-10T17:22:51.352Z. |
| Idempotência | Os saques (/crypto/payouts e /crypto/withdrawals) exigem o header Idempotency-Key (8 a 160 caracteres A-Z a-z 0-9 _ -). Mesma chave com o mesmo corpo devolve o mesmo saque; com corpo diferente, 409. Ver Idempotência. |
| Erros | Sempre com error (código estável, use no seu código) e message (texto para pessoas). Ver Erros. |
Em verde, o que a sua aplicação chama; o resto acontece sozinho e chega para você por webhook.
flowchart TD
B["Cadastrar cliente<br/>POST /crypto/customers"]:::you --> C{"Cliente já aprovado<br/>em outra loja?"}
C -- sim --> E["Cliente ACTIVE<br/>com brCode"]
C -- não --> D["Cliente abre tosLink e kycLink<br/>e faz o KYC"]
D --> W1(["webhook crypto.customer.updated"])
W1 --> E
E --> F["Pedir depósito (opcional)<br/>POST /crypto/deposits"]:::you
F --> G["Cliente paga o Pix fixo"]
G --> H["Pix vira USDC e entra<br/>no saldo da loja"]
H --> W2(["webhook crypto.deposit.paid"])
W2 --> I["Pagar o cliente<br/>POST /crypto/payouts"]:::you
I --> W3(["webhook crypto.payout.paid"])
W2 --> J["Sacar o saldo da loja<br/>POST /crypto/withdrawals"]:::you
J --> W4(["webhook crypto.withdrawal.paid"])
classDef you fill:#0b6e66,stroke:#0b6e66,color:#ffffff
O depósito e os saques são independentes: um saque pode usar saldo de qualquer depósito anterior.
| Item | Valor |
|---|
| Depósito: Pix até o webhook | cerca de 2 minutos |
| Saque: pedido até o Pix | de 2 a 10 minutos |
| Validade do pedido de depósito | 24 horas |
| Valor mínimo de saque | O valor que chega no Pix (valor pedido menos a taxa) precisa ser de pelo menos R$ 10,00. Na prática, o mínimo é R$ 10,00 + a taxa. |
| Limite por saque e diário | Definidos por loja pela Gestão Intermediações |
- Use o webhook como fonte da verdade e a consulta (
GET) como reserva, por exemplo a cada minuto enquanto o saque estiver PROCESSING.
- Guarde o
customerId ou use a sua externalRef; ela vale em todas as chamadas.
- Mostre ao cliente que o valor recebido é aproximado até o pagamento: a conversão final é feita no momento do Pix.
- Gere a
Idempotency-Key a partir do id do saque no seu sistema, para que um reenvio nunca crie um pagamento novo.
