Skip to main content
Use o @pagouai/api-sdk para integrar a API v2 com uma interface tipada, retries automáticos e tratamento de erros consistente.
Compatível com Node.js 18+, Bun e Deno.

​
Instalação

bun add @pagouai/api-sdk
# ou npm i @pagouai/api-sdk
# ou pnpm add @pagouai/api-sdk

​
Inicialização do cliente

import { Client } from "@pagouai/api-sdk";

const client = new Client({
	apiKey: "SEU_TOKEN",
	environment: "production", // padrão
	// environment: "sandbox",
	timeoutMs: 30_000,
	maxRetries: 2,
	telemetry: true,
});

​
Endpoints base

  • Produção: https://api.pagou.ai
  • Sandbox/Teste: https://api.sandbox.pagou.ai

​
Autenticação

Por padrão, o SDK usa Bearer:
  • Authorization: Bearer <token>
Você também pode configurar basic ou api_key_header (apikey). 
const client = new Client({
	apiKey: "SEU_TOKEN",
	auth: { scheme: "api_key_header", headerName: "apikey" },
});

​
Exemplos principais

​
Criar transação

Para method: "pix", buyer.document é obrigatório e buyer.document.type deve ser em caixa alta:
  • CPF
  • CNPJ
const created = await client.transactions.create({
	amount: 1500,
	currency: "BRL",
	method: "pix",
	buyer: {
		name: "Maria Silva",
		email: "[email protected]",
		document: {
			type: "CNPJ",
			number: "12345678000195",
		},
	},
	products: [{ name: "Pedido #123", price: 1500, quantity: 1 }],
});

console.log(created.data.id, created.meta.requestId);

​
Recuperar transação

const tx = await client.transactions.retrieve("id-da-transacao");
console.log(tx.data.status);

​
Listar transações com paginação (page/limit)

const page = await client.transactions.list({ page: 1, limit: 20, status: ["pending", "paid"] });

console.log(page.data.metadata.total);
console.log(page.data.data.length);

​
Atualizar transação (somente sandbox/teste)

const updated = await client.transactions.update(
	"id-da-transacao",
	{ status: "paid" },
	{ idempotencyKey: "idem-update-001" },
);

console.log(updated.data.status);

​
Iterar automaticamente por todas as páginas

for await (const tx of client.transactions.listAutoPagingIterator({ limit: 100 })) {
	console.log(tx.id);
}

​
Reembolsar transação

const refunded = await client.transactions.refund(
	"id-da-transacao",
	{ amount: 500, reason: "requested_by_customer" },
	{ idempotencyKey: "idem-refund-001" },
);

console.log(refunded.data);

​
Opções por requisição

Todos os métodos aceitam opts: 
{
	idempotencyKey?: string;
	requestId?: string;
	timeoutMs?: number;
	signal?: AbortSignal;
}

​
Retries e idempotência

O SDK aplica retry para:
  • Falhas de rede
  • 429, 500, 502, 503, 504
Regras:
  • GET/HEAD: retry automático
  • POST/PUT: retry somente quando idempotencyKey for enviado
  • Respeita Retry-After quando disponível

​
Tratamento de erros tipados

import {
	AuthenticationError,
	InvalidRequestError,
	NetworkError,
	NotFoundError,
	RateLimitError,
	ServerError,
} from "@pagouai/api-sdk";

try {
	await client.transactions.retrieve("id-inexistente");
} catch (error) {
	if (error instanceof NotFoundError) {
		console.error("Transação não encontrada", error.requestId);
	} else if (error instanceof RateLimitError) {
		console.error("Muitas requisições", error.status);
	} else if (error instanceof AuthenticationError || error instanceof InvalidRequestError || error instanceof ServerError) {
		console.error(error.message);
	} else if (error instanceof NetworkError) {
		console.error("Falha de rede", error.message);
	}
}
Os exemplos acima utilizam o caminho público /v2 da API.