Uso e Exemplos - PagFinance

Esta página reúne exemplos práticos de uso do @pagfinance/sdk.

Endpoints públicos (sem autenticação)

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

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

// Configuração de criptos aceitas
const config = await client.assets.acceptedCryptos();

// Preço de um ativo em uma moeda fiat
const price = await client.assets.getAssetPrice({ assetId: 1, fiatCurrency: 'BRL' });

// Validação de um código de pagamento (PIX, boleto ou giftcard)
const transfer = await client.payments.validateCode({ code: '00020101...' });

Chamadas autenticadas

Forneça o token JWT obtido fora do SDK e chame endpoints protegidos:

client.setToken(tokenJWT);

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

Fluxo ponta a ponta de transação

O fluxo típico de pagamento segue três passos: cotação, criação e recibo.

Cotar

Solicite uma cotação para o pagamento desejado.

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

Criar

Crie o pagamento a partir da cotação.

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

Submeter e acompanhar

Submeta a transação e consulte o recibo.

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

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

Os campos exatos de cada requisição e resposta dependem do contrato da API. Consulte a API Reference e a Referência de Métodos para detalhes de parâmetros.

Tratamento de erros

Toda falha lança PagFinanceError, com mensagens e erros de campo já normalizados:

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);
  }
}

O PagFinanceError normaliza os dois envelopes de resposta da API ({ success, data } e { ok, error }) em uma única estrutura com messages, fieldErrors, httpStatus e code.

Exemplo executável

O pacote inclui um exemplo ponta a ponta real em examples/transaction-flow (cotação, criação e recibo) usando um TOKEN_JWT de variável de ambiente:

pnpm --filter @pagfinance/sdk build

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

Consulte o pacote oficial no npm para o código de exemplo mais recente.

​Endpoints públicos (sem autenticação)

​Chamadas autenticadas

​Fluxo ponta a ponta de transação

​Tratamento de erros

​Exemplo executável

Endpoints públicos (sem autenticação)

Chamadas autenticadas

Fluxo ponta a ponta de transação

Tratamento de erros

Exemplo executável