Buy Now, Pay Later (BNPL)

  • Updated
Buy Now, Pay Later (BNPL) lets shoppers pay for an order in installments through alternative payment methods (APMs) such as Klarna, Afterpay, Clearpay, Affirm, and Zip. Configure BNPL to capture shoppers who want to split a payment without using a credit card, and to expose deferred-payment options at checkout without changing the rest of the order flow.
 
This article describes how Configured Commerce orchestrates a BNPL transaction through Spreedly and Stripe, what to configure in each system, and what to expect during the shopper experience. The audience is QA engineers verifying the feature and client implementers configuring BNPL on a Configured Commerce site.

Prerequisites

Confirm the following before you configure BNPL:
  • A Spreedly account with a connected gateway of type Stripe Payment Intents.
  • A Stripe account with BNPL payment methods activated.
  • The Configured Commerce Payment Gateway setting configured as PaymentService.
  • A Stripe publishable key. BNPL does not work without one.
  • A Stripe webhook configured to deliver payment status events to Spreedly.

Overview

Buy Now, Pay Later coordinates four systems to authorize a deferred payment and confirm the order. The Spire storefront calls Spreedly, which calls Stripe Payment Intents, which delegates authorization to the BNPL provider the shopper picks.
A complete BNPL transaction moves through these systems in this order:
  1. Spire storefront.
  2. Spreedly (the payment orchestrator).
  3. Stripe Payment Intents (the payment gateway).
  4. BNPL provider, for example Klarna, Afterpay, Clearpay, Affirm, or Zip.

Customer experience

Walk a shopper through BNPL on the storefront so you can confirm the integration behaves as described.
  1. On the Checkout - Review and Submit page, the shopper selects a BNPL payment method.
  2. Configured Commerce creates a pending transaction through Spreedly and Stripe at the moment of selection, before the shopper clicks Place Order.
  3. Stripe Payment Element renders an embedded form, and the shopper picks a specific BNPL provider, for example Klarna.
  4. The shopper clicks Place Order, and Stripe redirects them to the BNPL provider's site for authorization.
  5. After authorization, the BNPL provider returns the shopper to the storefront, and Configured Commerce confirms and places the order.

Supported BNPL providers

Stripe controls which providers display in the Payment Element. The list depends on the Stripe account, the order currency, the shopper's country, and the order amount.
Provider
APM identifier
Regions
Klarna
klarna
EU, US, UK, AU
Afterpay or Clearpay
afterpay_clearpay
US, UK, AU, NZ
Affirm
affirm
US, CA
Zip
zip
AU, NZ
The APM identifier is the value that Configured Commerce passes to Spreedly in the BNPL APM Types system setting. Stripe Payment Element filters the methods shown to the shopper based on the Stripe account and the order, so a method that you activate in Stripe still displays only when the order qualifies.

Stripe configuration

Activate each BNPL method you want to offer, collect the API credentials Configured Commerce needs, and create the webhook Spreedly relies on for payment status updates.

Activate BNPL methods in the Stripe Dashboard

Activate every BNPL provider you plan to offer. Some providers require Stripe verification before they go live.
  2. Find the BNPL provider you want to enable, for example Klarna, Afterpay, Affirm, or Zip.
  3. Click Turn on for the provider.
  4. (Optional) Complete the verification steps when Stripe prompts for them.
In Stripe Test mode, most BNPL providers are available automatically without verification.

Get the Stripe publishable key

Configured Commerce needs the Stripe publishable key to render the Payment Element on the storefront.
  2. Copy the publishable and the restricted key. The test key starts with pk_test_, the restricted key starts with rk_test_ and the live key starts with pk_live_.
  3. Save the key for the Configured Commerce Stripe Publishable Key system setting.

Configure the Stripe webhook

Spreedly receives payment status updates for BNPL and other APM transactions through a Stripe webhook. The webhook is mandatory for BNPL.
  2. Click Add endpoint.
  3. Enter https://core.spreedly.com/stripe/webhooks in the Endpoint URL field.
  4. Select every Payment Intent event in Events to send, including payment_intent.succeeded and the other payment_intent. events.
  5. Click Add endpoint.
  6. Copy the Webhook ID that displays in the endpoint URL. The ID starts with we_.
  7. Click Reveal in the Signing secret section and copy the secret.
Save the webhook ID and signing secret for the Spreedly gateway configuration. If you already have a Stripe webhook configured for 3D Secure, you can reuse it for BNPL. Confirm that the webhook subscribes to every required Payment Intent event.

