Skip to main content
The PagFinance API lets you integrate cryptocurrency payments converted to local currency (PIX, boleto, and gift card), price quotes, and KYC verification.
The recommended way to consume the API is through the official SDK @pagfinance/sdk. See the SDK documentation. This reference describes the underlying REST endpoints.

​
Base URL

The API is exposed through a host that acts as a proxy (for example, a Next.js app or a dedicated BFF). The SDK points to this host via the baseUrl option.
In the future, the sandbox.brlp.io domain will exclusively host the endpoints focused on BRLP. Organize your integration with this separation in mind. See the BRLP group.

​
Environments

Sandbox

Testing environment for development and staging. Sandbox base URL.

Production

Production environment with real transactions. Production base URL.

​
Authentication

The API uses JWT token authentication in the Authorization header. The token is obtained through a challenge-response Web3 login flow (SIWS style).
1

Request challenge

POST /api/auth/challenge returns a challenge (nonce) for the given address.
2

Sign

The application signs the challenge with the user’s wallet.
3

Verify

POST /api/auth/verify receives the signature and returns the JWT token.
No private key or signing logic lives in the client API. The only proof is the wallet signature, and all validation (nonce, verification, token issuance) happens on the server. See Authentication.

​
Response envelopes

The API can return two envelope formats. The SDK normalizes both automatically.

​
Common errors

​
validation error
Malformed request or invalid parameters. The fieldErrors field details the problems per field.
​
unauthenticated
Missing, expired, or invalid JWT token. Sign in again. The SDK can sign in again automatically (auto-relogin).
​
forbidden
The authenticated user does not have permission for the resource, or the required KYC has not been completed.
​
not found
The resource does not exist (for example, a payment or receipt was not found).
​
business rule
The request is valid but violates a business rule (for example, an amount above the allowed limit).
​
rate limit
Request limit exceeded. Wait before retrying.
​
internal error
Unexpected server error. Try again or contact support.

​
Reference structure

The endpoints are grouped by resource:

Authentication

Web3 login, tokens, and OTP.

Onramp and Offramp

Assets, prices, and conversion between crypto and local currency.

Payments

Payment validation, quoting, creation, and lookup.

BRLP

Endpoints focused on BRLP, the future sandbox.brlp.io domain.

KYC

Identity verification for individuals and companies.

Webhooks

Payment and KYC event notifications.