TypeScript SDK Quickstart

Use the TypeScript SDK from trusted server-side code. Do not ship secret API keys to the browser.

Which SDK should I use?

Use the TypeScript SDK in trusted server-side code to create payments, retrieve transactions, issue refunds, and create transfers. Use the browser SDK v3 through Payment Element when you need hosted card fields in a checkout page.

Need	Use
Create Pix, voucher, card, refund, and transfer requests from your backend	TypeScript SDK
Mount hosted card fields and tokenize card details in the browser	SDK v3 Reference
Continue a 3D Secure browser challenge	SDK v3 Reference

Requirements

TypeScript or JavaScript running on your backend.
A Pagou secret key for the environment you are calling.
A runtime with fetch. If your runtime does not expose global fetch, inject a custom implementation in the client options.

Install

bun add @pagouai/api-sdk

Create a client

import { Client } from "@pagouai/api-sdk";

const client = new Client({
  apiKey: process.env.PAGOU_API_KEY!,
  environment: "sandbox",
  timeoutMs: 30_000,
  maxRetries: 2,
});

Environments:

Environment	Base URL
`production`	`https://api.pagou.ai`
`sandbox`	`https://api.sandbox.pagou.ai`

You can also pass baseUrl for development tests or controlled proxies.

Response shape

SDK methods return { data, meta }. data is the API payload. meta contains HTTP metadata and the request ID used for tracing.

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

console.log(created.data.id);
console.log(created.data.status);
console.log(created.meta.requestId);

First 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 }],
  },
  {
    idempotencyKey: "tx_order_1001",
    requestId: "req_order_1001",
  },
);

Request options

Every resource method accepts an optional second argument:

await client.transactions.retrieve("018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f", {
  requestId: "reconcile_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  timeoutMs: 10_000,
  signal: abortController.signal,
});

Option	Use
`idempotencyKey`	Required for safe retries on `POST` and `PUT` requests.
`requestId`	Sends `X-Request-Id` for tracing.
`timeoutMs`	Overrides the client timeout for one request.
`signal`	Cancels the request with an `AbortSignal`.

Auth variants

Bearer auth is the default and recommended setup.

new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "bearer" } });

Use the other schemes only for legacy integrations or compatibility layers:

new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "basic" } });
new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "api_key_header", headerName: "apiKey" } });

Retry behavior

Retries cover network failures and 429, 500, 502, 503, 504.
GET and HEAD retry automatically.
POST and PUT retry only when you set idempotencyKey.
Default retry count is 2.
Default timeout is 30_000 ms.

Set idempotency keys on any payment, refund, transfer, or cancel request that may be retried:

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

Error handling

import { ApiError, NotFoundError, RateLimitError } from "@pagouai/api-sdk";

try {
  const transaction = await client.transactions.retrieve("018f1f2e-7b99-7c9a-8d3e-1a2b3c4d5e99");
  console.log(transaction.data.status);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Transaction not found", error.requestId);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited", error.status, error.requestId);
  } else if (error instanceof ApiError) {
    console.error(error.status, error.code, error.requestId, error.details);
  } else {
    throw error;
  }
}

Exported SDK errors include AuthenticationError, PermissionError, RateLimitError, InvalidRequestError, NotFoundError, ConflictError, ServerError, and NetworkError.

Choose an SDK

Server-side TypeScript

Which SDK should I use?

Requirements

Install

Create a client

Response shape

First Pix payment

Request options

Auth variants

Retry behavior

Error handling

Read next

​Which SDK should I use?

​Requirements

​Install

​Create a client

​Response shape

​First Pix payment

​Request options

​Auth variants

​Retry behavior

​Error handling

​Read next

Which SDK should I use?

Requirements

Install

Create a client

Response shape

First Pix payment

Request options

Auth variants

Retry behavior

Error handling

Read next