Skip to main content
O chamador parceiro (máquina-a-máquina) autentica com um de dois esquemas equivalentes: uma Bearer API key (recomendado) ou uma assinatura HMAC-SHA256. As mesmas rotas aceitam qualquer um dos dois. Separadamente, seu backend troca um identificador de usuário por um JWT de usuário final de curta duração, que libera as operações de pagamento.
As credenciais do parceiro (id do parceiro, API key ou segredo HMAC, segredo do webhook) são provisionadas pela nossa equipe no onboarding. Solicite-as em pag.finance/businesses.

​
API key (Bearer) - recomendado

Envie a chave diretamente no cabeçalho Authorization em toda requisição. Sem string canônica, sem assinatura, sem nonce, sem timestamp.
1

Gerar uma chave

Crie uma chave no dashboard (painel API e Integrações) ou via POST /api/v1/partners/me/api-keys. O valor completo sk_live_... é exibido uma única vez; guarde-o, pois não é recuperável (apenas o hash é mantido).
2

Enviar em toda requisição

Anexe a chave exatamente como recebida no cabeçalho Authorization.
3

Rotacionar ou revogar

Liste as chaves com GET /api/v1/partners/me/api-keys e revogue uma com POST /api/v1/partners/me/api-keys/:keyId/revoke (efeito imediato). Cada parceiro pode ter várias chaves, por exemplo uma por ambiente ou serviço.
Trafegue a chave sempre por HTTPS. A chave é um segredo bearer: se vazar, revogue-a. O status do parceiro (SUSPENDED ou REVOKED) e a allowlist opcional de IP continuam valendo. Uma chave inválida ou revogada retorna um 401 genérico.

​
HMAC-SHA256 - legado e avançado

Use HMAC se você já tem uma integração HMAC ou precisa de anti-replay baseado em nonce. O cabeçalho carrega o id do parceiro, um timestamp, um nonce e a assinatura.
A assinatura é calculada sobre uma string canônica com um separador de nova linha literal entre os campos:
1

Derivar a chave de assinatura

signingKey = SHA256(rawSecret + ":" + partnerId). O segredo bruto nunca trafega e nunca é armazenado: mantemos apenas SHA256(secret:partnerId). O segredo é texto puro, não base64.
2

Fazer o hash do corpo

bodyHash = SHA256_hex( JSON.stringify(JSON.parse(rawBody)) ). O corpo é normalizado antes do hash. Para um GET ou um corpo vazio, faça o hash do corpo vazio normalizado.
3

Assinar a string canônica

signature = HMAC_SHA256_hex(signingKey, canonical) (64 caracteres hex).
4

Montar o cabeçalho

HMAC-SHA256 partnerId=...,timestamp=...,nonce=...,signature=...
Janela de timestamp: 300 segundos (5 minutos); fora dela, 401. Nonce anti-replay: deduplicado no Redis por 600 segundos (10 minutos); reuso nessa janela retorna 401. Use um nonce único por requisição.

​
JWT do usuário final

As operações de pagamento (cash-out, cash-in, recibos) rodam como um usuário final, não como o parceiro. Seu backend troca o pubkey ou o uid do usuário por um JWT.

​
Emitir um token

POST /api/v1/auth/token, autenticado pelo parceiro (API key ou HMAC).
​
string
obrigatório
Credenciais do parceiro: Bearer sk_live_... ou o cabeçalho HMAC.
​
string
O endereço blockchain do usuário. Informe pubkey ou uid (ao menos um, mínimo 3 caracteres).
​
string
O id interno do usuário, como alternativa ao pubkey.
​
string
padrão:"padrão da configuração"
Override opcional de TTL, por exemplo 1h ou 7d. Limitado a 30d.
​
string
O JWT assinado (HS256). Envie-o como Authorization: Bearer <token> nas rotas protegidas.
​
string
O TTL efetivo aplicado ao token.
​
string
Sempre Bearer.
​
object
{ pubkey, kycStatus, partnerId } do usuário resolvido.
O token carrega apenas identidade (pubkey, uid, partnerId, iss). A emissão recusa um usuário BLOCKED com 403. O gate de KYC por operação (kycStatus === APPROVED) é aplicado nas rotas protegidas, não na emissão. Um token gerado por outra instância é rejeitado com 401 (o emissor é validado em toda chamada).

​
Uso do token

Inclua o JWT do usuário final no cabeçalho Authorization de toda chamada autenticada de usuário:
Em um 401, solicite um novo token em POST /api/v1/auth/token. Os tokens são de curta duração; não os armazene além do expiresIn.