Buy Now Pay Later Integration Engineering — From Klarna to Afterpay

The BNPL Landscape in 2026

Buy Now Pay Later isn't a trend anymore — it's table stakes. Global BNPL transaction volume crossed $500 billion in 2025, and every merchant integration I've worked on in the past two years has included at least one BNPL provider as a requirement. The appeal is straightforward: customers split purchases into installments, merchants get paid upfront (minus a fee), and the BNPL provider assumes the credit risk.

But from an engineering perspective, BNPL integrations are deceptively complex. Unlike a standard card payment where you authorize, capture, and you're done, BNPL introduces a multi-party flow with asynchronous state changes, split settlement timelines, and refund logic that can make your accounting team cry.

The Checkout Flow — How It Actually Works

At a high level, every BNPL checkout follows the same pattern. The merchant creates a session, the customer approves the payment on the provider's side, and the merchant captures the order. Here's the flow I've seen across all three major providers:

Simple enough on a whiteboard. In practice, every arrow in that diagram is a place where things can go wrong — expired sessions, customers closing the browser mid-approval, race conditions between the redirect callback and the webhook, and capture calls that timeout because the provider is having a bad day.

Redirect vs. Embedded: Choosing Your Integration Pattern

The first architectural decision you'll face is whether to use a redirect flow or an embedded widget. I've shipped both, and the tradeoffs are real.

Redirect Flow

The customer leaves your checkout page, completes approval on the BNPL provider's hosted page, and gets redirected back with an authorization token. Klarna's HPP (Hosted Payment Page) and Afterpay's standard integration both work this way.

Redirect is simpler to implement — you're essentially handing off the UI to the provider. But you lose control of the experience, and you have to handle the return carefully. The biggest gotcha: never trust the redirect alone. Customers can manipulate query parameters, and redirects can fail silently. Always confirm the authorization server-side via the API before showing a success page.

Embedded Flow

Klarna's Payments SDK and Affirm's checkout.js let you render the BNPL option inline within your checkout page. The customer never leaves your domain. It's a better UX, but you're now responsible for loading the SDK, handling its lifecycle events, and managing the iframe communication.

type BNPLProvider interface {
    CreateSession(ctx context.Context, order Order) (*Session, error)
    Authorize(ctx context.Context, token string) (*Authorization, error)
    Capture(ctx context.Context, authID string, amount Money) (*Capture, error)
    Refund(ctx context.Context, captureID string, amount Money) (*Refund, error)
}

Provider Comparison

After working with all three in production, here's how they stack up from an engineering perspective:

Feature	Klarna	Afterpay	Affirm
Integration Pattern	Redirect + Embedded SDK	Redirect (primary)	Embedded JS + Redirect
Settlement Timing	T+2 (net of fees)	T+2 to T+4	T+2 to T+3
Installment Options	Pay in 4, financing (6-36 mo)	Pay in 4 (fixed)	3, 6, 12, 18 month terms
Webhook Reliability	Good — retries with backoff	Decent — manual retry available	Good — configurable retry
Sandbox Quality	Excellent	Adequate	Good
API Documentation	Comprehensive	Improving	Solid
Partial Capture	Yes	No	Yes
Integration Complexity	Medium-High	Medium	Medium

One thing the table doesn't capture: Klarna's API surface is significantly larger than the others. They offer pay-in-4, long-term financing, and a full checkout takeover product, each with different integration paths. If you only need pay-in-4, Afterpay is the fastest to ship.

Webhook Handling for Installment Events

BNPL webhooks are where the real complexity lives. Unlike a card payment where the transaction is essentially done after capture, BNPL providers send events throughout the installment lifecycle — and you need to handle them to keep your records accurate.

The events you'll typically receive:

• Order approved / authorized — customer completed approval
• Order captured — funds committed, settlement scheduled
• Installment paid — customer made a scheduled payment (Klarna sends these)
• Installment missed — customer missed a payment (provider handles collections, but you may want to flag the order)
• Refund processed — your refund request was completed
• Dispute opened — customer disputed the charge with the BNPL provider

Verify every webhook signature. Klarna uses HMAC-SHA256, Afterpay uses a signature header with their public key, and Affirm signs with a shared secret. Treat unverified webhooks as hostile.

The Installment Payment Lifecycle

Here's what a typical 4-installment BNPL order looks like from the merchant's perspective over time:

The key insight: the merchant gets paid upfront. The installment schedule is between the customer and the BNPL provider. This is great for cash flow, but it creates a disconnect that makes refunds complicated.

Reconciliation Challenges with Split Payments

Reconciliation is where BNPL integrations get painful. The settlement you receive from the BNPL provider is the order total minus their fee — but the fee structure varies. Klarna charges a percentage plus a fixed fee per transaction. Afterpay is percentage-based. Affirm varies by term length.

The problem: your settlement file from the BNPL provider won't match your order amounts. You need to account for the provider fee on every transaction, and those fees can change based on your contract terms, promotional rates, or volume tiers.

What worked for us: we store the expected fee at capture time (calculated from our contract terms) and reconcile against the actual settlement amount. Any discrepancy over a threshold triggers an alert. We catch fee changes within one settlement cycle this way.

Refund Complexity

Refunds are the single hardest part of BNPL integration. With a card payment, you refund and the money goes back. With BNPL, the customer may have already paid two of four installments. A full refund means the provider needs to reverse the remaining installments and refund what's been paid. A partial refund is even messier — the provider has to recalculate the installment schedule.

Afterpay doesn't support partial captures, which means if a customer orders three items and you can only fulfill two, you have to void the entire order and create a new one for the two items. This is a workflow your order management system needs to handle gracefully.

Regulatory Considerations

BNPL regulation is tightening globally. The UK's FCA brought BNPL under formal regulation in 2025. The EU's Consumer Credit Directive now covers BNPL products. In the US, the CFPB has issued interpretive rules classifying BNPL providers as lenders.

For engineers, this means: don't store BNPL-related customer financial data beyond what's necessary for the transaction. The providers handle the credit assessment and compliance — your job is to not accidentally become a data controller for information you don't need. Log order IDs and transaction references, not customer credit details.

References

• Klarna Developer Documentation
• Afterpay Developer Portal
• Affirm Developer Documentation
• FCA — Buy Now Pay Later Regulation
• CFPB — Buy Now Pay Later Market Report

Disclaimer: This article reflects the author's personal experience and opinions. Product names, logos, and brands are property of their respective owners. Pricing and features mentioned are subject to change — always verify with official documentation.