Cada parceiro e cada usuário é isolado. Todas as leituras e escritas são restritas ao principal autenticado (o parceiro por trás da API key ou da assinatura HMAC, e o usuário final por trás de um JWT). Você nunca passa um id de parceiro ou de usuário no corpo para trocar de inquilino.
URL base
Todo endpoint versionado fica sob/api/v1.
Chamadas para
/api/* sem versão são redirecionadas para /api/v1/* (301 no GET, 308 no POST, PATCH e DELETE). Os webhooks de entrada dos provedores ficam fora de /api (por exemplo /webhooks/bank) e não fazem parte da superfície do parceiro.Ambientes
Não existe um host de sandbox separado. O modo de teste é ativado por configuração nas suas credenciais: o pagamento PIX de saída roda em dry-run (a intenção é registrada, mas nenhum PIX real é enviado) e o provedor de KYC aceita documentos de teste. As credenciais de sandbox (id do parceiro, API key ou segredo HMAC, os valoresx-app-* esperados e os CPF/CNPJ de teste para os cenários aprovado e rejeitado) são provisionadas pela nossa equipe.
Solicitar acesso ao sandbox
Fale com a equipe de integração para receber suas credenciais de parceiro e os dados de teste.
Autenticação
A API tem três camadas de autenticação. Veja Autenticação para o detalhe completo.Parceiro: API key (recomendado)
Authorization: Bearer sk_live_<hex>. Enviada diretamente, sem assinatura. Usada nas rotas do parceiro (/auth/token, /users/*, /partners/*).Parceiro: HMAC-SHA256 (legado)
Authorization: HMAC-SHA256 partnerId=...,timestamp=...,nonce=...,signature=.... Assinatura por requisição. Aceita nas mesmas rotas que a API key.Usuário final: JWT
Authorization: Bearer <token>. Emitido por POST /api/v1/auth/token para um usuário; obrigatório em cash-out, cash-in e recibos.Rotas públicas
Sem autenticação:
GET /getAssetPrice, GET /accepted-cryptos, POST /validate-code, verificações de saúde e resolução pública de links de pagamento.Envelopes de resposta
Respostas de sucesso usam um envelopesuccess com o payload em data. Erros retornam success: false com uma mensagem error e, em alguns casos, um code.
Limites de taxa
No estouro, a API retorna
429 com { success: false, error, retryAfter }. Respeite o retryAfter com backoff exponencial e dimensione seu cliente com um timeout de 10 a 15 segundos.
Erros comuns
erro de validação
Requisição malformada ou campo obrigatório ausente. A mensagem
error descreve o problema.não autenticado
Credenciais ausentes, expiradas ou inválidas (API key, assinatura HMAC ou JWT). A resposta é genérica e não revela se o principal existe.
proibido
O principal não é permitido: um parceiro suspenso ou revogado, um IP fora da allowlist, um usuário bloqueado ou uma operação que exige KYC aprovado (
kycStatus === APPROVED).não encontrado
O recurso não existe (por exemplo um usuário, intenção ou recibo).
concorrência
Uma operação concorrente já está em andamento para o mesmo recurso (por exemplo um segundo
cashout/intent para o mesmo quoteId, ou uma Idempotency-Key ainda em processamento).limite de taxa
Limite de taxa excedido. Aguarde
retryAfter segundos antes de tentar de novo.erro interno
Erro inesperado no servidor. A resposta carrega um
requestId para o suporte.Um provedor dependente não está configurado nesta instância (por exemplo o provedor de KYC). Retornado no momento da chamada.
Estrutura da referência
Os endpoints são agrupados por recurso:Autenticação
API key do parceiro, HMAC-SHA256 e emissão de JWT de usuário final.
Liquidação em cripto
Redes suportadas, o catálogo de ativos ao vivo, reconciliação por memo e a máquina de estados do cash-out.
Endpoints
Navegue pelos grupos da API ao vivo na barra lateral (Usuários, Parceiros, KYC, Preços, Cash-out, Cash-in, Recibos, Links). Cada endpoint tem um playground interativo gerado a partir do spec OpenAPI.
BRLP
Saque BRLP (Modo B) e a camada de precificação em BRL.
KYC
Consulta de documentos e sessões completas de onboarding.
Webhooks
Notificações de eventos de saída, registro e assinatura.