.cursorrules Template

# Pagou Integration Rules

This project integrates with the Pagou.ai payments API.

## API Configuration

- Sandbox: https://api-sandbox.pagou.ai
- Production: https://api.pagou.ai
- Documentation: https://developer.pagou.ai
- OpenAPI: https://developer.pagou.ai/api-reference/openapi-v2.json

## Authentication

Use one of these methods:
- Bearer token: `Authorization: Bearer <PAGOU_API_KEY>`
- API key header: `apiKey: <PAGOU_API_KEY>`
- Basic auth: username=token, password=x

## Endpoint Reference

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

### Transfers
- POST /v2/transfers - Create Pix Out transfer
- GET /v2/transfers/{id} - Get transfer
- POST /v2/transfers/{id}/cancel - Cancel transfer

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

## Payment Creation

Pix payment request:
```json
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "buyer": {
    "name": "Customer Name",
    "email": "customer@example.com",
    "document": { "type": "CPF", "number": "12345678901" }
  }
}
```

Card payment request (with Payment Element token):
```json
{
  "external_ref": "order_1001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "<token_from_payment_element>",
  "installments": 1
}
```

## Transfer Creation

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

pix_key_type values: CPF, CNPJ, EMAIL, PHONE, EVP

## Status Enums

Transaction: pending, paid, expired, failed, refunded, partially_refunded, chargedback
Transfer: pending, in_analysis, processing, paid, error, cancelled

## Webhook Events

Payment events (in data.event_type):
- transaction.created, transaction.pending, transaction.paid
- transaction.cancelled, transaction.refunded, transaction.chargedback
- transaction.three_ds_required

Transfer events (in top-level type):
- payout.created, payout.in_analysis, payout.processing
- payout.transferred, payout.failed, payout.canceled

## TypeScript SDK

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

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

## Code Rules

When writing Pagou integration code:

1. Always include external_ref in payment/transfer requests
2. Use requestId header for request tracing
3. Deduplicate webhooks by the top-level event id
4. Handle 3DS by checking for next_action in card payment responses
5. Reconcile state with GET endpoints, don't retry failed POSTs
6. Never handle raw card numbers - use Payment Element tokens
7. ACK webhooks with { "received": true }
8. Store transaction/transfer id alongside your external_ref

## Error Handling

- 400: Validation error - check request body
- 401: Invalid API key
- 404: Resource not found
- 409: Duplicate external_ref (use GET to fetch existing)
- 429: Rate limited - implement backoff
- 500+: Server error - safe to retry with idempotency key

## Payment Element (Cards)

Frontend script: https://js.pagou.ai/payments/v3.js

```js
const elements = Pagou.elements({
  publicKey: "pk_sandbox_...",
  locale: "en",
  origin: window.location.origin,
});

const card = elements.create("card", { theme: "default" });
card.mount("#card-element");

const result = await elements.submit({
  createTransaction: async (tokenData) => {
    // Call your backend with tokenData.token
  },
});
```