Skip to main content
A API do PagFinance permite integrar pagamentos com criptomoedas convertidos para moeda local (PIX, boleto e giftcard), cotações de preço e verificação de KYC.
A forma recomendada de consumir a API é através do SDK oficial @pagfinance/sdk. Consulte a documentação da SDK. Esta referência descreve os endpoints REST subjacentes.

​
Base URL

A API é exposta através de um host que atua como proxy (por exemplo, um app Next.js ou um BFF dedicado). O SDK aponta para esse host via a opção baseUrl.
O domínio sandbox.brlp.io passará, no futuro, a hospedar exclusivamente os endpoints focados no BRLP. Organize sua integração já considerando essa separação. Veja o grupo BRLP.

​
Ambientes

Sandbox

Ambiente de testes para desenvolvimento e homologação. Base URL de sandbox.

Produção

Ambiente de produção com transações reais. Base URL de produção.

​
Autenticação

A API usa autenticação por token JWT no cabeçalho Authorization. O token é obtido por um fluxo de login Web3 do tipo challenge-response (estilo SIWS).
1

Solicitar desafio

POST /api/auth/challenge retorna um desafio (nonce) para o endereço informado.
2

Assinar

A aplicação assina o desafio com a carteira do usuário.
3

Verificar

POST /api/auth/verify recebe a assinatura e retorna o token JWT.
Nenhuma chave privada ou lógica de assinatura vive na API cliente. A única prova é a assinatura da carteira, e toda a validação (nonce, verificação, emissão do token) ocorre no servidor. Consulte Autenticação.

​
Envelopes de resposta

A API pode retornar dois formatos de envelope. O SDK normaliza ambos automaticamente.

​
Erros comuns

​
400 Bad Request
erro de validação
Requisição malformada ou parâmetros inválidos. O campo fieldErrors detalha os problemas por campo.
​
401 Unauthorized
não autenticado
Token JWT ausente, expirado ou inválido. Refaça o login. O SDK pode refazer o login automaticamente (auto-relogin).
​
403 Forbidden
sem permissão
O usuário autenticado não tem permissão para o recurso, ou o KYC exigido não foi concluído.
​
404 Not Found
não encontrado
Recurso inexistente (por exemplo, pagamento ou recibo não encontrado).
​
422 Unprocessable Entity
regra de negócio
A requisição é válida, mas viola uma regra de negócio (por exemplo, valor acima do limite permitido).
​
429 Too Many Requests
limite de taxa
Limite de requisições excedido. Aguarde antes de repetir.
​
500 Internal Server Error
erro interno
Erro inesperado no servidor. Tente novamente ou contate o suporte.

​
Organização da referência

Os endpoints estão agrupados por recurso:

Autenticação

Login Web3, tokens e OTP.

Onramp e Offramp

Ativos, preços e conversão entre cripto e moeda local.

Pagamentos

Validação, cotação, criação e consulta de pagamentos.

BRLP

Endpoints focados no BRLP, futuro domínio sandbox.brlp.io.

KYC

Verificação de identidade de pessoa física e jurídica.

Webhooks

Notificações de eventos de pagamento e KYC.