> ## 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.

# Pagamentos com o SDK TypeScript

> Crie transações Pix, voucher e cartão, consulte e liste por cursor, rode updates de sandbox e reembolse com segurança usando o SDK TypeScript.

Use estes exemplos quando o seu serviço for dono da criação, consulta e reembolso de pagamentos.

Todos os exemplos assumem um `client` configurado a partir do [Início rápido do SDK para TypeScript](/pt/sdks/typescript/quickstart).

## Métodos do recurso

| Método                                                       | Operação da API                    | Uso                                                      |
| ------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------- |
| `client.transactions.create(params, opts?)`                  | `POST /v2/transactions`            | Criar Pix, voucher, cartão ou outros métodos suportados. |
| `client.transactions.retrieve(id, opts?)`                    | `GET /v2/transactions/{id}`        | Ler o estado atual da transação.                         |
| `client.transactions.list(params?, opts?)`                   | `GET /v2/transactions`             | Listar transações com paginação por cursor e filtros.    |
| `client.transactions.update(id, params, opts?)`              | `PUT /v2/transactions/{id}`        | Atualizar status de uma transação de sandbox/teste.      |
| `client.transactions.refund(id, params?, opts?)`             | `PUT /v2/transactions/{id}/refund` | Reembolsar uma transação.                                |
| `client.transactions.listAutoPagingIterator(params?, opts?)` | Helper de cursor                   | Iterar todos os itens entre páginas.                     |

## Criar um pagamento Pix

```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` e `price` dos produtos são em centavos.

## Criar um pagamento por voucher

Use `method: "voucher"` para Boleto no Brasil, SPEI ou transferência bancária no México, Mercado Pago ou vouchers locais na Argentina, Webpay no Chile, PSE na Colômbia e outros meios locais configurados por país.

```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: "Cidade do Mexico",
        zipCode: "06600",
        country: "MX",
      },
    },
    products: [{ name: "Plano anual", 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);
```

Não envie nomes de opções locais como `boleto`, `spei`, `webpay` ou `mercadopago`. A API recebe `voucher` e seleciona um meio local disponível a partir da configuração da conta, moeda e país.

O objeto normalizado `voucher` pode incluir `barcode`, `digitable_line`, `url`, `expiration_date`, `instructions` e `receipt_url`. Esses campos são nullable porque cada meio de pagamento local retorna um formato diferente de instrução.

## Criar um pagamento com cartão a partir de um token do Payment Element

Use o SDK v3 de navegador para coletar os dados do cartão e envie apenas o token `pgct_*` resultante para o seu back-end.

```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);
```

Nunca envie dados brutos de cartão pelo SDK TypeScript. A coleta de cartão no navegador pertence à [Referência do SDK v3](/pt/frontend/payment-element/sdk-reference).

## Consultar e reconciliar

```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 consultas para reconciliação, telas administrativas e checagens atrasadas de estado. Fulfillment ainda deve depender de webhooks ou reconciliação server-side, não apenas do estado do navegador.

## Listar com filtros

```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,
  });
}
```

Filtros suportados incluem `id`, `paymentMethods`, `status`, `deliveryStatus`, `installments`, `name`, `email`, `documentNumber`, `phone` e `traceable`.

## Listar com paginação automática

```ts theme={null}
for await (const item of client.transactions.listAutoPagingIterator({ limit: 100 })) {
  console.log(item.id, item.status);
}
```

Use paginação automática para jobs de lote e exportações. Use `list(...)` diretamente quando precisar expor `next_cursor`, `prev_cursor` ou `total` na sua própria interface.

## Reembolsar com segurança

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

Para retentativas seguras de reembolso, sempre defina uma `idempotencyKey` estável.

## Atualizar status de transação em sandbox

`transactions.update(...)` é destinado a fluxos de teste/sandbox.

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

## Formato de resposta

Métodos de criação, consulta, atualização e reembolso retornam `{ data, meta }`.

Métodos de listagem retornam `{ data, meta }`, em que `data` é um envelope com cursor:

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