Template CLAUDE.md

# Integração Pagou

Este projeto integra com a API de pagamentos Pagou.ai.

## API

- Sandbox: https://api-sandbox.pagou.ai
- Produção: https://api.pagou.ai
- Docs: https://developer.pagou.ai

## Autenticação

Escolha um método:
- `Authorization: Bearer <PAGOU_API_KEY>`
- Header `apiKey: <PAGOU_API_KEY>`
- Basic Auth (username=token, password=x)

## Pagamentos

### Criar pagamento Pix
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Nome do Cliente",
    "email": "cliente@example.com",
    "document": { "type": "CPF", "number": "12345678901" }
  }
}
```

Resposta inclui `pix_qr_code` (base64) e `pix_code` (string).

### Criar pagamento com cartão
```
POST /v2/transactions
{
  "external_ref": "order_1001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "<token_do_payment_element>",
  "installments": 1
}
```

Pagamentos com cartão requerem Payment Element no navegador para tokenizar dados do cartão.

### Status de transações
pending → paid | expired | failed | refunded | chargedback

## Transferências (Pix Out)

```
POST /v2/transfers
{
  "pix_key_type": "EMAIL",
  "pix_key_value": "destinatario@example.com",
  "amount": 1200,
  "description": "Descrição do pagamento",
  "external_ref": "payout_1001"
}
```

pix_key_type: CPF, CNPJ, EMAIL, PHONE, EVP

### Status de transferências
pending → in_analysis → processing → paid | error | cancelled

## Webhooks

### Estrutura de evento de pagamento
```json
{
  "id": "evt_pay_1001",
  "event": "transaction",
  "data": {
    "event_type": "transaction.paid",
    "id": "tr_1001",
    "status": "paid",
    "correlation_id": "order_1001"
  }
}
```

### Estrutura de evento de transferência
```json
{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "data": {
    "object": {
      "id": "po_1001",
      "status": "paid"
    }
  }
}
```

### Eventos de pagamento
- transaction.created
- transaction.pending
- transaction.paid
- transaction.cancelled
- transaction.refunded
- transaction.chargedback
- transaction.three_ds_required

### Eventos de transferência
- payout.created
- payout.in_analysis
- payout.processing
- payout.transferred
- payout.failed
- payout.canceled

## SDK TypeScript

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

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

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

## Regras

- Sempre incluir external_ref para correlação e idempotência
- Usar header requestId para rastreamento de requisições
- Deduplicar webhooks por id do evento (não da transação/transferência)
- Reconciliar em falhas com GET, não fazer retry de POST
- Cartões requerem Payment Element - nunca manipular dados brutos do cartão
- Confirmar webhooks com `{ "received": true }`

## Erros comuns a evitar

- Fazer retry de POST em falha (usar GET para reconciliar)
- Deduplicar webhooks por id da transação (mesma tx emite múltiplos eventos)
- Pular external_ref (impossibilita reconciliação)
- Manipular números de cartão brutos (usar tokens do Payment Element)
- Ignorar next_action em fluxos 3DS