Pagbank

PagBank AI Developer Skill

Guia de referência para integrações robustas e em conformidade com padrões financeiros do ecossistema PagBank (REST, OpenAPI).

Integration routing

Read reference.md before answering domain-specific questions. Use examples.md for request/response patterns and security.md before recommending production code, webhook handlers, card flows, OAuth Connect, mTLS transfers, or credential storage.

Critical rules

1. PCI: Never send raw card data to merchant servers. Use PagBank SDK for client-side encryption and tokenization (Transparent Checkout v4.1).
2. Webhooks: Treat notifications as hints only. Always GET the resource from PagBank API before updating internal state (idempotency).
3. Transfer API: Configure mTLS with digital certificates before calling transfer endpoints.
4. Connect Challenge (2FA): RSA 2048-bit keys — public in X.509 SPKI, private in PKCS8. Decrypt Base64 challenge with OAEP/MGF1/SHA-256; token expires in 30 seconds.
5. Split math: FIXED mode — sum of receiver amounts = order total. PERCENTAGE mode — sum of percentages = 100%.
6. Boleto percentages: Send as integers (real_value × 100). Fine 1–9999 (0.01%–99.99%), interest 1–5999 (0.01%–59.99%), discounts 1–9999 with date ≤ due date.
7. Token rotation: Generating a new static token invalidates the previous one immediately. Production tokens are email-only; update all systems simultaneously. Automate OAuth refresh; each refresh invalidates the prior refresh token.
8. Webhook signatures: Verify SHA256 authenticity before processing any notification. PagBank order-payment webhooks use header x-authenticity-token; compute SHA256("{account_token}-{raw_unformatted_payload}") and compare in constant time.
9. mTLS rotation: Generating a new certificate invalidates the previous one immediately. Deploy before provisioning replacement.
10. Error 40002: Usually payment method disabled on merchant account (common for newly enabled PIX). Verify account config before debugging payload.
11. Environment isolation: Sandbox and production credentials, public keys, certificates, webhook endpoints, and databases must be separate. Never point sandbox tests at production callback URLs or production stores.
12. Production code: Add idempotency keys to retriable writes, structured error handling, rate-limit/backoff, audit logs without secrets/PAN/CVV, and feature flags or allowlists before enabling payment methods.

Security

For PCI-DSS scope reduction, mTLS lifecycle, webhook zero-trust (SHA256 + GET verification), Connect Challenge 2FA, and credential management, see security.md.

Auth decision tree

Multi-tenant app serving many merchants?
├─ YES → PagBank Connect (OAuth 2.0)
│         1. Register app → X_CLIENT_ID + X_CLIENT_SECRET
│         2. Consent: redirect (code) or SMS (needs authorization_id)
│         3. POST token exchange (grant_type: authorization_code | sms | challenge)
│         4. Implement refresh (/oauth2/refresh) and revoke (/oauth2/revoke)
└─ NO  → Static Bearer token
          Sandbox: sandbox.pagseguro.uol.com.br → Perfis de Integração → Vendedor
          Production: PagSeguro portal → Venda Online → Integrações → Gerar Token (sent by email)

Production security posture

When generating or reviewing code, default to a "secure-by-construction" implementation:

• Keep all PagBank tokens, X_CLIENT_SECRET, OAuth refresh tokens, mTLS key, and private challenge keys in a secrets manager or encrypted vault.
• Use separate env vars for PAGBANK_ENV, base URL, secure base URL, token, client ID/secret, webhook token, mTLS certificate, and mTLS key.
• Refuse patterns that log Authorization, card number, CVV, refresh token, decrypted challenge, certificate key, or raw webhook body containing PII.
• Make payment state transitions idempotent and monotonic. Do not downgrade PAID to WAITING from a late webhook.
• Require TLS for public endpoints, CSRF/session protection in admin panels, origin/rate checks for checkout pages, and bot protection (for example reCAPTCHA) on card entry flows.
• In code reviews, flag raw card fields (number, security_code, exp_month, exp_year) in server routes unless the merchant is explicitly PCI-certified and the user asked for a PCI-scoped direct-card integration.

Checkout flow (JSON v4.1)

1. POST /checkouts with items and buyer payload.
2. Parse links[] in response.
3. Find object with rel: "PAY" → redirect customer to payment URL.

Supported methods: credit/debit cards (AMEX, Visa, Master, Elo, etc.), Pix, Boleto, Apple Pay, Google Pay. "Pague com PagBank" is native and permanent on all checkouts.

Split workflow modes

Boleto types via payment_instructions: proposta (no fine/interest) vs cobranca (fine/interest rules).

SmartPOS homologation (physical)

1. Commercial contact — submit business model to partnerships.
2. DEBUG terminal configuration.
3. SDK payment method implementation.
4. Mandatory test scripts on DEBUG terminal.
5. Production — publish to PagBank App Store.

Routing: Moderninha PRO/WIFI routes directly via GSM/Wi-Fi. Minizinha routes via host device internet over Bluetooth.

Webhook configuration

Subscription events (all mandatory): subscription.initial, .updated, .suspended, .activated, .recurrence, .expired, .canceled, .migrated.

EDI reconciliation

• Data available D+1.
• Response header VALIDADO=TRUE → complete/integrity OK.
• VALIDADO=FALSE → processing pending; data may be incomplete.

Pre-production checklist

Copy and verify before go-live:

- [ ] Homologation completed or exemption confirmed for platform/plugin flow
- [ ] Sandbox and production credentials fully separated
- [ ] Base URLs pinned per environment; secure URL used for Transfer/Pix Bacen
- [ ] Secrets stored outside code, build logs, and client bundles
- [ ] mTLS configured for Transfer API
- [ ] mTLS renewal planned before expiry (no blind cert swap)
- [ ] Connect Challenge keys: SPKI public, PKCS8 private
- [ ] Cards encrypted only via client-side SDK (no PAN/CVV on server)
- [ ] Webhook SHA256 signature verification enabled (`x-authenticity-token`)
- [ ] Webhooks + GET verification (idempotent state updates)
- [ ] Idempotency-Key used for retriable writes
- [ ] Logs redact Authorization, card, CVV, token, certificate key, PII where possible
- [ ] Rate limits, retry/backoff, and alerting configured
- [ ] Split formulas validated (100% or total match)
- [ ] OAuth refresh automated (no silent token expiry)
- [ ] OAuth refresh token replacement persisted atomically
- [ ] Sandbox scenarios tested (Simulador: Pix/Boleto paid, waiting, canceled/expired)
- [ ] Production feature flags and rollback path prepared

SDK encryption error codes

Additional resources

• Cybersecurity and PCI-DSS guidelines: security.md
• Full service catalog, OAuth params, and doc index: reference.md
• Request patterns and handler snippets: examples.md
• Official docs: https://developer.pagbank.com.br
• Official API index for agents: https://developer.pagbank.com.br/llms.txt