Início rápido do SDK para TypeScript

Use o SDK TypeScript em código confiável do lado do servidor. Não envie chaves secretas da API para o navegador.

Qual SDK devo usar?

Use o SDK TypeScript em código server-side confiável para criar pagamentos, consultar transações, emitir reembolsos e criar transferências. Use o SDK v3 de navegador pelo Payment Element quando precisar de campos hospedados de cartão em uma página de checkout.

Necessidade	Use
Criar requisições Pix, voucher, cartão, reembolso e transferência pelo back-end	SDK TypeScript
Montar campos hospedados e tokenizar cartão no navegador	Referência do SDK v3
Continuar um challenge 3D Secure no navegador	Referência do SDK v3

Requisitos

TypeScript ou JavaScript rodando no seu back-end.
Uma chave secreta da Pagou para o ambiente chamado.
Um runtime com fetch. Se seu runtime não expõe fetch global, injete uma implementação customizada nas opções do cliente.

Instalação

bun add @pagouai/api-sdk

Crie um cliente

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

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

Ambientes:

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

Você também pode informar baseUrl para testes de desenvolvimento ou proxies controlados.

Formato de resposta

Os métodos do SDK retornam { data, meta }. data é o payload da API. meta contém metadados HTTP e o request ID usado para rastreio.

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);

Primeiro 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",
    requestId: "req_order_1001",
  },
);

Opções por requisição

Todo método de recurso aceita um segundo argumento opcional:

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

Opção	Uso
`idempotencyKey`	Obrigatória para retentativas seguras em requisições `POST` e `PUT`.
`requestId`	Envia `X-Request-Id` para rastreio.
`timeoutMs`	Sobrescreve o timeout do cliente para uma requisição.
`signal`	Cancela a requisição com um `AbortSignal`.

Variações de autenticação

Bearer auth é o padrão e a configuração recomendada.

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

Use os outros modos apenas para integrações legadas ou camadas de compatibilidade:

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

Comportamento de retentativa

Retries cobrem falhas de rede e 429, 500, 502, 503, 504.
GET e HEAD repetem automaticamente.
POST e PUT só repetem quando você define idempotencyKey.
A quantidade padrão de retentativas é 2.
O timeout padrão é 30_000 ms.

Defina chaves de idempotência em qualquer pagamento, reembolso, transferência ou cancelamento que possa ser repetido:

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

Tratamento de erros

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("Transação não encontrada", error.requestId);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit atingido", error.status, error.requestId);
  } else if (error instanceof ApiError) {
    console.error(error.status, error.code, error.requestId, error.details);
  } else {
    throw error;
  }
}

Erros exportados pelo SDK incluem AuthenticationError, PermissionError, RateLimitError, InvalidRequestError, NotFoundError, ConflictError, ServerError e NetworkError.

Escolha um SDK

TypeScript no back-end

Início rápido do SDK para TypeScript

Qual SDK devo usar?

Requisitos

Instalação

Crie um cliente

Formato de resposta

Primeiro pagamento Pix

Opções por requisição

Variações de autenticação

Comportamento de retentativa

Tratamento de erros

Leia a seguir

​Qual SDK devo usar?

​Requisitos

​Instalação

​Crie um cliente

​Formato de resposta

​Primeiro pagamento Pix

​Opções por requisição

​Variações de autenticação

​Comportamento de retentativa

​Tratamento de erros

​Leia a seguir

Qual SDK devo usar?

Requisitos

Instalação

Crie um cliente

Formato de resposta

Primeiro pagamento Pix

Opções por requisição

Variações de autenticação

Comportamento de retentativa

Tratamento de erros

Leia a seguir