CLAUDE.md Template

# Pagou Integration

This project integrates with the Pagou.ai payments API.

## API

- Sandbox: https://api-sandbox.pagou.ai
- Production: https://api.pagou.ai
- Docs: https://developer.pagou.ai

## Authentication

Pick one method:
- `Authorization: Bearer <PAGOU_API_KEY>`
- `apiKey: <PAGOU_API_KEY>` header
- Basic Auth (username=token, password=x)

## Payments

### Create Pix payment
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Customer Name",
    "email": "customer@example.com",
    "document": { "type": "CPF", "number": "12345678901" }
  }
}
```

Response includes `pix_qr_code` (base64) and `pix_code` (string).

### Create card payment
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "<token_from_payment_element>",
  "installments": 1
}
```

Card payments require Payment Element in browser to tokenize card data.

### Transaction statuses
pending → paid | expired | failed | refunded | chargedback

## Transfers (Pix Out)

```
POST /v2/transfers
{
  "pix_key_type": "EMAIL",
  "pix_key_value": "recipient@example.com",
  "amount": 1200,
  "description": "Payout description",
  "external_ref": "payout_1001"
}
```

pix_key_type: CPF, CNPJ, EMAIL, PHONE, EVP

### Transfer statuses
pending → in_analysis → processing → paid | error | cancelled

## Webhooks

### Payment event structure
```json
{
  "id": "evt_pay_1001",
  "event": "transaction",
  "data": {
    "event_type": "transaction.paid",
    "id": "tr_1001",
    "status": "paid",
    "correlation_id": "order_1001"
  }
}
```

### Transfer event structure
```json
{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "data": {
    "object": {
      "id": "po_1001",
      "status": "paid"
    }
  }
}
```

### Payment events
- transaction.created
- transaction.pending
- transaction.paid
- transaction.cancelled
- transaction.refunded
- transaction.chargedback
- transaction.three_ds_required

### Transfer events
- payout.created
- payout.in_analysis
- payout.processing
- payout.transferred
- payout.failed
- payout.canceled

## TypeScript SDK

```bash
bun add @pagouai/api-sdk
```

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

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

// Pix payment
const tx = await client.transactions.create({
  external_ref: "order_1001",
  amount: 1500,
  currency: "BRL",
  method: "pix",
});

// Transfer
const transfer = await client.transfers.create({
  pix_key_type: "EMAIL",
  pix_key_value: "recipient@example.com",
  amount: 1200,
  external_ref: "payout_1001",
});
```

## Rules

- Always include external_ref for correlation and idempotency
- Use requestId header for request tracing
- Deduplicate webhooks by event id (not transaction/transfer id)
- Reconcile on failures with GET, don't retry POST
- Cards require Payment Element - never handle raw card data
- ACK webhooks with `{ "received": true }`

## Common mistakes to avoid

- Retrying POST on failure (use GET to reconcile instead)
- Deduplicating webhooks by transaction id (same tx emits multiple events)
- Skipping external_ref (makes reconciliation impossible)
- Handling raw card numbers (use Payment Element tokens)
- Ignoring next_action for 3DS flows