Convenções
Valores, IDs, paginação, idempotência e erros.
Valores
Valores monetários são inteiros na menor unidade da moeda (centavos).
| Na API | Moeda | Valor |
|---|---|---|
1000000 | BRL | R$ 10.000,00 |
182765 | USD | US$ 1.827,65 |
100000 | USDT | 1.000,00 USDT |
Taxas de câmbio (exchangeRate, effectiveRate) são strings decimais com seis casas, por exemplo "0.184020". Datas seguem ISO 8601 em UTC.
IDs
IDs são opacos e têm prefixo por recurso: cus_ cliente, kya_ atestação, aud_ auditoria, rcv_ conta de destino, quo_ cotação, trf_ transferência, whe_ endpoint de webhook, evt_ evento, req_ requisição.
Paginação
Listagens devolvem data e nextCursor. Para a próxima página, envie cursor. limit aceita de 1 a 100.
Idempotência
POST /v1/transfers e POST /v1/transfers/{transferId}/refund exigem o header Idempotency-Key. Repetir a chamada nunca duplica um pagamento nem um reembolso.
| Situação | Resposta |
|---|---|
| Primeira chamada | 201 |
| Mesma chave, mesmo corpo | A mesma resposta, com Idempotent-Replayed: true |
| Mesma chave, corpo diferente | 409 IDEMPOTENCY_CONFLICT |
| Sem a chave | 400 IDEMPOTENCY_KEY_REQUIRED |
Gere um UUID por operação, grave-o antes da chamada e reutilize-o em toda nova tentativa.
Erros
Todo erro tem o mesmo formato:
{
"error": {
"code": "QUOTE_EXPIRED",
"message": "A cotação expirou. Gere uma nova cotação e tente de novo.",
"requestId": "req_c57158228f0bfc9d"
}
}Trate pelo code. Informe o requestId ao suporte.
| HTTP | code | O que fazer |
|---|---|---|
| 400 | VALIDATION_ERROR, IDEMPOTENCY_KEY_REQUIRED | Corrija a requisição |
| 401 | UNAUTHORIZED | Verifique a API key |
| 403 | FORBIDDEN | Escopo, IP ou ambiente incorretos |
| 404 | NOT_FOUND | O recurso não existe neste ambiente |
| 409 | IDEMPOTENCY_CONFLICT, TRANSFER_NOT_CANCELLABLE, TRANSFER_NOT_REFUNDABLE | Não repita a operação |
| 422 | KYC_ATTESTATION_REQUIRED | Envie a atestação KYC do cliente |
| 422 | INVALID_ATTESTATION_SIGNATURE | Confira a chave de assinatura |
| 422 | QUOTE_EXPIRED | Cote de novo e mostre o novo valor |
| 422 | ROUTE_UNAVAILABLE | Tente outro rail ou mais tarde |
| 429 | RATE_LIMITED | Aguarde o tempo de Retry-After |
| 5xx | PROVIDER_ERROR, INTERNAL_ERROR | Repita com a mesma Idempotency-Key |
Repita apenas timeouts, 429 e 5xx, com backoff exponencial.
Versionamento
A versão é uma data (2026-10-01) e vem em todo webhook. Mudanças incompatíveis só entram em uma nova versão, com aviso prévio.