.cursorrules Template

# Pagou Integration Rules

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

## API Configuration

- 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: 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

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

## Endpoint Reference

### Payments
- POST /v2/transactions - Create payment (Pix, voucher, 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

### Subscriptions
- POST /v2/subscriptions - Create subscription
- GET /v2/subscriptions - List subscriptions
- GET /v2/subscriptions/{id} - Get subscription
- PATCH /v2/subscriptions/{id} - Update subscription
- POST /v2/subscriptions/{id}/cancel - Cancel subscription

## 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
}
```

Voucher payment request:
```json
{
  "external_ref": "order_3001",
  "amount": 125000,
  "currency": "MXN",
  "method": "voucher",
  "buyer": {
    "name": "Customer Name",
    "email": "customer@example.com",
    "address": {
      "street": "Av. Paseo de la Reforma",
      "city": "Ciudad de Mexico",
      "zipCode": "06600",
      "country": "MX"
    }
  },
  "products": [{ "name": "Annual plan", "price": 125000, "quantity": 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

## Subscription Creation

Create subscriptions from the backend after the browser returns a Payment Element token:

```json
{
  "customer_id": "cus_1001",
  "token": "pgct_...",
  "amount": 4990,
  "currency": "BRL",
  "interval": "month",
  "interval_count": 1,
  "external_ref": "sub_1001"
}
```

## Status Enums

Transaction: pending, paid, expired, canceled, refused, refunded, partially_refunded, chargedback
Subscription: trialing, active, past_due, cancel_scheduled, canceled
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

Subscription events (event=subscription, concrete event in data.event_type):
- subscription.created, subscription.started, subscription.renewed
- subscription.updated, subscription.canceled, subscription.payment_failed
- subscription.past_due, subscription.trial_will_end, subscription.chargeback_received

## 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 idempotency for creates, refunds, subscription actions, transfers, and cancellations
3. Use requestId for request tracing when the API returns it
4. Deduplicate webhooks by the top-level event id
5. Route payments by event=transaction + data.event_type
6. Route subscriptions by event=subscription + data.event_type
7. Route transfers by top-level type
8. Handle 3DS by checking for next_action in card payment responses
9. Reconcile state with GET endpoints only for support, recovery, or uncertain state
10. Never use polling as the main integration flow
11. Never handle raw card numbers - use Payment Element tokens
12. ACK webhooks quickly with { "received": true }
13. Store transaction/subscription/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 - retry with backoff only when the write is idempotent

## Payment Element (Cards)

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

```js
const elements = Pagou.elements({
  publicKey: "pk_test_...",
  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
  },
});
```