AI-Assisted Integration

# Pagou.ai Payment Gateway API

> Brazilian payment gateway. Pix collections, credit card payments (via Payment Element),
> Pix Out transfers (payouts), and webhooks through a REST API (v2).
> SDK: @pagouai/api-sdk (TypeScript/Node).

## Environments
- Sandbox: https://api-sandbox.pagou.ai
- Production: https://api.pagou.ai
- Docs: https://docs.pagou.ai

## Authentication
Pick one method for all requests:
- `Authorization: Bearer <token>` (recommended)
- `apiKey: <token>` header
- Basic Auth (username: `token`, password: `x`)

## Core Endpoints

### Transactions (payments)
- POST   /v2/transactions          — Create Pix or card payment
- GET    /v2/transactions          — List transactions
- GET    /v2/transactions/{id}     — Get transaction
- PUT    /v2/transactions/{id}/refund — Refund transaction

### Customers
- POST   /v2/customers             — Create customer
- GET    /v2/customers             — List customers
- GET    /v2/customers/{id}        — Get customer

### Transfers (payouts)
- POST   /v2/transfers             — Create Pix Out transfer
- GET    /v2/transfers             — List transfers
- GET    /v2/transfers/{id}        — Get transfer
- POST   /v2/transfers/{id}/cancel — Cancel transfer

## Create a Pix Payment

```bash
curl -X POST https://api-sandbox.pagou.ai/v2/transactions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "order_1001",
    "amount": 1500,
    "currency": "BRL",
    "method": "pix",
    "notify_url": "https://merchant.example/webhooks/pagou",
    "buyer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "document": { "type": "CPF", "number": "12345678901" }
    },
    "products": [{ "name": "Order", "price": 1500, "quantity": 1 }]
  }'
```

## Create a Card Payment
Use Payment Element (hosted iframe) for card input. Browser tokenizes the card,
then your backend calls POST /v2/transactions with the token:

```json
{
  "external_ref": "order_1002",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "pgct_token_from_browser",
  "installments": 1,
  "buyer": { ... },
  "products": [{ ... }]
}
```

## Create a Pix Out Transfer

```json
POST /v2/transfers
{
  "external_ref": "payout_9001",
  "amount": 1200,
  "currency": "BRL",
  "pix_key": "merchant@example.com",
  "recipient_name": "Ada Lovelace"
}
```

## Idempotency
Use `external_ref` as your stable idempotency key for creates.
Reuse the same value on retries for the same logical operation.
Conflicting duplicates return 409.

## Transaction Statuses
pending, processing, paid, captured, authorized, three_ds_required,
partially_paid, refunded, partially_refunded, canceled, expired,
refused, chargedback, processed, in_protest

Terminal: paid, captured, refunded, partially_refunded, canceled, expired, refused

## Transfer Statuses
created, pending, in_analysis, processing, transferred,
failed, rejected, canceled, unknown

Terminal: transferred, failed, rejected, canceled

## Webhook Events
Payment: transaction.created, transaction.pending, transaction.paid,
  transaction.cancelled, transaction.refunded, transaction.partially_refunded,
  transaction.chargedback, transaction.three_ds_required
Transfer: payout.created, payout.in_analysis, payout.processing,
  payout.transferred, payout.failed, payout.rejected, payout.canceled

## Webhook Envelopes

Payment envelope:
```json
{ "id": "...", "event": "transaction", "data": { "id": "tr_...", "event_type": "transaction.paid", "status": "paid", "amount": 1500 } }
```

Transfer envelope:
```json
{ "id": "evt_...", "type": "payout.transferred", "data": { "object": { "id": "po_...", "status": "paid", "amount": 10000 } } }
```

## TypeScript SDK

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

const client = new Client({
  apiKey: process.env.PAGOU_API_KEY,
  environment: "sandbox", // or "production"
});

// Create Pix payment
const tx = await client.transactions.create({
  external_ref: "order_1001",
  amount: 1500,
  currency: "BRL",
  method: "pix",
  buyer: { name: "Ada", email: "ada@example.com", document: { type: "CPF", number: "12345678901" } },
  products: [{ name: "Order", price: 1500, quantity: 1 }],
}, { idempotencyKey: "idem_order_1001" });

// Retrieve
const fetched = await client.transactions.retrieve("tr_123");

// List with auto-pagination
for await (const t of client.transactions.listAutoPagingIterator({ limit: 100 })) {
  console.log(t.id, t.status);
}

// Transfer
const transfer = await client.transfers.create({ external_ref: "po_001", amount: 1200, currency: "BRL", pix_key: "email@example.com" });
```

## Key Integration Patterns
- Acknowledge webhooks with 200 immediately, process async via queue
- Deduplicate by webhook event ID
- Reconcile with GET /v2/transactions/{id} or GET /v2/transfers/{id} when state is uncertain
- Store external_ref + Pagou resource ID + requestId
- Use notify_url (transactions) or postback_url (transfers) for per-request callbacks

## Error Handling
- 400: fix request — 401/403: fix credentials — 404: verify ID
- 409: reconcile with existing resource — 422: fix field validation
- 5xx: retry with backoff, then reconcile
- RFC 7807 problem+json errors with field-level detail