Configure the admin console

Create the Spreedly gateway that processes BNPL transactions, add a BNPL payment method, and enable the BNPL system settings in the Configured Commerce admin console.
 

Create a Stripe Payment Intents gateway in Spreedly

A Spreedly gateway routes BNPL transactions through Stripe Payment Intents. You can reuse the gateway that handles credit-card payments, or create a separate gateway for BNPL.
  1. Go to Admin > Administration > Payment Service > Gateways.
  2. Click Add Gateway.
  3. Select Stripe Payment Intents.
  4. Enter the Stripe restricted API key in the Api Key field. As copied in Get the Stripe publishable key step.
  5. Enter the Webhook value and the Signing Secret value from the Stripe webhook.
  6. Click Save.
  7. Copy the Gateway Token that displays after save. You need it for the BNPL Gateway Token system setting.
The BNPL Gateway Token setting is independent of the main Gateway Token setting, so you can point BNPL at a separate Spreedly gateway when your account requires it.

Configure the BNPL payment method

A BNPL payment method exposes the deferred-payment option to shoppers in checkout. Mark the method as BNPL so the storefront renders Stripe Payment Element instead of the credit-card form.
  1. Go to Admin > Sales > Payment Methods.
  2. Open an existing payment method, or click Add Payment Method to create one.
  3. Set Is Bnpl to Yes.
  4. Enter a shopper-facing name in the Name field, for example Buy Now, Pay Later.
  5. Enter a shopper-facing description in the Description field, for example Pay with Klarna, Afterpay, or other BNPL providers.
  6. Set the Activate On and Deactivate On dates the campaign requires.
  7. Click Save.
Do not set Is Bnpl and Is Credit Card to Yes on the same payment method. The two flags describe different payment types, and the storefront cannot render both at once.

Configure system settings

The Spreedly settings group exposes the toggles and identifiers that drive BNPL behavior. The group displays only when Gateway is configured as PaymentService.
  1. Go to Admin > Administration > System Settings > Order Management > Spreedly.
  2. Configure the core BNPL settings described in the next table.
  3. Confirm the supporting settings in the second table are configured correctly.
The following table describes the core BNPL settings. 
Setting Description Required  Example
Buy Now, Pay Later Enabled BNPL toggle. Enables or disables the feature Yes  Yes 
BNPL Gateway Token Token of the Spreedly gateway that processes BNPL transactions. Stripe Payment Intents is the only supported gateway Yes  AbC123dEfGhI456
BNPL APM Types Comma-separated list of APM identifiers. The values must match providers activated in the Stripe Dashboard. Yes  klarna, afterpay_clearpay, zip, affirm
BNPL Test Callback Url Override for the callback URL in a test environment. Leave empty to use the auto-generated URL. No  Empty 
BNPL Test Redirect Url Override for the redirect URL in a test environment. Leave empty to use the auto-generated URL. No Empty 
The following table describes the supporting settings that BNPL depends on.
Setting
 Section Description
Gateway
Order Management > Payment
Set to Spreedly or PaymentService.
Stripe Publishable Key
Order Management > Payment
Publishable key from the Stripe Dashboard. The test key starts with pk_test_ and the live key starts with pk_live_.
Gateway Token
Order Management > Spreedly
Spreedly gateway token for credit-card payments.
The BNPL Gateway Token, BNPL APM Types, BNPL Test Callback Url, and BNPL Test Redirect Url fields display only when Buy Now, Pay Later Enabled is set to Yes.
 

Find the APM identifier for a provider

The Stripe BNPL documentation lists the APM identifier for each provider in the API support table at Buy Now, Pay Later overview. The identifier appears in the second column.
The following table lists the supported identifiers.
Provider  APM identifier
Affirm  affirm
Afterpay or Clearpay afterpay_clearpay
Alma  alma
Billie  billie
Klarna  klarna
Kriya  kriya
Mondu  mondu
SeQura  sequra
Sunbit  sunbit
Zip  zip
You can also find the identifier on the Accept a payment page for each provider in the Stripe documentation. The code samples on that page include a payment_method_types[1] parameter, and the value after the equals sign is the identifier you need.
Add only the providers activated in the Stripe Dashboard to the BNPL APM Types setting. Stripe Payment Element filters the methods it displays based on currency, country, and amount, and Spreedly uses the BNPL APM Types value to build the API request.

