> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI-Assisted Integration
> Give AI coding agents the right Pagou docs context before they generate integration code.
Copy this prompt into any AI coding agent:
```text Pagou AI Context theme={null}
You are a senior engineer building a production Pagou integration.
Sources of truth:
- 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
- Base URLs: https://api.pagou.ai and https://api.sandbox.pagou.ai
Rules:
- Keep Pagou secret keys server-side only. Use env vars.
- Validate endpoints, fields, statuses, and webhook shapes against OpenAPI before coding.
- Do not invent undocumented endpoints, fields, 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 async.
- Route payments by event=transaction + data.event_type.
- Route subscriptions by event=subscription + data.event_type.
- Route transfers by top-level type.
- Fulfill orders, access, and payout state only from webhook-confirmed or server-reconciled state.
- Use GET polling only for reconciliation, support, or recovery. Never use polling as the main integration flow.
```
## Docs reference
`llms.txt` — find the right page quickly
`llms-full.txt` — complete offline docs
OpenAPI — endpoints, fields, webhooks
## Setup by agent
Add to `CLAUDE.md` in project root:
```markdown theme={null}
## Pagou Integration
- Sources of truth: https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
- Keep Pagou secret keys server-side only and use env vars
- Validate endpoints, fields, statuses, and webhooks against OpenAPI; do not invent undocumented fields
- Amounts in API v2 are in cents
- Always include external_ref and idempotency on writes
- Use Payment Element / SDK v3 for cards and send only pgct_ tokens to the backend
- Implement real webhooks, deduplicate by top-level id, process async, and avoid polling as the main flow
- Fulfill orders, subscriptions, and transfers only from webhook-confirmed or server-reconciled state
```
[Full CLAUDE.md template](/start-here/claude-md-template)
Add to `AGENTS.md` in project root:
```markdown theme={null}
## Pagou Integration
- Sources of truth: https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
- Keep Pagou secret keys server-side only and use env vars
- Validate endpoints, fields, statuses, and webhooks against OpenAPI; do not invent undocumented fields
- Amounts in API v2 are in cents
- Always include external_ref and idempotency on writes
- Use Payment Element / SDK v3 for cards and send only pgct_ tokens to the backend
- Implement real webhooks, deduplicate by top-level id, process async, and avoid polling as the main flow
- Fulfill orders, subscriptions, and transfers only from webhook-confirmed or server-reconciled state
```
Or run with inline context:
```bash theme={null}
codex "Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json. Build Pix checkout with backend-only Pagou calls, external_ref, webhook endpoint, event dedupe, and GET only for reconciliation."
```
Add to `.cursorrules` in project root:
```markdown theme={null}
## Pagou Integration
- Sources of truth: https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
- Keep Pagou secret keys server-side only and use env vars
- Validate endpoints, fields, statuses, and webhooks against OpenAPI; do not invent undocumented fields
- Amounts in API v2 are in cents
- Always include external_ref and idempotency on writes
- Use Payment Element / SDK v3 for cards and send only pgct_ tokens to the backend
- Implement real webhooks, deduplicate by top-level id, process async, and avoid polling as the main flow
- Fulfill orders, subscriptions, and transfers only from webhook-confirmed or server-reconciled state
```
[Full .cursorrules template](/start-here/cursorrules-template)
Paste the Pagou AI Context prompt above at the start of your chat, then ask your question. Require the agent to implement real webhooks, deduplicate events, keep secrets server-side, and avoid polling as the primary integration flow.
If the agent can't fetch URLs, paste the relevant section from [llms-full.txt](https://developer.pagou.ai/llms-full.txt) directly.
Start with this as your first message. It is strict on backend boundaries, webhooks, and documented API fields:
```text Lovable Pagou Integration Prompt theme={null}
You are a senior engineer building a production Pagou integration inside Lovable.
Use only these Pagou sources of truth:
- Full docs: https://developer.pagou.ai/llms-full.txt
- OpenAPI v2: https://developer.pagou.ai/api-reference/openapi-v2.json
- Production base URL: https://api.pagou.ai
- Sandbox base URL: https://api.sandbox.pagou.ai
Scope:
- Customers: create, list, and retrieve customers
- Transactions: Pix, voucher/local payment, card payment, list, retrieve, and refund
- Subscriptions: create, list, retrieve, update, and cancel recurring card billing
- Transfers: Pix Out creation, list, retrieve, and cancellation
- Webhooks: payment, subscription, and transfer events
- Frontend card flow: Payment Element / SDK v3 for secure tokenization
Non-negotiable rules:
- Never expose a Pagou secret API token in the browser.
- All Pagou API calls must run from a backend route, server function, or secure server action.
- Use environment variables for credentials and base URL.
- Use sandbox first. Keep the production switch configuration-only.
- Use Payment Element / SDK v3 for card collection. Send only the `pgct_` token to the backend.
- Never handle raw card numbers.
- Amounts in Pagou API v2 are in cents. Example: BRL 49.00 = `4900`.
- Always send a deterministic `external_ref` for creates and sensitive writes.
- Use idempotency for creates, refunds, subscription actions, and transfers.
- Do not invent endpoints, fields, statuses, or webhook shapes. Validate against OpenAPI first.
Webhook-first architecture:
- Implement a real webhook endpoint, not only polling.
- Return `2xx` quickly from the webhook endpoint.
- Do not run heavy business logic before responding to the webhook.
- Persist or enqueue the payload, then process it asynchronously.
- Deduplicate by the top-level webhook `id`.
- Payment events use `event: "transaction"` and the concrete event in `data.event_type`.
- Subscription events use `event: "subscription"` and the concrete event in `data.event_type`.
- Transfer events use the top-level `type`, such as `payout.transferred` or `payout.failed`.
- Use GET polling only for reconciliation, support screens, or recovery after an uncertain state. Do not use polling as the main integration flow.
Fulfillment and state:
- Never fulfill an order from a browser success message alone.
- Fulfill Pix, voucher, and card orders only after `transaction.paid` or a reconciled paid state.
- For cards, handle `next_action` / 3DS when returned.
- For voucher/local payments, instructions may arrive in the create response or later by webhook.
- For subscriptions, use webhooks for created, started, renewed, updated, canceled, payment_failed, past_due, trial_will_end, and chargeback_received events.
- For transfers, use resource status for operational state and webhook events for transitions.
Error handling:
- 4xx: fix the request or permissions. Do not retry automatically.
- 409: reconcile the existing resource before creating another one.
- 429, 5xx, timeout: retry with exponential backoff and jitter only when the write is idempotent.
- Always log `requestId` when the API returns it.
- Show safe user messages. Do not expose provider internals or secrets.
When generating code:
1. Create a clear frontend + backend/server-function architecture.
2. Keep all Pagou secrets server-side.
3. Implement the webhook endpoint and event deduplication.
4. Use webhook-confirmed or server-reconciled state for final business actions.
5. Include required environment variables.
6. Cite the endpoint used for each flow.
7. Validate request and response fields against the OpenAPI.
8. If a behavior is not documented, say it is not documented and suggest contacting Pagou support with the `requestId`.
Build: [describe the app and the Pagou flows you need]
```
Replace `[describe your app]` with what you want to build.
## One-shot prompts
Copy any of these directly into your AI agent:
```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
Build a Pix checkout flow:
1. Backend/server function only: POST /v2/transactions with method=pix, amount in cents, and external_ref
2. Frontend: display only buyer-facing Pix fields returned by the backend
3. Webhook: implement POST /webhooks/pagou, deduplicate by top-level id, route event=transaction by data.event_type
4. Fulfillment: update the order only after transaction.paid or a reconciled paid state
5. Reconciliation: use GET /v2/transactions/{id} only for recovery/support, not as the main flow
Use env vars for API keys. Never expose Pagou credentials in frontend. Validate all fields against OpenAPI.
```
```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
Build a card checkout flow:
1. Frontend: load Payment Element from https://js.pagou.ai/payments/v3.js and mount hosted card fields
2. On submit: call elements.submit(), then send only the pgct_ token to the backend
3. Backend/server function only: POST /v2/transactions with method=credit_card, amount in cents, token, installments, and external_ref
4. 3DS: if the backend response has next_action, continue the challenge through the SDK flow
5. Webhook: route event=transaction by data.event_type and update order state only after webhook or server reconciliation
6. Reconciliation: use GET /v2/transactions/{id} only after uncertain browser/network state
Use env vars for API keys. Never expose secrets or handle raw card numbers. Validate all fields against OpenAPI.
```
```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
Build a subscription billing flow:
1. Backend/server function only: create or retrieve the customer with /v2/customers
2. Frontend: use Payment Element in subscription mode and send only the pgct_ token to the backend
3. Backend: POST /v2/subscriptions with customer_id, token, amount in cents, interval, interval_count, external_ref/metadata if needed
4. Webhook: implement POST /webhooks/pagou, deduplicate by top-level id, route event=subscription by data.event_type
5. State: grant or remove access from subscription status and subscription webhooks, not browser state
6. Reconciliation: use GET /v2/subscriptions/{id} only for recovery/support or uncertain state
Handle subscription.created, subscription.started, subscription.renewed, subscription.updated, subscription.canceled, subscription.payment_failed, subscription.past_due, subscription.trial_will_end, and subscription.chargeback_received.
Use env vars for API keys. Never expose Pagou credentials in frontend. Validate all fields against OpenAPI.
```
```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
Build a webhook endpoint:
1. POST /webhooks/pagou - accept JSON body and return 200 with {"received": true} quickly
2. Persist or enqueue the raw payload before async processing
3. Deduplicate by top-level "id" field (same event can be sent multiple times)
4. Route payment events by event=transaction and data.event_type
5. Route subscription events by event=subscription and data.event_type
6. Route transfer events by top-level type, such as payout.transferred, payout.failed, payout.rejected, payout.canceled
7. Do heavy business logic in a background job, not before the HTTP response
Store processed event IDs to prevent duplicate processing. Do not use polling as the primary state update path.
```
```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json
Build a Pix Out transfer flow:
1. Backend/server function only: POST /v2/transfers with recipient Pix data, amount in cents, and external_ref
2. Webhook: route transfer events by top-level type, including payout.transferred, payout.failed, payout.rejected, and payout.canceled
3. State: update payout status from webhook/resource status, not frontend polling
4. Reconciliation: use GET /v2/transfers/{id} only if webhook processing is delayed or uncertain
5. Cancellation: POST /v2/transfers/{id}/cancel only when the current resource status allows it
Use env vars for API keys. Never expose Pagou credentials in frontend. Validate all fields against OpenAPI.
```
## Tips for agents
* Keep API keys server-side only, use env vars
* Never log card tokens or Pix keys
* Validate webhook source before processing
* Use HTTPS everywhere
* Test in sandbox first, same code works in prod
* Use ngrok to receive webhooks locally
* Always send external\_ref for idempotency
* Reconcile with GET if webhook fails
## Read next
* [TypeScript SDK Quickstart](/sdks/typescript/quickstart)
* [Accept Pix Payments](/payments/pix/accept-payments)
* [Webhooks Overview](/webhooks/overview)