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

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.

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.