Klarna

Klarna is a buy-now-pay-later wallet. Customers are redirected to Klarna, choose a payment option there (pay in full, pay later, installments, or financing), and return to your checkout. Klarna pays you the full amount up front and collects from the customer itself. In PayNext, Klarna is available through Stripe. It supports one-time payments and subscriptions, with separate authorize and capture (like Amazon Pay).

​

Payment Method Details

​

Prerequisites

1. Connect and activate the Stripe integration in PayNext and add the Publishable Key to it (see Notes)
2. Enable Klarna in your Stripe Dashboard under Settings → Payment methods (the Stripe capability klarna_payments must be active on the account that serves the customer)
3. Turn on Klarna in your PayNext checkout configuration and list the customer currencies it applies to

​

Country limits

PayNext applies extra country rules on top of Stripe account availability, keyed on the customer’s country: The same country rules decide whether Klarna is offered at checkout and whether a subscription can be reactivated. Reactivation does not require the Klarna checkout configuration to list currencies. A condition on customer currencies still has to match the plan’s currency, according to its match type. Reactivation is allowed when any condition in your Klarna configuration matches. Reactivation checks the country only when it takes a payment. Klarna is not returned in checkout configuration for a plan that breaks the country rules.

​

How it works

​

One-time payments

The customer selects Klarna, is redirected to Klarna to pick a payment option and approve, then returns to your site. A one-off does not save a reusable instrument for subscriptions (setup_future_usage is not sent).

​

Subscriptions (initial payment)

For a subscription, the first payment is customer-present: Klarna redirects the customer, the authorization can reach AUTHORIZED, and a separate capture moves the payment to SETTLED. That first approval also sets up the saved Klarna instrument for later renewals.

​

Recurring charges

After the instrument is saved, renewals are charged off-session against the stored Klarna payment method. If Stripe accepts the charge, the payment can be AUTHORIZED (a separate capture then settles it, see Authorize and capture), SETTLING (Stripe completes it with a later event), or SETTLED. PayNext prefers the Stripe account that created the instrument and, if it can’t find that account, uses the processor from your workflow.

​

Paid trials

Klarna can’t pay a free trial: starting a Klarna payment for a plan whose price today is zero returns HTTP 400 with the message Klarna requires a positive plan price. On a paid-trial subscription’s first customer-present payment, PayNext charges the trial price (what the customer pays today). Klarna’s confirmation page shows the renewal price and the next billing date for later charges. That first-payment discount presentation applies only while the customer is present. Off-session renewals charge without that trial discount. On an existing subscription—for example a prorated charge or a plan change through checkout—Klarna does not present the charge as a trial-style discount; a checkout plan change uses the target plan’s renewal price for what Klarna shows as the upcoming amount.

​

Payments completed without the customer returning

A Klarna payment can finish even if the customer never returns to your site after approving on Klarna. When Stripe reports the approval, PayNext creates the customer, the payment, and, for a subscription plan, the subscription.

• PayNext creates a new customer for the attempt unless it finds one to reuse: the customer of an existing subscription, or a customer already saved in the checkout session. It never matches a customer by email.
• The customer’s name stays empty. The country comes from the checkout session, or from the payment’s Stripe metadata when the session has none. If neither has a valid country, the customer’s country stays empty.
• The payment is PENDING, then moves to AUTHORIZED and SETTLED as Stripe reports each step.
• If you have a published workflow for Klarna, Workflow Runs lists one run for the payment (see Workflows).

A checkout session stays valid for 24 hours. After that, a create request for the same Klarna payment returns HTTP 400 with code klarna_session_expired. PayNext can still process a late Stripe notification from the details stored with the payment at Stripe. If those details are incomplete, PayNext acknowledges the notification and creates nothing. If the customer starts Klarna again in a checkout session whose payment is already AUTHORIZED, SETTLING, SETTLED, or REFUNDED, the request returns HTTP 409 (payment already completed for this client session) and PayNext creates nothing new at Stripe.

​

Authorize and capture

