Pular para o conteúdo principal
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.

​
Métodos do recurso

MétodoOperação da APIUso
client.transactions.create(params, opts?)POST /v2/transactionsCriar 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/transactionsListar 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}/refundReembolsar uma transação.
client.transactions.listAutoPagingIterator(params?, opts?)Helper de cursorIterar todos os itens entre páginas.

​
Criar um pagamento Pix

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. 
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 específicos de provedor como boleto, spei, webpay ou mercadopago. A API recebe voucher e escolhe o meio de pagamento local a partir da configuração de pagamento da empresa, 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. 
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.

​
Consultar e reconciliar

const current = await client.transactions.retrieve("tr_1001", {
  requestId: "reconcile_tr_1001",
  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

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

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

const refunded = await client.transactions.refund(
  "tr_1001",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_tr_1001_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. 
const updated = await client.transactions.update(
  "tr_1001",
  { status: "paid" },
  { idempotencyKey: "update_tr_1001_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: 
{
  "success": true,
  "requestId": "req_3002",
  "data": [],
  "next_cursor": "cursor_next",
  "prev_cursor": null,
  "total": 120
}