Usage and Examples - PagFinance

This page gathers practical usage examples for @pagfinance/sdk.

Public endpoints (no authentication)

import { PagFinanceClient } from '@pagfinance/sdk';

const client = new PagFinanceClient({
  baseUrl: 'https://app.pag.finance',
  clientId: 'my-app',
  appMeta: { name: 'my-app', version: '1.0.0', domain: 'myapp.com' },
  defaultBlockchain: 'solana',
});

// Accepted crypto configuration
const config = await client.assets.acceptedCryptos();

// Price of an asset in a fiat currency
const price = await client.assets.getAssetPrice({ assetId: 1, fiatCurrency: 'BRL' });

// Validation of a payment code (PIX, boleto, or gift card)
const transfer = await client.payments.validateCode({ code: '00020101...' });

Authenticated calls

Provide the JWT token obtained outside the SDK and call protected endpoints:

client.setToken(tokenJWT);

const me = await client.user.me();

End-to-end transaction flow

The typical payment flow has three steps: quote, creation, and receipt.

Quote

Request a quote for the desired payment.

const quote = await client.payments.quote({
  code: '00020101...',
  assetId: 1,
  blockchain: 'solana',
});

Create

Create the payment from the quote.

const payment = await client.payments.create({
  quoteId: quote.id,
});

Submit and track

Submit the transaction and fetch the receipt.

await client.payments.submit({ paymentId: payment.id, txHash: '...' });

const receipt = await client.receipts.get({
  type: 'pix',
  tx: payment.id,
  chain: 'solana',
});

The exact fields of each request and response depend on the API contract. See the API Reference and the Method Reference for parameter details.

Error handling

Every failure throws PagFinanceError, with messages and field errors already normalized:

import { PagFinanceError } from '@pagfinance/sdk';

try {
  await client.payments.quote(req);
} catch (e) {
  if (e instanceof PagFinanceError) {
    console.error(e.messages, e.fieldErrors, e.httpStatus);
  }
}

PagFinanceError normalizes the two API response envelopes ({ success, data } and { ok, error }) into a single structure with messages, fieldErrors, httpStatus, and code.

Runnable example

The package includes a real end-to-end example in examples/transaction-flow (quote, creation, and receipt) using a TOKEN_JWT environment variable:

pnpm --filter @pagfinance/sdk build

PAGFINANCE_BASE_URL=https://app.pag.finance \
PAGFINANCE_CLIENT_ID=example \
TOKEN_JWT=... \
PAYMENT_CODE='00020101...' \
SENDER_WALLET=7NaNvh... \
npx tsx examples/transaction-flow/index.ts

See the official package on npm for the most recent example code.

​Public endpoints (no authentication)

​Authenticated calls

​End-to-end transaction flow

​Error handling

​Runnable example

Public endpoints (no authentication)

Authenticated calls

End-to-end transaction flow

Error handling

Runnable example