Pular para o conteúdo principal
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.
NecessidadeUse
Criar requisições Pix, voucher, cartão, reembolso e transferência pelo back-endSDK TypeScript
Montar campos hospedados e tokenizar cartão no navegadorReferência do SDK v3
Continuar um challenge 3D Secure no navegadorReferê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:
AmbienteBase URL
productionhttps://api.pagou.ai
sandboxhttps://api.sandbox.pagou.ai
Você também pode informar baseUrl para testes internos 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("tr_1001", {
  requestId: "reconcile_tr_1001",
  timeoutMs: 10_000,
  signal: abortController.signal,
});
OpçãoUso
idempotencyKeyObrigatória para retentativas seguras em requisições POST e PUT.
requestIdEnvia X-Request-Id para rastreio.
timeoutMsSobrescreve o timeout do cliente para uma requisição.
signalCancela 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(
  "tr_1001",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_tr_1001_1" },
);

​
Tratamento de erros

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("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.

​
Leia a seguir