Pagamentos com 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.

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

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

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("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

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(
  "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.

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:

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

Escolha um SDK

TypeScript no back-end

Métodos do recurso

Criar um pagamento Pix

Criar um pagamento por voucher

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

Consultar e reconciliar

Listar com filtros

Listar com paginação automática

Reembolsar com segurança

Atualizar status de transação em sandbox

Formato de resposta

​Métodos do recurso

​Criar um pagamento Pix

​Criar um pagamento por voucher

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

​Consultar e reconciliar

​Listar com filtros

​Listar com paginação automática

​Reembolsar com segurança

​Atualizar status de transação em sandbox

​Formato de resposta

Métodos do recurso

Criar um pagamento Pix

Criar um pagamento por voucher

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

Consultar e reconciliar

Listar com filtros

Listar com paginação automática

Reembolsar com segurança

Atualizar status de transação em sandbox

Formato de resposta