Laravel Pagseguro Laravel Package

Getting Started

1. Check compatibility before anything else. The package's last release was March 2021, so its composer.json constraints almost certainly target Laravel 6–8 / PHP 7.4–8.0. Run composer require artistas/laravel-pagseguro in a scratch branch first; on Laravel 10/11 you will likely need --ignore-platform-reqs, a fork, or a vcs repository entry. Decide this before you write a line of application code.

2. Install and publish config.

composer require artistas/laravel-pagseguro
php artisan vendor:publish --provider="Artistas\PagSeguro\PagSeguroServiceProvider"

Inspect config/pagseguro.php — it is the single source of truth for credentials, sandbox toggle, notification URL, and redirect URLs. Add the env keys it references (PAGSEGURO_EMAIL, PAGSEGURO_TOKEN, sandbox flag) to .env and .env.example.

3. Get sandbox credentials. Create a sandbox seller account at PagSeguro/PagBank, retrieve the sandbox email + token (they are different from production), and set the sandbox flag. Sandbox and production are separate credential sets and separate base URLs — never mix them.

4. Where to look first. Read the (Portuguese) README end to end — it is the de-facto API documentation. Then read src/ in this order: the service provider (what gets bound), the main client/facade class (method names and payload shape), and the config file. Ignore the tests unless there are fixtures; if there are, they show the exact XML/JSON payloads PagSeguro expects.

5. First use case: one transparent credit-card payment. The flow is always: your backend obtains a session ID from PagSeguro → your frontend tokenizes the card with PagSeguro's JS library → you POST the card token + sender hash to your controller → the package creates the transaction → you persist the transaction code and redirect to the returned payment URL. Build this single path end to end in sandbox before touching subscriptions.

Implementation Patterns

Wrap the facade in your own payment service. Never call the package facade from controllers. Create App\Payments\PagSeguroGateway with methods like charge(), chargeBoleto(), subscribe(), cancel(), find(). This gives you one place to log, retry, and later swap to PagBank's newer API.

Session ID endpoint. The frontend JS needs a session before it can tokenize a card. Expose your own route (e.g. GET /pagseguro/session) that calls the package's session method and returns the ID, and cache it briefly — sessions are reused by the JS SDK across cards on the same page.

Notification/webhook handling. Register a single POST /pagseguro/notification route that is publicly reachable over HTTPS. On receipt:

1. Read notificationCode and notificationType from the request.
2. Re-fetch the transaction/subscription from the API using that code — do not trust the notification body.
3. Upsert into your payments table keyed on the PagSeguro transaction code (idempotency — notifications repeat).
4. Map the numeric status to your own enum and fire domain events (PaymentApproved, SubscriptionCanceled).

Recurring payments. The model is two-step: create a plan (preApproval) once with amount/period/name, then create a subscription which returns an authorization URL. Redirect the customer there, and drive all subsequent state from notifications — not from the redirect return. Cancellation and suspension are explicit calls; there is no "just stop notifying."

Persistence schema. Store at minimum: code, reference (your order ID), status, gross_amount_cents, payment_method, installments, raw_response (JSON), updated_at. The raw response is your only forensic tool when PagSeguro support asks what happened.

Testing. Bind a fake gateway in the container or PagSeguro::shouldReceive(...) on the facade; never let the test suite hit the network. Assert on the payload your service builds, not on the HTTP call.

Gotchas and Tips

• This is effectively legacy software. PagSeguro rebranded to PagBank and retired large parts of the legacy Checkout Transparente JS library and recurring/preApproval API. Before investing, verify in sandbox that the exact endpoints the package calls still respond. If you are starting a new integration in 2026, treat this package as a reference implementation of the payload format and plan a migration to PagBank's current Orders/Subscriptions API.
• Sandbox is not production. Antifraud, approval rates, and even error responses differ; sandbox has had multi-day outages. Test the error paths deliberately using PagSeguro's documented test cards.
• Amounts. Confirm whether the package expects cents or a decimal string — mismatch is the #1 silent failure (a R$ 1,00 charge becomes R$ 100,00). Keep money as integer cents in your DB and convert only at the boundary.
• Card data must never touch your server. Tokenization and the sender hash happen in the browser. If you find yourself accepting a raw PAN in a Laravel request, stop — that is a PCI problem and the token flow exists specifically to avoid it.
• Sender hash + IP matter. Pass the real client IP; substituting your server IP degrades approval and can trigger antifraud rejection.
• Errors are opaque. The package tends to surface a generic exception for HTTP 400s. Always log the response body / getResponse(); PagSeguro returns a list of error codes that tell you exactly which field is wrong.
• Config cache. Run php artisan config:cache after changing env, and confirm the package reads config at call time rather than capturing values in the service provider's register().
• Notification URL must be public HTTPS. Use ngrok/Expose locally and re-register the URL when the tunnel changes; PagSeguro silently drops notifications to unreachable hosts.
• Installments are your responsibility. The package passes quantity and value through; interest calculation, minimum installment value, and the installment table shown to the user are all on you.
• Status codes are not the same across resources. Transaction statuses (1–9) and preApproval statuses (INITIATED, PENDING, ACTIVE, …) are different enums. Map each explicitly rather than with a shared helper.
• Extension point if you must fork. The client class is small; overriding the base URL and the HTTP client gives you a cheap path to point at a newer endpoint without rewriting the payload builders.