Klarna supports manual capture. With a published workflow, a completed customer approval leaves the payment in AUTHORIZED until the workflow captures it (after a Delay step, if you add one). Without a published workflow, PayNext captures a customer-present payment right away when Stripe reports it. Capture settles the payment to SETTLED for the full authorized amount—partial capture is not supported. When Stripe reports the charge as still processing, the payment is SETTLING first and becomes SETTLED with a later Stripe event. You can void an AUTHORIZED payment before capture: a refund request on an uncaptured authorization cancels the hold. The payment becomes CANCELLED and no money is returned (refunded amount stays 0). The payment’s timeline shows one Cancelled entry, whether you voided the payment or Stripe cancelled it. If the payment started a subscription, PayNext cancels the subscription when Stripe delivers the cancellation event for the voided authorization, not at the moment of your request (see Webhooks). If an authorization is not captured within 28 days, Klarna cancels it through Stripe. PayNext runs no timer of its own: when Stripe notifies it, PayNext reports the payment as CANCELLED and cancels the subscription the payment started (see Webhooks).

​

Workflows

When Stripe reports that the customer approved a Klarna payment, PayNext follows your published payment-created workflow for Klarna. Without one, PayNext captures a customer-present payment reported this way immediately. A payment that stays AUTHORIZED keeps its hold until Stripe cancels it. You can’t save a workflow that Klarna triggers with an Authorize and capture step. For a payment PayNext created from the Stripe notification, Workflow Runs shows one run for the payment. A delayed capture shows as waiting. PayNext does not calculate tax for a payment that Stripe has already settled.

​

If the customer doesn’t complete payment

If the customer abandons the Klarna redirect (closes the tab or never returns), the payment becomes INCOMPLETE when Stripe reports that the attempt expired. This applies to customer-present payments. No charge is taken, and an abandoned Klarna redirect does not open dunning. If the customer tries Klarna again in the same checkout session after an attempt ended INCOMPLETE, DECLINED, or FAILED, PayNext creates a new payment with a new payment ID and a new PaymentIntent at Stripe, and cancels the previous PaymentIntent if Stripe still shows it as unpaid. If Stripe already shows the previous attempt as paid or authorized, PayNext returns that payment instead of creating a new one. The first payment keeps its own status.

​

Plan changes

Merchant-API plan changes (for example PATCH /subscriptions with a plan id, without a customer-present checkout) and the Change subscription workflow step are refused for subscriptions billed with Klarna, including a change to the plan the subscription is already on. The API returns HTTP 400 with code klarna_plan_change_requires_checkout, and the workflow step fails with an error that starts with klarna_plan_change_requires_checkout. Neither changes the plan. Metadata sent in the same PATCH request is saved even when the plan change is refused, and a request that sends only metadata isn’t affected. The check is skipped for a subscription that has no payment in status AUTHORIZED, SETTLING, SETTLED, or REFUNDED. Otherwise it looks at the payment method of the latest such payment, including a deleted Klarna method. A subscription that started on Klarna but whose latest such payment used another method is not blocked. To change the plan on a Klarna subscription, run a customer-present plan change through checkout so the customer re-authorizes on Klarna. See Change Subscription Plan.

​

Change the payment method

The customer changes the payment method through a customer-present checkout that charges the existing subscription. There is no separate flow that only switches the method, and Klarna doesn’t accept a zero-amount checkout. To switch from a card to Klarna, the customer must also pass the country limits and your Klarna checkout configuration. Renewals are charged on the customer’s payment method that most recently completed a successful payment, across all of the customer’s payments, not only this subscription’s.

​

Reactivation

PayNext charges for a reactivation only when the subscription is cancelled and its paid period has ended. If the paid period is still running, or the subscription is only scheduled for cancellation, reactivation creates no payment and does not check the payment method. When a reactivation takes a payment, PayNext charges the customer’s most recently used payment method (or, if none has paid, the most recently added one). If that method is Klarna and is deleted, closed, invalid, inactive, or suspended, the API returns an error with code payment_method_inactive_or_deleted before it creates a payment. Other method types are not checked. When that method is Klarna, the reactivation is also refused with code klarna_reactivation_ineligible when Klarna isn’t eligible for the customer’s country and the plan, or when no condition in your Klarna checkout configuration matches. Eligibility follows the country limits and your configuration, without the requirement to list currencies.

​

If the customer revokes the mandate

