CLAUDE.md Template

# Pagou Integration

This project integrates with the Pagou.ai API for payments, subscriptions, transfers, and webhooks.

## API

- Sandbox: https://api.sandbox.pagou.ai
- Production: https://api.pagou.ai
- Fast docs: https://developer.pagou.ai/llms.txt
- Full docs: https://developer.pagou.ai/llms-full.txt
- OpenAPI v2: https://developer.pagou.ai/api-reference/openapi-v2.json

## Authentication

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

Keep secret keys server-side only. Use environment variables. Never expose a Pagou secret key in the browser.

## Core rules

- Validate endpoints, fields, statuses, and webhook shapes against OpenAPI before coding
- Do not invent undocumented endpoints, fields, statuses, or flows
- Amounts in API v2 are in cents
- Always include `external_ref` and idempotency on writes
- Use Payment Element / SDK v3 for cards; send only `pgct_` tokens to the backend
- Implement real webhooks, deduplicate by top-level event id, and process asynchronously
- Use GET polling only for reconciliation, support, or recovery, never as the primary flow

## 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 | canceled | refused | refunded | partially_refunded | chargedback

## Subscriptions

Create recurring card billing from the backend after the browser returns a Payment Element token:

```
POST /v2/subscriptions
{
  "customer_id": "018f1f2e-7b46-7c9a-8d3e-1a2b3c4d5e73",
  "token": "pgct_...",
  "amount": 4990,
  "currency": "BRL",
  "interval": "month",
  "interval_count": 1,
  "external_ref": "sub_1001"
}
```

Use subscription webhooks to grant, renew, pause, or remove access. Reconcile uncertain state with `GET /v2/subscriptions/{id}`.

### Subscription statuses
trialing → active | past_due | cancel_scheduled | canceled

## 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": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "paid",
    "correlation_id": "order_1001"
  }
}
```

### Transfer event structure
```json
{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "data": {
    "object": {
      "id": "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
      "status": "paid"
    }
  }
}
```

### Subscription event structure
```json
{
  "id": "evt_sub_1001",
  "event": "subscription",
  "data": {
    "event_type": "subscription.created",
    "id": "018f1f2e-7b47-7c9a-8d3e-1a2b3c4d5e74",
    "status": "active",
    "customer_email": "customer@example.com"
  }
}
```

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

### Subscription events
- subscription.created
- subscription.started
- subscription.renewed
- subscription.updated
- subscription.canceled
- subscription.payment_failed
- subscription.past_due
- subscription.trial_will_end
- subscription.chargeback_received

### 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` for request tracing when the API returns it
- Deduplicate webhooks by top-level event id, not transaction, subscription, or transfer id
- Route payments by `event="transaction"` + `data.event_type`
- Route subscriptions by `event="subscription"` + `data.event_type`
- Route transfers by top-level `type`
- Reconcile uncertain states with GET; do not use polling as the main integration flow
- Cards require Payment Element; never handle raw card data
- ACK webhooks quickly with `{ "received": true }`

## Common mistakes to avoid

- Retrying POST on failure (use GET to reconcile instead)
- Deduplicating webhooks by resource id (same resource emits multiple events)
- Skipping external_ref (makes reconciliation impossible)
- Handling raw card numbers (use Payment Element tokens)
- Ignoring next_action for 3DS flows
- Updating order, access, or payout state from browser success instead of webhook-confirmed or server-reconciled state