> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments with the TypeScript SDK

> Create Pix, voucher, and card transactions, retrieve and list by cursor, run sandbox updates, and refund safely with the TypeScript SDK.

Use these examples when your service owns payment creation, retrieval, and refund logic.

All examples assume a configured `client` from the [TypeScript SDK Quickstart](/sdks/typescript/quickstart).

## Resource methods

| Method                                                       | API operation                      | Use                                                            |
| ------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------- |
| `client.transactions.create(params, opts?)`                  | `POST /v2/transactions`            | Create 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/transactions`             | List 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}/refund` | Refund a transaction.                                          |
| `client.transactions.listAutoPagingIterator(params?, opts?)` | Cursor helper                      | Iterate every item across pages.                               |

## Create a Pix payment

```ts theme={null}
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.

```ts theme={null}
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 local option names such as `boleto`, `spei`, `webpay`, or `mercadopago`. The API receives `voucher` and selects an available local payment option from the account 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.

```ts theme={null}
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](/frontend/payment-element/sdk-reference).

## Retrieve and reconcile

```ts theme={null}
const current = await client.transactions.retrieve("018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f", {
  requestId: "reconcile_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
const refunded = await client.transactions.refund(
  "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f_1" },
);
```

For retry-safe refunds, always set a stable `idempotencyKey`.

## Update sandbox transaction status

`transactions.update(...)` is intended for test/sandbox flows.

```ts theme={null}
const updated = await client.transactions.update(
  "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  { status: "paid" },
  { idempotencyKey: "update_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f_paid" },
);
```

## Response shape

Create, retrieve, update, and refund methods return `{ data, meta }`.

List methods return `{ data, meta }`, where `data` is a cursor envelope:

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": [],
  "next_cursor": "cursor_next",
  "prev_cursor": null,
  "total": 120
}
```