API de integração — v1
API servidor-a-servidor para receber pagamentos, pagar saques e negociar cripto a partir do seu backend.
Sua credencial identifica a conta: nenhuma chamada recebe identificador de cliente, e nenhuma alcança dados de outra conta. Autentique com chave de API e assinatura HMAC — os quatro cabeçalhos estão em Autenticação.
Três coisas que economizam a primeira hora de integração:
- toda resposta tem o mesmo envelope, sucesso ou erro. Escreva sua lógica
sobre
error.code, que é estável, e não sobreerror.message, que é para humanos e pode ser reescrito; - valor monetário é string decimal, nunca número. Um float perde precisão antes mesmo de sair do seu processo, e aqui a fração perdida tem dono;
- a mesma chave é de teste ou de produção, jamais das duas. O modo é da credencial, não da chamada.
Eventos chegam por webhook assinado, com id estável entre retentativas — veja Webhooks.
Authentication
- API Key: hmacAuth
Integração servidor-a-servidor. Quatro cabeçalhos, sempre os quatro:
| cabeçalho | conteúdo |
|---|---|
X-Api-Key | o clientId da credencial |
X-Timestamp | epoch em segundos |
X-Nonce | único por chamada, até 128 caracteres |
X-Signature | HMAC-SHA256 da cadeia canônica, em hexadecimal minúsculo |
A cadeia canônica é a concatenação destas cinco partes, separadas por
\n:
MÉTODO EM MAIÚSCULAS
/caminho/da/requisicao
timestamp
nonce
sha256(corpo)
O corpo entra como resumo, não inteiro. Corpo vazio vira
sha256(""). O host fica de fora: o mesmo cliente fala com
api.marca-a.com e api.marca-b.com, e incluí-lo obrigaria a reassinar
por domínio sem ganhar nada.
Cada campo está lá porque a ausência dele abre um ataque concreto — sem
o método, um GET assinado é reenviado como DELETE; sem o caminho,
uma cobrança de R$ 10 é reenviada contra outro endpoint; sem o instante,
a mesma chamada vale para sempre; sem o nonce, ela vale dentro da janela
de tolerância; sem o corpo, troca-se o valor mantendo a assinatura.
Tolerância de 300 segundos entre X-Timestamp e o relógio do
servidor. Fora disso, 401. Sincronize o relógio do seu servidor: essa
é a causa número um de invalid_signature numa integração que já
funcionou.
O nonce é consumido: repeti-lo dentro da janela responde 401,
mesmo com assinatura correta.
Chave desconhecida e assinatura errada respondem igual
(invalid_signature). Distingui-las já revelaria quais chaves existem.
O modo (test/live) é da credencial, nunca da chamada. Chave de
teste só alcança o ambiente de teste; chave de produção, só o real.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-Signature |