Skip to main content
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.
NeedUse
Create Pix, voucher, card, refund, and transfer requests from your backendTypeScript SDK
Mount hosted card fields and tokenize card details in the browserSDK v3 Reference
Continue a 3D Secure browser challengeSDK 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:
EnvironmentBase URL
productionhttps://api.pagou.ai
sandboxhttps://api.sandbox.pagou.ai
You can also pass baseUrl for internal 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("tr_1001", {
  requestId: "reconcile_tr_1001",
  timeoutMs: 10_000,
  signal: abortController.signal,
});
OptionUse
idempotencyKeyRequired for safe retries on POST and PUT requests.
requestIdSends X-Request-Id for tracing.
timeoutMsOverrides the client timeout for one request.
signalCancels 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(
  "tr_1001",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_tr_1001_1" },
);

​
Error handling

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

try {
  const transaction = await client.transactions.retrieve("tr_missing");
  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.