Architecting for Alternative Payment Methods (APMs)
Cards dominate the US, but globally, they are the exception. In Brazil, Pix handles billions of transactions. In the Netherlands, iDeal captures over 70% of e-commerce volume. A payment stack hardcoded for the synchronous "Authorise & Capture" model of credit cards will break when attempting to integrate these crucial localized Alternative Payment Methods (APMs).
The Synchronous vs Asynchronous Divide
A standard credit card transaction is Synchronous: the client submits the PAN, the gateway pings the issuer, and returns an immediate APPROVED or DECLINED.
Most APMs are Asynchronous and often Push-based:
- Redirect Flow (e.g., iDeal, Bancontact): The user is redirected to their bank app, authorizes the payment there, and the merchant waits for an asynchronous webhook to verify the funds arrived.
- QR / Push Flow (e.g., Pix, WeChat Pay): The checkout generates a QR code. The user scans it with their phone to "push" the funds to the merchant. The checkout UI must poll or wait via WebSocket for confirmation.
- Buy Now, Pay Later (e.g., Klarna): Requires complex itemized cart data, real-time credit checks, and separate capture phases aligned with shipping physical goods.
The Unified Payment Intent Object
The architectural solution is abstracting the payment state into a standardized PaymentIntent. Instead of executing the payment, the client initializes an Intent. The API returns an action_required state containing either a redirect URL or a QR payload. The UI blindly executes the action type, leaving the core checkout logic entirely completely ignorant of the underlying APM mechanics.
Handling Webhook Delays
Because APMs rely on webhooks, edge cases arise where a user completes a bank transfer, but the network delays the webhook by 5 minutes. The user returns to the merchant site, but the system still shows "Pending."
Robust systems implement Optimistic Fulfillment UI with Idempotent Polling—showing the user an "Order Processing" state and holding the inventory lock, rather than dropping them back to an empty cart.
Ready to expand your localized payment coverage? Learn more about the specifics of Global Markets or consult our API docs for APM integrations.