Skip to main content

​
Create a Pix transaction

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

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

const response = 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 }],
});

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

​
Create a Pix transaction from an order service

type Order = {
	id: string;
	total: number;
	customerName: string;
	customerEmail: string;
	customerDocument: string;
};

export async function createPixForOrder(order: Order) {
	return client.transactions.create(
		{
			external_ref: order.id,
			amount: order.total,
			currency: "BRL",
			method: "pix",
			buyer: {
				name: order.customerName,
				email: order.customerEmail,
				document: { type: "CPF", number: order.customerDocument },
			},
			products: [{ name: `Order ${order.id}`, price: order.total, quantity: 1 }],
		},
		{ idempotencyKey: `tx_${order.id}` },
	);
}

​
Create a card transaction from a frontend token

const cardTransaction = await client.transactions.create(
	{
		external_ref: "order_1002",
		amount: 2490,
		currency: "BRL",
		method: "credit_card",
		token: "pgct_token_from_payment_element",
		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_create_order_1002" },
);

console.log(cardTransaction.data.status);

​
Persist the result of a create call

const created = await client.transactions.create(
	{
		external_ref: "order_1003",
		amount: 990,
		currency: "BRL",
		method: "pix",
		buyer: {
			name: "Grace Hopper",
			email: "grace@example.com",
			document: { type: "CPF", number: "12345678901" },
		},
		products: [{ name: "Addon", price: 990, quantity: 1 }],
	},
	{ idempotencyKey: "idem_order_1003" },
);

await saveOrderPayment({
	orderId: "order_1003",
	transactionId: String(created.data.id),
	status: created.data.status,
	requestId: created.meta.requestId,
});

​
Retrieve by ID

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

console.log(transaction.data.status, transaction.data.amount);

​
List transactions with filters

const page = await client.transactions.list({
	page: 1,
	limit: 20,
	status: ["pending", "paid"],
	paymentMethods: ["pix"],
	email: "ada@example.com",
});

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

for (const item of page.data.data) {
	console.log(item.id, item.status, item.payment.method);
}

​
Fetch only open Pix transactions for operations

const openPixPage = await client.transactions.list({
	page: 1,
	limit: 50,
	status: ["pending"],
	paymentMethods: ["pix"],
});

const rows = openPixPage.data.data.map((item) => ({
	id: item.id,
	status: item.status,
	amount: item.amount,
	method: item.payment.method,
}));

console.table(rows);

​
Iterate every page automatically

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

​
Update a sandbox transaction

const updated = await client.transactions.update(
	"tr_123",
	{ status: "paid" },
	{ idempotencyKey: "idem_update_tr_123_paid" },
);

console.log(updated.data.status);

​
Move a sandbox payment through a test scenario

await client.transactions.update(
	"tr_sandbox_1",
	{ status: "processing" },
	{ idempotencyKey: "idem_tr_sandbox_1_processing" },
);

await client.transactions.update(
	"tr_sandbox_1",
	{ status: "paid" },
	{ idempotencyKey: "idem_tr_sandbox_1_paid" },
);

​
Refund a transaction

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

console.log(refunded.data.amount_refunded, refunded.data.is_full_refund);

​
Full refund helper

export async function refundFullTransaction(transactionId: string) {
	return client.transactions.refund(
		transactionId,
		{ reason: "requested_by_customer" },
		{ idempotencyKey: `refund_full_${transactionId}` },
	);
}

​
Reconcile after webhook uncertainty

async function reconcileTransaction(id: string) {
	const response = await client.transactions.retrieve(id, {
		timeoutMs: 10_000,
	});

	return {
		id: response.data.id,
		status: response.data.status,
		requestId: response.meta.requestId,
	};
}

​
Webhook consumer pattern with retrieve fallback

export async function handleTransactionWebhook(payload: { id: string; event: string }) {
	const current = await client.transactions.retrieve(payload.id, {
		requestId: `webhook_${payload.id}`,
	});

	await savePaymentState({
		id: current.data.id,
		status: current.data.status,
		event: payload.event,
		requestId: current.meta.requestId,
	});
}

​
Persist request correlation data

const result = await client.transactions.create({
	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 }],
});

await db.insert({
	pagouTransactionId: String(result.data.id),
	pagouRequestId: result.meta.requestId,
	status: result.data.status,
});

​
Nightly reconciliation export

const stale: Array<{ transactionId: string }> = await loadPaymentsNeedingReconciliation();

for (const item of stale) {
	const current = await client.transactions.retrieve(item.transactionId);

	await appendSettlementRow({
		transactionId: current.data.id,
		status: current.data.status,
		requestId: current.meta.requestId,
	});
}