Skip to main content
Use these examples when your service owns payment creation, retrieval, and refund logic. All examples assume a configured client from the TypeScript SDK Quickstart.

​
Resource methods

MethodAPI operationUse
client.transactions.create(params, opts?)POST /v2/transactionsCreate Pix, voucher, card, or other supported payment methods.
client.transactions.retrieve(id, opts?)GET /v2/transactions/{id}Read the current transaction state.
client.transactions.list(params?, opts?)GET /v2/transactionsList transactions with cursor pagination and filters.
client.transactions.update(id, params, opts?)PUT /v2/transactions/{id}Update a sandbox/test transaction status.
client.transactions.refund(id, params?, opts?)PUT /v2/transactions/{id}/refundRefund a transaction.
client.transactions.listAutoPagingIterator(params?, opts?)Cursor helperIterate every item across pages.

​
Create a Pix payment

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: "tx_order_1001" },
);

console.log(created.data.id, created.data.status, created.meta.requestId);
amount and product price are in cents.

​
Create a voucher payment

Use method: "voucher" for Boleto in Brazil, SPEI or bank transfer in Mexico, Mercado Pago or local voucher options in Argentina, Webpay in Chile, PSE in Colombia, and other configured country-specific payment instructions. 
const voucherPayment = await client.transactions.create(
  {
    external_ref: "order_3001",
    amount: 125000,
    currency: "MXN",
    method: "voucher",
    buyer: {
      name: "Ada Lovelace",
      email: "ada@example.com",
      document: { type: "CURP", number: "LOLA800101MDFXXX09" },
      address: {
        street: "Av. Paseo de la Reforma",
        city: "Ciudad de Mexico",
        zipCode: "06600",
        country: "MX",
      },
    },
    products: [{ name: "Annual plan", price: 125000, quantity: 1 }],
    notify_url: "https://example.com/webhooks/pagou",
  },
  { idempotencyKey: "tx_order_3001" },
);

console.log(voucherPayment.data.voucher?.url);
console.log(voucherPayment.data.voucher?.digitable_line);
Do not pass provider-specific method names such as boleto, spei, webpay, or mercadopago. The API receives voucher and chooses the local payment option from the company’s payment setup, currency, and country. The normalized voucher object can include barcode, digitable_line, url, expiration_date, instructions, and receipt_url. These fields are nullable because each local payment option returns a different instruction format.

​
Create a card payment from a Payment Element token

Use the browser SDK v3 to collect card details and send only the resulting pgct_* token to your backend. 
const cardPayment = await client.transactions.create(
  {
    external_ref: "order_2001",
    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: "tx_order_2001" },
);

console.log(cardPayment.data.status);
Never send raw card data through the TypeScript SDK. Browser card collection belongs in SDK v3 Reference.

​
Retrieve and reconcile

const current = await client.transactions.retrieve("tr_1001", {
  requestId: "reconcile_tr_1001",
  timeoutMs: 10_000,
});

console.log(current.data.status);
Use retrieve calls for reconciliation, admin views, and delayed payment-state checks. Fulfillment should still rely on webhooks or server-side reconciliation, not browser status alone.

​
List with filters

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

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

if (page.data.next_cursor) {
  const nextPage = await client.transactions.list({
    cursor: page.data.next_cursor,
    direction: "next",
    limit: 50,
  });
}
Supported list filters include id, paymentMethods, status, deliveryStatus, installments, name, email, documentNumber, phone, and traceable.

​
List with auto-pagination

for await (const item of client.transactions.listAutoPagingIterator({ limit: 100 })) {
  console.log(item.id, item.status);
}
Use auto-pagination for batch jobs and exports. Use list(...) directly when you need to expose next_cursor, prev_cursor, or total to your own UI.

​
Refund safely

const refunded = await client.transactions.refund(
  "tr_1001",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_tr_1001_1" },
);
For retry-safe refunds, always set a stable idempotencyKey.

​
Update sandbox transaction status

transactions.update(...) is intended for test/sandbox flows. 
const updated = await client.transactions.update(
  "tr_1001",
  { status: "paid" },
  { idempotencyKey: "update_tr_1001_paid" },
);

​
Response shape

Create, retrieve, update, and refund methods return { data, meta }. List methods return { data, meta }, where data is a cursor envelope: 
{
  "success": true,
  "requestId": "req_3002",
  "data": [],
  "next_cursor": "cursor_next",
  "prev_cursor": null,
  "total": 120
}