A customer can remove or deactivate the saved Klarna payment method in the Klarna app. PayNext receives that from Stripe (mandate.updated) and sets the payment method status to deleted. A mandate of type single_use is ignored. A revoked payment method can’t be charged: an attempt on it is aborted and recorded as INCOMPLETE with decline_code payment_method_disabled. If the customer has no other usable payment method, PayNext pauses dunning for all of the customer’s past_due subscriptions, and each stays past_due for 14 days before it is cancelled with reason dead_instrument. If the customer has another usable method, dunning continues and PayNext doesn’t cancel for this reason. The 14 days start at the revocation for a subscription that is already past_due, and at the first failed renewal otherwise. A subscription that isn’t past_due is unchanged until its next renewal fails. See Dead payment methods. Each change is reported by customer.payment_method.updated.

​

Webhooks

For Klarna payment and subscription advances, merchants receive:

• v1: payment.created, payment.updated (on each status change), and subscription.created when the subscription becomes active
• v2 (sent only when v2 webhooks are enabled): payment_v2.created, payment_v2.authorized, payment_v2.settling, payment_v2.settled, payment_v2.cancelled, and subscription_v2.created

Each of those events fires once for the matching transition. See Event Types. For a payment PayNext creates from the Stripe notification, you receive payment.created once, then one payment.updated for each status the payment reaches: AUTHORIZED, SETTLING (when Stripe reports the charge as still processing), and SETTLED. A subscription becomes active when the payment is authorized or when it settles, so subscription.created is not tied to one payment status. When a workflow decline blocks a payment because Stripe’s approval notification reached PayNext first, no payment.updated for BLOCKED is sent, so the last update you receive for the payment shows AUTHORIZED. When the customer’s return reaches the Decline step first, or for a renewal, PayNext sends payment.updated with status BLOCKED (payment_v2.blocked for v2). A payment that ends CANCELLED sends payment.updated.

​

Subscription cancelled with a voided payment

When an AUTHORIZED payment is cancelled, PayNext also cancels the subscription that payment started. This happens when you void the payment, and when Stripe cancels the hold (including when it expires). PayNext cancels the subscription with reason workflow_action. PayNext cancels the subscription only when all of these hold:

• The payment is customer-present (not a renewal) and was authorized but not captured.
• The subscription is active or in a trial.
• The subscription has no other payment in status AUTHORIZED, SETTLING, SETTLED, or REFUNDED.

Otherwise the subscription stays as it is.

​

Refunds

What a refund request does depends on the payment status:

• AUTHORIZED: PayNext voids the hold. No money is returned. See Authorize and capture.
• SETTLED or SETTLING: PayNext refunds the full amount through Stripe.
• DECLINED, FAILED, or a BLOCKED payment that never held funds: the API refuses the request with HTTP 400.

Partial refunds are not supported: a request with an amount returns HTTP 400 (even if it equals the full payment amount), or HTTP 409 if the payment is already fully refunded. A request for a CANCELLED payment, or for an AUTHORIZED payment whose void is already in progress, returns HTTP 200 and changes nothing, whatever it contains. Repeating a full refund request (without amount) also returns HTTP 200 and changes nothing when the payment already has a refund in status PENDING, DECLINED, SETTLING, or SETTLED. A refund that FAILED is sent to Stripe again. HTTP 409 is also returned when the payment is already fully refunded and has no refund record, or when another operation on the payment is in progress. Stripe’s response can settle the refund immediately (SETTLED), decline it (DECLINED), or leave it SETTLING; a SETTLING refund completes when Stripe reports the result. See Stripe Klarna docs for Klarna’s refund window at the processor.

​

Testing

​

Notes

• PayNext keeps its own internal Klarna fields out of the payment metadata in API responses and webhooks. For a payment made with a saved Klarna method on a one-off plan with the customer present, PayNext stores your return URL in klarna_return_url, and it stays visible in payment metadata. PayNext overwrites a metadata key with that name.
• Klarna options shown on Klarna’s page (pay later, installments, financing) depend on country, amount, and whether the charge is one-off or recurring — PayNext does not pre-select or restrict which option Klarna shows.
• The Klarna page language follows the locale known to checkout (mapped to Klarna’s preferred locale). When none is known, PayNext uses the language from the Accept-Language header of the request that starts the payment, and en-US if nothing maps.
• Add the Publishable Key to the Stripe integration. The checkout receives it for Klarna when it is set.
• Do not use merchant-API plan change for Klarna subscriptions; use customer-present checkout instead.