Transfers with the TypeScript SDK

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

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

const transfer = await client.transfers.create({
	pix_key_type: "CPF",
	pix_key_value: "12345678901",
	amount: 5000,
	description: "Payment to supplier",
	external_ref: "inv_001",
});

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

type PayoutRequest = {
	id: string;
	amount: number;
	pixKeyType: "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "EVP";
	pixKeyValue: string;
	description: string;
};

export async function createTransferForPayout(payout: PayoutRequest) {
	return client.transfers.create(
		{
			pix_key_type: payout.pixKeyType,
			pix_key_value: payout.pixKeyValue,
			amount: payout.amount,
			description: payout.description,
			external_ref: payout.id,
		},
		{ requestId: `payout_${payout.id}` },
	);
}

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

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

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

const pending = await client.transfers.list({
	page: 1,
	limit: 100,
	status: "pending",
});

const queue = pending.data.data.map((item) => ({
	id: item.id,
	status: item.status,
	amount: item.amount,
}));

const current = await client.transfers.retrieve("tf_123");

console.log(current.data.status, current.data.amount, current.data.pix_key);

const cancelled = await client.transfers.cancel(
	"tf_123",
	{ reason: "wrong recipient" },
	{ requestId: "cancel_tf_123" },
);

console.log(cancelled.data.status);

export async function cancelTransfer(id: string, reason: string) {
	return client.transfers.cancel(
		id,
		{ reason },
		{ requestId: `cancel_${id}` },
	);
}

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

const suppliers = [
	{ id: "sup_1", email: "supplier-1@example.com", amount: 12000 },
	{ id: "sup_2", email: "supplier-2@example.com", amount: 8000 },
];

for (const supplier of suppliers) {
	await client.transfers.create(
		{
			pix_key_type: "EMAIL",
			pix_key_value: supplier.email,
			amount: supplier.amount,
			description: `Settlement for ${supplier.id}`,
			external_ref: `settlement_${supplier.id}`,
		},
		{ requestId: `job_${supplier.id}` },
	);
}

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

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

export async function handleTransferWebhook(payload: { id: string; event: string }) {
	const response = await client.transfers.retrieve(payload.id, {
		requestId: `webhook_transfer_${payload.id}`,
	});

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

await client.transfers.create(
	{
		pix_key_type: "EMAIL",
		pix_key_value: "supplier@example.com",
		amount: 12500,
		description: "Settlement for invoice 2026-001",
		external_ref: "supplier_settlement_2026_001",
	},
	{
		requestId: "payout_job_2026_001",
	},
);

const unfinished = await loadTransfersNeedingReconciliation();

for (const item of unfinished) {
	const response = await client.transfers.retrieve(item.transferId);

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