> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK Quickstart

> Install and configure the official server-side TypeScript SDK, then make safe requests with response metadata, retries, and typed errors.

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](/frontend/payment-element/sdk-reference)           |
| Continue a 3D Secure browser challenge                                     | [SDK v3 Reference](/frontend/payment-element/sdk-reference#3d-secure) |

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

```bash theme={null}
bun add @pagouai/api-sdk
```

## Create a client

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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.

```ts theme={null}
new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "bearer" } });
```

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

```ts theme={null}
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:

```ts theme={null}
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

```ts theme={null}
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`.

## Read next

* [Payments with the TypeScript SDK](/sdks/typescript/payments)
* [Transfers with the TypeScript SDK](/sdks/typescript/transfers)
* [SDK v3 Reference](/frontend/payment-element/sdk-reference)