Integrating BNPLs like Affirm, Afterpay, and Klarna through Juspay Hyperswitch requires configuring three separate payment method types each with distinct geographic constraints, required API fields, and authorization flows. Affirm operates in the United States only, in USD, via redirect flow. Klarna supports 23+ countries through both redirect and SDK flows. Afterpay and Clearpay share a single payment method type and route through different PSPs like Stripe or Adyen, which determine the product brand from the billing country. The orchestration layer connects them all under a unified API but each provider's requirements must be met explicitly for payments to reach the provider's systems.

How does Hyperswitch model BNPL in its payment method data structure?

PayLater: Hyperswitch's payment method category for buy now pay later (BNPL). All BNPL methods are represented as PaymentMethodData::PayLater(PayLaterData) variants in the data model. The PayLaterData enum supports 10+ providers including KlarnaRedirect, KlarnaSdk { token }, AffirmRedirect, and AfterpayClearpayRedirect with Klarna being the only provider that supports both a redirect flow and a native SDK flow.

Each payment method type maps to different providers in terms of connector options, as represented below:

PaymentMethodType::Affirm → [Affirm direct, Stripe, Adyen]
PaymentMethodType::AfterpayClearpay → [Stripe, Adyen]
PaymentMethodType::Klarna → [Klarna direct, Stripe, Adyen, Mollie]

What are the geographic and currency constraints for each BNPL provider?

Geographic eligibility: The constraint each BNPL provider applies based on the customer's billing country and the payment currency. These constraints are enforced at the connector or payment service provider level not by Hyperswitch's routing engine. A representation of this is shared below

Afterpay and Clearpay are the same PaymentMethodType::AfterpayClearpay in Hyperswitch. The branding distinction of Afterpay in English-speaking markets and Clearpay in European markets is resolved downstream at the PSP level based on the customer's billing country.

What does integrating Affirm through Hyperswitch require?

Affirm redirect flow: Affirm operates exclusively as a redirect-based BNPL method. When the customer selects Affirm, they are redirected to Affirm's hosted checkout where the credit decision is made. The customer returns to the merchant's return URL after approval.

Affirm requires the following fields in every payment create request: customer email, billing address, shipping address and order_details- an array of items with product_name, product_id, amount, and quantity. If billing, shipping, email, or order details are absent, Hyperswitch returns* *ConnectorError::MissingRequiredField at the connector stage before the request reaches Affirm's API. Every Affirm-bound payment must carry all required fields before the authorize call.

How does Klarna integration work and what makes the SDK flow different from redirect?

Klarna is the only BNPL provider in Hyperswitch that supports two distinct integration paths. The redirect flow and the SDK flow have different configuration requirements, different customer experiences, and different data requirements.

Redirect flow: Klarna renders its hosted checkout page, where the customer completes the BNPL agreement before returning to the merchant. This flow requires the merchant to configure return URLs - terms URL, checkout URL, confirmation URL, and a push webhook URL, that Hyperswitch passes to Klarna during the authorize call. Without these URLs, the redirect flow cannot complete the return handoff after Klarna's credit decision.

SDK flow: Klarna renders inline within the merchant's checkout using Klarna's JavaScript SDK. The customer never leaves the merchant's page. The flow requires two steps: a session call followed by a confirm call.

The session-to-authorization sequence for Klarna's SDK flow:

The SDK flow requires order_details in the payment call:

"order_details": {
    "product_name": "Apple iPhone 15",
    "quantity": 1
    "amount": $400
  }
