# Pagbank

> PagBank/PagSeguro integration guide for REST APIs, OAuth Connect, checkout (redirect and transparent), split payments, webhooks, mTLS transfers, PCI client-side encryption, SmartPOS/PlugPag, EDI reconciliation, homologation, production readiness, sandbox testing, fraud controls, and cybersecurity (PCI-DSS, webhook SHA256 authenticity, credential and certificate lifecycle). Use when building, modifying, or reviewing PagBank integrations, PagSeguro checkouts, PIX/Boleto/card payments, marketplace splits, subscriptions, payment terminals, security reviews, go-live checklists, or Brazilian payment compliance. Always use this skill when code may touch real payments, card data, seller authorization, transfers, webhooks, reconciliation, or PagBank production credentials.

- Skill: `gitdolucas/pagbank` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gitdolucas/pagbank`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitdolucas/pagbank/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: gitdolucas (https://skillmd.com/u/gitdolucas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gitdolucas/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](reference.md) before answering domain-specific questions. Use [examples.md](examples.md) for request/response patterns and [security.md](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

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](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

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

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

| 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](security.md)
- Full service catalog, OAuth params, and doc index: [reference.md](reference.md)
- Request patterns and handler snippets: [examples.md](examples.md)
- Official docs: https://developer.pagbank.com.br
- Official API index for agents: https://developer.pagbank.com.br/llms.txt