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.

Building…	Recommended path	Notes
Hosted checkout, minimal PCI scope	Checkout Redirect / Lightbox	PagBank hosts payment UI
Custom UX on merchant site	Transparent Checkout + SDK	Client-side card encryption mandatory
Shareable pay link (social, email)	Payment Link	No dedicated site required
Multi-tenant SaaS / marketplace onboarding	PagBank Connect (OAuth 2.0)	`X_CLIENT_ID` + token lifecycle
Single merchant, server-to-server	Static token	Sandbox or production portal token; never expose client-side
Marketplace fund division	Split Payments API	Fixed or percentage; max 5 receivers
Subscriptions / recurring billing	Recurring Payments API	8 mandatory webhook events
Fund transfers between accounts	Transfer API	mTLS required
ERP reconciliation	EDI Statement API v3.00	D+1 data; check `VALIDADO` header
E-commerce store (WooCommerce, VTEX, etc.)	Platform connector	Prefer native plugin over custom API
Physical terminal (Moderninha, Minizinha)	PlugPag / SmartPOS SDK	5-step homologation lifecycle
High-volume retail PINPad	TEF	Local software integration
Workflow automation	n8n node	PIX, cards, sandbox support

Critical rules

PCI: Never send raw card data to merchant servers. Use PagBank SDK for client-side encryption and tokenization (Transparent Checkout v4.1).
Webhooks: Treat notifications as hints only. Always GET the resource from PagBank API before updating internal state (idempotency).
Transfer API: Configure mTLS with digital certificates before calling transfer endpoints.
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.
Split math: FIXED mode — sum of receiver amounts = order total. PERCENTAGE mode — sum of percentages = 100%.
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.
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.
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.
mTLS rotation: Generating a new certificate invalidates the previous one immediately. Deploy before provisioning replacement.
Error 40002: Usually payment method disabled on merchant account (common for newly enabled PIX). Verify account config before debugging payload.
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.
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)

POST /checkouts with items and buyer payload.
Parse links[] in response.
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

Mode	Flow
Single-stage	Split defined at checkout/order creation
Decoupled	Create order via `/orders`, call `/pay` when ready to split

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

SmartPOS homologation (physical)

Commercial contact — submit business model to partnerships.
DEBUG terminal configuration.
SDK payment method implementation.
Mandatory test scripts on DEBUG terminal.
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

URL field	Events
`notification_urls`	Checkout events
`payment_notification_urls`	Transaction events

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

Code	Fix
`INVALID_NUMBER`	Luhn validation failed
`INVALID_SECURITY_CODE`	CVV must be 3, 4, or 0 digits
`INVALID_EXPIRATION_MONTH`	MM format, 01–12
`INVALID_EXPIRATION_YEAR`	YYYY, current or future
`INVALID_PUBLIC_KEY`	Refresh via Public Keys API
`INVALID_HOLDER`	Non-empty cardholder name

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