`there are 10+ optional fields available under order_details

Klarna's credit decision happens inside the widget, not at authorization time. By the time the merchant frontend calls /payments/confirm, the customer has already completed Klarna's agreement flow. The authorize call confirms the decision. This is a key difference from card authorization where the payment network decision happens at the authorize call.

The SDK flow typically delivers higher checkout conversion than the redirect flow because the customer never leaves the merchant's page and the Klarna interaction feels native to the checkout experience.

How does Afterpay/Clearpay integrate through Hyperswitch?

AfterpayClearpay redirect flow: Both Afterpay and Clearpay are integrated through PSPs like Stripe, Adyen and more. The merchant integrates payment_method_type: AfterpayClearpay, and Hyperswitch controls the Afterpay button and presents it on the unified checkout.

The integration requirements match the other redirect-based BNPL methods: billing address, shipping address, and email are required in the payment create request. The customer is redirected to Afterpay's or Clearpay's hosted page and returns to the merchant's return URL after approval.

Where BNPL payment responsibility ends and what the orchestration layer cannot do

Hyperswitch supports ordered fallback within a single PaymentMethodType when the payment method is cards. However for payment methods like Klarna the system doesn’t retry on its own or doesn’t do automatic retry. If the primary configured payment provider for the Klarna is unavailable or declines, whether due to a connector outage or Klarna's own credit decision, Hyperswitch does not automatically fall back to another provider of Klarna or a different payment method like card for the same payment intent.

Once, the merchant receives the BNPL decline, the checkout must surface a card or alternative payment option by relying on the manual retry option. A merchant needs to have this feature enabled from the Hyperswitch dashboard. This is not a limitation specific to BNPL, the routing engine operates on the PaymentMethodType dimension and a PayLater/Klarna failure cannot be retried or become Card/Credit within the same payment flow.

The checkout-layer fallback also applies when Klarna's credit decision is to decline. Klarna evaluates the customer's credit profile, purchase history, and risk signals independently. A Klarna decline on credit grounds is final for that BNPL session.

What the manual retry flow looks like from a checkout design perspective:

What breaks when BNPL integration is misconfigured

• Expecting BNPL options like Klarna or Affirm for non supported geographies or currencies. The Hyperswitch SDK only renders payment methods that can be supported for a given transaction basis the inputs received from the customer and the merchant. For instance, a transaction with currency = non USD AND/ OR country = non US will not have Affirm show up on the Hyperswitch SDK at checkout.
• Missing Affirm fields surfacing as connector errors. Affirm requires billing address, shipping address, email, and order details in the payment create request. If any are absent, Hyperswitch returns ConnectorError::MissingRequiredField at the connector stage. Validate that all Affirm-bound payments carry complete billing, shipping, and order_details before the Payments call reaches Hyperswitch.
• Klarna redirect flow without merchant URLs. Klarna's redirect flow requires terms URL, checkout URL, confirmation URL, and a push webhook URL. If these are not configured, Klarna cannot complete the redirect handoff after its credit decision. The payment fails at the step where Klarna would return the customer to the merchant's confirmation page. The Klarna SDK flow avoids this entirely, no redirect URLs are required.
• Expecting automatic BNPL-to-BNPL fallback. Teams that configure BNPL across multiple PSPs and expect Hyperswitch to fall back to another provider if BNPL fails are working from a false assumption. There is no automatic fallback for BNPL-to-BNPL or other payment methods. This is supported via manual retry option and requires surfacing alternative payment options in the checkout.

How to enable BNPL payments in Hyperswitch

Step 1 - Enable BNPL methods on each connector. In the Hyperswitch dashboard, navigate to respective connectors (Stripe, Adyen, Klarna direct, Affirm direct etc.) and enable the BNPL payment method types under the connector's payment methods tab.

Step 2 - Choose and configure the Klarna flow type.** Decide whether to use Klarna's redirect flow or SDK flow. For the redirect flow, configure the terms, checkout, confirmation, and push webhook URLs in the connector settings. For the SDK flow, ensure metadata.order_details is populated in the payment create request and that the frontend initializes the Klarna SDK using the client_token returned from Hyperswitch's session call.

Step 3 - Populate required fields for BNPL payments. Ensure that any payment routed to Hyperswitch includes complete 'billing, shipping, and emailfields, plusorder_details` with product name, product ID, amount, and quantity per item. These can be collected at checkout or passed from the merchant's customer profile.

Step 4 - Enable manual retry to allow customers to select another payment method and retry transcription when the BNPL payment fails.

Key Takeaways

• Affirm, AfterpayClearpay, and Klarna are distinct PaymentMethodType variants in Hyperswitch.
• Affirm is US/USD only; Afterpay covers US/CA/AU/NZ; Clearpay covers UK/ES/FR/IT; Klarna covers 23+ countries. Geographic or currency eligibility is enforced at the Hyperswitch layer
• Affirm requires billing address, shipping address, email, and order_details - missing fields return ConnectorError::MissingRequiredField
• Klarna offers two integration flows: redirect (requires merchant return URLs) and SDK (requires metadata.order_details, returns client_token for widget initialization)
• Afterpay and Clearpay share PaymentMethodType::AfterpayClearpay - they route through Hyperswitch, which determines the product brand from the billing country, to the underlying PSP like Stripe, Adyen or others.
• BNPL-to-other payment method fallback is not automatic and is manual in nature and driven by manuka retry flag configured in the Hyperswitch merchant account.