User flow

The following sections describe what happens during a successful BNPL purchase and what the shopper sees when the transaction fails.

Happy path

A successful BNPL purchase moves through the following events in order. The actor column identifies which system performs each action.
Step  Actor  Action 
1 Shopper  Adds items to the cart and starts checkout.
2 Shopper  Selects a BNPL payment method on the Review and Submit page. 
3 Configured Commerce Creates a pending transaction through Spreedly and Stripe when the shopper selects the method.
4 Configured Commerce Reads client_secret and transaction_token from the Stripe response.
5 Stripe Payment Element Renders the BNPL methods available for the order. The list depends on currency, amount, and the shopper's country.
6 Shopper  Selects a BNPL provider, for example Klarna.
7 Shopper  Clicks Place Order. 
8 Configured Commerce
Calls confirmPayment(), and Stripe redirects the shopper to the BNPL provider's site. 
9 Shopper  Authorizes the payment on the BNPL provider's site.
10 BNPL provider Redirects the shopper back through Spreedly to the redirect URL.
11 Configured Commerce Checks the transaction status through the Spreedly API.
Configured Commerce branches on the transaction status returned by Spreedly:
  • When the status is succeeded, Configured Commerce updates the pending transaction, places the order, and displays the Order Confirmation page.
  • When the status is processing, the order moves to PendingPaymentValidation, the shopper sees the Order Confirmation page, and the webhook delivers the final result later.
When the order total changes after the pending transaction is created, Configured Commerce recreates the pending transaction with the updated amount automatically. An example is when the shopper adds or removes an item from the cart.

Error scenarios

The following table maps each transaction status to the resulting order state and the message the shopper sees on the storefront.
Transaction status Configured Commerce behavior Shopper experience
succeeded Pending transaction updates to Submitted, and the order is placed Order Confirmation page.
processing Pending transaction stays in place. Order moves to PendingPaymentValidation, and the webhook finalizes the order Order Confirmation page.
pending Shopper returned without completing the payment. Error Payment failed. Please try again. on the checkout page. The shopper can retry. 
failed Payment was declined. The pending transaction is marked Error. Error on the checkout page. Selecting the BNPL method again creates another pending transaction.
gateway_processing_failed Gateway error. The pending transaction is marked Error. Error on the checkout page. Selecting the BNPL method again creates another pending transaction.
gateway_processing_result_unknown Transaction result is unknown. Error Payment was successful, but order submission failed. Please contact support.

FAQ

Which BNPL providers are supported?
Every provider supported by Stripe Payment Element is available. For the current list, see the Stripe payment methods integration options. Spreedly does not support the card type for APMs.
 
Why does Klarna or Afterpay not display in the Payment Element?
Stripe filters the methods displayed in the Payment Element based on currency, amount, and the shopper's country. Confirm the following:
  • The provider is activated in the Stripe Dashboard.
  • The APM identifier is listed in the BNPL APM Types setting.
  • The order currency and country match what the provider supports.
Is a separate Spreedly gateway required for BNPL?
No. You can reuse the same Stripe Payment Intents gateway for credit-card and BNPL transactions. The BNPL Gateway Token setting is separate from the main Gateway Token setting, so you can point BNPL at a different gateway when your Stripe account requires it.
 
What happens when the Stripe webhook does not arrive?
For most BNPL providers, Configured Commerce learns the transaction result on redirect and does not depend on the webhook. Webhooks matter for providers that finalize slowly, for example SEPA Debit, where the provider can take days to confirm. When the webhook fails, the order stays in PendingPaymentValidation status.
 
Does BNPL work with promo codes and discounts?
Yes. BNPL transacts against the final order total, including discounts, taxes, and shipping.
 
When are the BNPL test callback and redirect URLs needed?
Configure the BNPL Test Callback Url and BNPL Test Redirect Url settings only in environments where the auto-generated URLs are not reachable, for example localhost. In production, leave them empty. Configured Commerce generates the URLs automatically:
  • Redirect URL: https://{site}/api/v1/spreedly/bnpl/redirect?cartId={cartId}
  • Callback URL: https://{site}/api/v1/paymentauthentication/bnplcallback

Payment flow diagram

Sequence diagram of the BNPL payment flow, showing requests exchanged between the Spire storefront, Spreedly, Stripe Payment Intents, and the BNPL provider during checkout

References

The following resources document the systems referenced in this article. Use them when you need detail beyond the Configured Commerce configuration.