Skip to main content
Use these examples when your service owns payment creation, retrieval, and refund logic.

​
Underlying API request example

{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix"
}

​
Underlying API response example

{
  "success": true,
  "requestId": "req_3002",
  "data": {
    "id": "tr_1001",
    "status": "pending"
  }
}

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

​
Create a card payment from a Payment Element token

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

​
Retrieve and reconcile

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

​
Refund

const refunded = await client.transactions.refund(
  "tr_1001",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_tr_1001_1" },
);

​
List with auto-pagination

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