TypeScript SDK Quickstart

bun add @pagouai/api-sdk

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

const client = new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	environment: "sandbox",
	timeoutMs: 30_000,
	maxRetries: 2,
	telemetry: true,
});

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

export function createPagouClient() {
	return new Client({
		apiKey: process.env.PAGOU_API_KEY!,
		environment: process.env.NODE_ENV === "production" ? "production" : "sandbox",
		timeoutMs: 30_000,
		maxRetries: 2,
	});
}

new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	auth: { scheme: "bearer" },
});

new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	auth: { scheme: "basic" },
});

new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	auth: { scheme: "api_key_header", headerName: "apiKey" },
});

const client = new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	environment: "production",
});

const client = new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	baseUrl: "https://api-sandbox.pagou.ai",
});

const client = new Client({
	apiKey: process.env.PAGOU_API_KEY!,
	userAgent: "MerchantBackend/1.0 (+https://merchant.example)",
	fetch: fetch,
});

const transaction = await client.transactions.retrieve("tr_123", {
	requestId: "req_debug_123",
	timeoutMs: 10_000,
});

const refunded = await client.transactions.refund(
	"tr_123",
	{ amount: 500, reason: "requested_by_customer" },
	{ idempotencyKey: "idem_refund_tr_123_1" },
);

const response = await client.transactions.retrieve("tr_123");

console.log(response.data.status);
console.log(response.meta.status);
console.log(response.meta.requestId);

const page = await client.transactions.list({ page: 1, limit: 20 });

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

const created = await client.transactions.create(
	{
		external_ref: "order_1001",
		amount: 1500,
		currency: "BRL",
		method: "pix",
		buyer: {
			name: "Ada Lovelace",
			email: "ada@example.com",
			document: { type: "CPF", number: "12345678901" },
		},
		products: [{ name: "Starter order", price: 1500, quantity: 1 }],
	},
	{
		idempotencyKey: "idem_order_1001",
		requestId: "req_order_1001",
	},
);

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

const cardPayment = await client.transactions.create(
	{
		external_ref: "order_1002",
		amount: 2490,
		currency: "BRL",
		method: "credit_card",
		token: "pgct_token_from_browser",
		installments: 1,
		buyer: {
			name: "Ada Lovelace",
			email: "ada@example.com",
			document: { type: "CPF", number: "12345678901" },
		},
		products: [{ name: "Plan upgrade", price: 2490, quantity: 1 }],
	},
	{ idempotencyKey: "idem_order_1002" },
);

console.log(cardPayment.data.status);

for await (const transaction of client.transactions.listAutoPagingIterator({
	limit: 100,
	status: ["pending", "paid"],
})) {
	console.log(transaction.id, transaction.status);
}

for await (const transfer of client.transfers.listAutoPagingIterator({ limit: 100 })) {
	console.log(transfer.id, transfer.status);
}

async function reconcileOpenTransactions(ids: string[]) {
	for (const id of ids) {
		const response = await client.transactions.retrieve(id, {
			requestId: `reconcile_${id}`,
			timeoutMs: 10_000,
		});

		await savePaymentState({
			id: response.data.id,
			status: response.data.status,
			requestId: response.meta.requestId,
		});
	}
}

export async function createPixForOrder(orderId: string) {
	return client.transactions.create(
		{
			external_ref: orderId,
			amount: 1500,
			currency: "BRL",
			method: "pix",
			buyer: {
				name: "Ada Lovelace",
				email: "ada@example.com",
				document: { type: "CPF", number: "12345678901" },
			},
			products: [{ name: "Starter order", price: 1500, quantity: 1 }],
		},
		{ idempotencyKey: `tx_${orderId}` },
	);
}

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

try {
	await client.transactions.retrieve("tr_404");
} catch (error) {
	if (error instanceof NotFoundError) {
		console.error("Missing transaction", error.requestId);
	} else if (error instanceof RateLimitError) {
		console.error("Back off and retry", error.status, error.code);
	} else if (error instanceof NetworkError) {
		console.error("Network issue", error.message);
	} else if (
		error instanceof AuthenticationError ||
		error instanceof InvalidRequestError ||
		error instanceof ServerError
	) {
		console.error(error.message);
	} else {
		throw error;
	}
}