How to structure Stripe, Mercado Pago, and Asaas in one Laravel codebase
If you're building a SaaS for the Latin American market, you will inevitably face a hard architectural decision: how do you support multiple payment providers without turning your codebase into a mess of if/else statements? You might start with Stripe, since it's the standard for international recurring billing. Then a client asks for PIX, and you need Mercado Pago. Another client wants boleto…
When creating a SaaS for the Latin American market, you will need to decide how to handle multiple payment providers without making your codebase complicated. Stripe is the go-to option for international recurring billing, but then clients may request additional methods like PIX, boleto bancário, or Asaas. If you're not cautious, your PaymentController can quickly become an unwieldy 500-line monster filled with provider-specific code.
To avoid this, use the Driver/Adapter pattern with a typed interface. This means defining a contract around your business operations, not the provider's API. Create an interface called GatewayDriverInterface with methods like createCustomer, createSubscription, cancelSubscription, verifyWebhookSignature, handleWebhook, and eventId. Then, use a manager to resolve the driver by name (e.g., stripe, mercadopago, or asaas). The usage is the same, regardless of which provider is being used.
Two crucial rules to follow from the beginning are:
1. Return structured arrays, not raw provider payloads. Normalizing responses into the same shape prevents coupling your business logic to each provider's schema.
2. Store money as integers in cents. Floating-point prices can cause issues like unexpected charges and reconciliation problems.
Handling webhooks without blocking falls under the same abstraction. Verify the signature for each gateway first, then dispatch a queued job. This keeps the payment system waiting, and allows for exponential backoff retries on transient failures. The eventId() method ensures duplicates are accounted for, as gateways may retry webhooks.
The Filament Pulse Charge package, available in Pro tier, offers a reference implementation of this architecture in production. It's open source and available for a one-time purchase of R$29.00 (approximately $5 USD).
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.