AI-Assisted Integration

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.

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.

Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json

Build a checkout link flow (Pagou-hosted checkout — no card handling on your side):
1. Backend/server function only: POST /v2/checkout-links with an Authorization: Bearer <API key>
2. Body — products: { "currency": "BRL", "title": "<order>", "products": [{ "external_id": "<your id>", "name": "<name>", "price": <cents>, "quantity": <n> }] }
3. Body — value-only: { "currency": "BRL", "amount": <cents> }. Send EITHER products OR amount, never both.
4. external_id is your own product id; re-sending the same id updates that product (no duplicates).
5. Response is { "data": { "url": "<checkout url>" } } — redirect the buyer to data.url.
6. Fulfillment: update the order only after the transaction webhook (event=transaction, data.event_type) confirms payment — not on redirect.

Prices/amount are integers in cents. Keep the API key server-side (env var), never in the browser. Validate all fields against OpenAPI.

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
   For Pix Automático instead: skip step 2, send payment_method "pix_automatic" without token, and show the returned authorization.qr_code to the payer
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.unpaid, 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.

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. Run slow application work 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.

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.