Klarna payments with SourcesBeta
We recommend using the Payment Intents and Payment Methods APIs to integrate Klarna. See the Klarna Payments with Payment Methods guide.
Stripe users in Europe and the United States can enable Klarna payments using Sources—a single integration path for creating payments using any supported method.
Supported countries
During the payment process, a Source object is created and your customer is either presented with a Klarna widget or redirected to a Klarna Hosted Payment Page that displays payment options, including Pay now, Pay later, and Financing. Your integration then uses the source to make a charge request and complete the payment.
Within the scope of Sources, Klarna is a push-based, single-use and synchronous or asynchronous method of payment.
U.S. users can accept payments from U.S. customers, and European users can accept payments from European buyers. The payment options that Klarna offer are based on the customer’s location. The table below shows payment options available to customers by country.
Customer’s country | Currency | Installments | Pay later | Financing | Pay now |
---|---|---|---|---|---|
Austria | EUR | 30 days | |||
Belgium | EUR | 30 days | |||
Denmark | DKK | 30 days | |||
Finland | EUR | 30 days | |||
France | EUR | Pay in 3 | |||
Germany | EUR | 30 days | |||
Ireland | EUR | Pay in 3 | |||
Italy | EUR | Pay in 3 | |||
Netherlands | EUR | 30 days | |||
Norway | NOK | 30 days | |||
Spain | EUR | Pay in 3 | |||
Sweden | SEK | 30 days | |||
United Kingdom | GBP | Pay in 3 | 30 days | * | |
United States | USD | Pay in 4 | * |
Prerequisite: Update Terms and Conditions
Prior to processing live transactions with Klarna, it’s important that you update your Terms and Conditions and Privacy Policy, per Klarna’s requirements.
Create a Source object
A Source
object is either created client-side using Stripe.js or server-side using the Source creation endpoint. Updatable fields enable you to create a source without providing personally identifiable information (PII), which must be added later using a source update once the customer selects Klarna as a payment option.
Note that if you are operating in one of Klarna’s Restricted Business List Categories, you will also need to add additional purchase information using the klarna[attachment]
field.
Parameter | Value | |
---|---|---|
type | klarna | |
amount | A positive integer in the smallest currency unit representing the amount to charge the customer (for example, 1099 for a 10.99 GBP payment). | |
currency | The currency the payment is being created in. Supported values are eur, sek, nok, dkk, gbp, usd. This must be the default currency of your customer’s billing address country. | |
klarna[product] | payment (Klarna requires for routing as a payment) | |
klarna[purchase_country] | The ISO-3166 2-letter country code of the customer’s location. | |
source_order[items] | The order object associated with this payment. The order items amounts must add up to the amount of the source. | |
owner[email] | updatable | The email address of the customer. |
owner[address] | updatable | The billing address of the customer. |
klarna[first_name] | updatable | The first name of the customer (Klarna requires the customer’s name to be passed as separate first and last name values). |
klarna[last_name] | updatable | The last name of the customer. |
source_order[shipping][address] | updatable | The shipping address of the customer. Only required if a physical product is being sold that must be shipped |
source_order[shipping][carrier] | updatable | The delivery service used to ship a physical product, such as FedEx, UPS, USPS, and so on |
source_order[shipping][tracking_number] | optional | The tracking number obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas. |
source_order[shipping][phone] | optional | Recipient phone (including extension). |
klarna[shipping_first_name] | updatable | The first name used on the shipping address (Klarna requires the shipping name to be passed as separate first and last name values). |
klarna[shipping_last_name] | updatable | The last name used on the shipping address. |
klarna[shipping_delay] | updatable | The delay in days before the order is shipped. Please contact us at Stripe support if you would like to use this parameter. |
klarna[locale] | optional | Format locales as a language tag consisting of a two-letter language code combined with a two-letter country code, according to RFC 1766. Examples are en-us for U.S. English, en-gb for British English, and sv-se for Swedish (in Sweden). (RFC1766). |
klarna[attachment] | optional | Additional purchase information relating to the transaction that may be required for select businesses, such as those on Klarna’s Restricted List to increase approval rates. Values provided vary based on business type and can be found on Klarna’s site |
To create a Klarna source, call stripe.createSource()
with the relevant details:
stripe.createSource({ type: 'klarna', amount: 816, currency: 'eur', klarna: { product: 'payment', purchase_country: 'DE', }, source_order: { items: [{
Using either server-side or client-side source creation, Stripe returns a Source
object containing the relevant details for the method of payment used. Information specific to Klarna is provided within the klarna
subhash.
{ "id": "src_16xhynE8WzK49JbAs9M21jaR", "object": "source", "amount": 1099, "client_secret": "src_client_secret_qxC8aTQt9mSnwh29lLgP9pfb", "created": 1445277809, "currency": "eur", "flow": "none", "klarna": { "locale": "de-DE",
Error codes
Source creation for Klarna payments may return any of the following errors:
Error | Description |
---|---|
payment_method_not_available | The payment method is currently not available. Invite your customer to fallback to another payment method to proceed. |
processing_error | An unexpected error prevented us from creating the source. Retry source creation. |
missing_sku_item_quantity | The SKU provided in the order is missing a quantity value. |
country_currency_mismatch | The currency is not the default currency of the customer’s billing address country. |
country_not_supported | The country is not supported for the currency being used. |
invalid_currency | The currency is not supported. |
invalid_email | The owner’s email is not valid. |
invalid_phone | The owner’s phone number is not valid. |
invalid_address | The specified address is not valid. |
Update the source
If customer details are not provided at source creation, they must be added using a source update.
Billing information
Billing information is required for physical goods and, if not provided during source creation a source update is required. If the billing address is provided but the shipping address isn’t, Klarna will assume the shipping address is the same as the billing address. If neither the billing or shipping address is provided, Klarna will collect the billing address during the checkout, and assume the shipping address is the same as the billing address. In both circumstances, if the order’s shipping address differs from the billing address, Klarna will not cover any losses that might occur due to customer disputes or fraud.
Parameter | Value |
---|---|
klarna[first_name] | The first name of the customer (Klarna requires the customer’s name to be passed as separate first and last name values). |
klarna[last_name] | The last name of the customer. |
owner[email] | The email address of the customer. |
owner[address] | The billing address of the customer. |
See an example of updating a source with billing information:
Shipping information
If selling a physical product that must be shipped, shipping information is required. If not provided during creation, shipping information should be provided in a source update.
Parameter | Value |
---|---|
klarna[shipping_first_name] | The first name used on the shipping address (Klarna requires the shipping name to be passed as separate first and last name values). |
klarna[shipping_last_name] | The last name used on the shipping address. |
source_order[shipping][phone] | Recipient phone (including extension). |
source_order[shipping][address] | The shipping address of the customer. |
See an example of updating a source with shipping information:
Tracking information
Additionally, to assist Klarna with any customer requests about a physical shipment, you can update the source to include tracking information.
Parameter | Value |
---|---|
source_order[shipping][carrier] | The delivery service used to ship a physical product, such as FedEx, UPS, USPS, and so on |
source_order[shipping][tracking_number] | The tracking number obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas. |
Here is an example of how to update a source with tracking information:
Attachment
For businesses on Klarna’s Restricted List, it’s recommended that you update the source to include additional purchase information relating to the transaction via the klarna[attachment]
parameter.
Parameter | Value |
---|---|
klarna[attachment] | Additional purchase information relating to the transaction that may be required for select businesses, such as those on Klarna’s Restricted List to increase approval rates. Values provided vary based on business type and can be found on Klarna’s site |
See below for an example of updating a source with an event
attachment.
Authorize the payment with Klarna
There are two ways to have your customer authorize the payment: you can use a Klarna widget embedded in your page or you can redirect the customer to a Klarna Hosted Payment Page that displays payment options including Pay now, Pay later, and Financing.
When you create a source, its status is initially set to pending
and it can’t yet be used to make a charge request. The payment must first be submitted to Klarna for authorization. Once authorized, the source becomes chargeable.
To load the Klarna widget and verify that a payment has been authorized, use the Klarna JavaScript SDK:
- Add the SDK to your checkout page and initialize it using
Klarna.Payments.init()
with the value fromsource.klarna.client_token
. - Load a widget for each
category
, usingKlarna.Payments.load()
and a value forcontainer
to specify the DOM element where you want the widget rendered. Categories are different payment options Klarna offers. See the list of values you can pass forcategory
inload()
insource.klarna.payment_method_categories
. The response fromload()
includesshow_form: true/false
, which indicates whether the Klarna payment option should remain available, based on Klarna’s risk assessment. - Use
Klarna.Payments.authorize()
to submit the payment with the selected category to Klarna for authorization.
For Klarna’s new markets (Austria, Spain, and Italy), Klarna only returns one payment method category in source.klarna.payment_method_categories
: pay_later
. All of the payment options for that market, as determined by the availability table, are rendered within the load()
call when you pass pay_later
.
As the customer interacts with the Klarna widget, they may be asked for additional information, depending on the jurisdiction they are in.
If an attempt to authorize a payment fails, that category is removed from the list of available payment_method_categories
on the source, and reloading the Klarna widget will return show_form: false
. The source status will stay pending
until the last method is failed, at which point the source status will become failed
.
Testing the authorization process
When creating a Source
object using your test API keys, use the returned klarna[client_token]
with the same Klarna SDK. With a test client token, the Klarna widget doesn’t request any additional customer information as part of the authorization process. The test source then becomes chargeable and you can use it to create a test charge. When using test API keys, no credit issuance or money movement happens. It’s always safe to interact with test client tokens. Klarna provides multiple test inputs so that you can test check your integration with various payment flows, which are outlined in the below section on Testing Klarna Payments.
Step 2a: Authorizing the payment using a redirect
As an alternative to their recommended widget-based authorization, Klarna also supports a full-redirect authorization specifically designed for both desktop and mobile experiences. To leverage the redirect flow, you create the source using these additional arguments:
Parameter | Value |
---|---|
flow | redirect |
redirect[return_url] | The URL the customer should be redirected to after the authorization process. |
stripe.createSource({ type: 'klarna', flow: 'redirect', redirect: { return_url: '__TOKEN_PLACEHOLDER_0__', }, // ... }).then(function(result) { // handle result.error or result.source });
When flow
is set to redirect, Stripe returns a Source
of flow redirect. To allow your customer to authorize the payment, redirect them to one of the URLs provided within the Source
object, eg: klarna[pay_later_redirect_url]
, klarna[pay_over_time_redirect_url]
or klarna[pay_now_redirect_url]
.
For Klarna’s new markets (Austria, Spain, and Italy), Klarna only returns one payment method category in source.klarna.payment_method_categories
: klarna[pay_later_redirect_url]
. All of the payment options for that market, as determined by the availability table, are rendered within the Klarna payments page when you redirect to that URL.
If the customer is redirected to redirect[url]
, Pay later will be used if it’s available.
{ "id": "src_16xhynE8WzK49JbAs9M21jaR", "object": "source", "amount": 1099, "client_secret": "src_client_secret_qxC8aTQt9mSnwh29lLgP9pfb", "created": 1445277809, "currency": "eur", "flow": "redirect", "klarna": { "locale": "de-DE",
After the authorization process, your customer is redirected back to the URL provided as the value of redirect[return_url]
. This happens regardless of authorization success or failure. Stripe appends redirect[return_url]
with a redirect_status
parameter, with the following potential values:
Value | Description | Suggested Action |
---|---|---|
succeeded | The customer completed the payment flow. | Use the source in a charge request. |
canceled | The customer abandoned the payment flow. | Reload the checkout page with the same options |
failed | The customer was not eligible for the selected Klarna method. | Reload the checkout page with the remaining eligible Klarna payment_method_categories |
If the customer authorizes the payment, the Source
object’s status transitions to chargeable
when it is ready to be used in a charge request. If your customer declines the payment and no other payment_method_categories
are available, the status transitions to failed
.
Testing the redirect process
When creating a Source
object using your test API keys, follow any one of the URLs returned in the klarna[***_redirect_url]
field. This leads to a Klarna page that displays information about the test payment, where you can either authorize or cancel the payment. Authorizing the payment redirects you to the URL specified in redirect[return_url]
but doesn’t attempt to charge or contact the customer.
Charge the source
Once Klarna authorizes the payment, the source’s status
transitions to chargeable
and it can be used to make a charge request.
Since that transition happens asynchronously, it is essential that your integration rely on webhooks to determine when the source becomes chargeable in order to create a charge. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.
Webhooks
The following webhook events are also sent to notify you about changes to the source’s status:
Event | Description |
---|---|
source.chargeable | A source object becomes chargeable after it has been authorized by Klarna. |
source.failed | A source object failed to become chargeable. |
source.canceled | A source object expired and cannot be used to create a charge. |
Make a charge request to finalize the authorization
After the source is chargeable, from your source.chargeable
webhook handler, you can make a charge request using the source ID as the value for the source
parameter to complete the payment. The amount must match the Source object’s amount.
When selling physical goods, you should pass the capture: false
flag to the charge request to let Klarna know that you’re working on fulfilling the order. After all items have been shipped, send a capture request to let Klarna know that the order has been fulfilled. Only one capture, less than or equal to the charge amount, is permitted. Any remaining amount is released back to the customer.
Note that the charge must be captured by midnight of the 28th calendar day after the charge request, otherwise the authorization will expire. For example, a charge request at UTC 2020-10-01 14:00 must be captured by UTC 2020-10-29 00:00.
Klarna Sources are single-use and cannot be used for recurring or additional payments. Refer to our Sources & Customers guide for more information on how single-use Source
objects interact with Customer
objects.
Optional: Authorizing the payment and capturing immediately
By omitting the capture parameter or sending capture: true
, Klarna assumes that the order is immediately fulfilled. This is handy if you’re selling digital goods.
Confirm that the charge has succeeded
Klarna is asynchronous for payments made by customers in the UK and U.S., and synchronous otherwise. When async for the UK and U.S., the Charge object’s status remains in a pending state for up to 24 hours from its creation. Once the charge is confirmed—and the funds guaranteed—its status is updated to succeeded
.
All other supported countries are synchronously approved. The Charge object’s status immediately reflects whether or not it has succeeded.
One of the following events is sent when the charge’s status is updated:
Event | Description |
---|---|
charge.succeeded | The charge succeeded and the payment is complete. |
charge.failed | The charge has failed and the payment could not be completed. |
We recommend that you rely on the charge.succeeded
webhook event to notify your customer that the payment process has been completed and their order is confirmed. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.
Stop payment
Klarna may request additional information relating to high risk orders and in some cases require that you cancel and create a refund for orders that haven’t shipped. Generally, failure to respond within 24 hours may result in a dispute at a later date. Refer to the Klarna shipping policies for more details.
Refunds
Payments made with Klarna can only be submitted for refund within 180 days from the date of the original charge. After 180 days, it is no longer possible to refund the charge.
Klarna supports both full and partial refunds. When you create a refund for the full amount of the charge, the Klarna order is voided, and if funds had been moved by the customer, Klarna will return these funds. You can also issue multiple partial refunds, up to the amount of the original charge. A partial refund will update the Klarna order to reflect the new total amount, and if funds were moved by the customer, Klarna will return the difference.
You can submit a refund against charges that are still pending and have not yet been confirmed. If you create a full or partial refund on a pending charge, the refund is performed only after the charge’s status is transitioned to succeeded
. In the event of the charge transitioning to status failed, full and partial refunds are marked as canceled, as the money never left the customer’s bank account.
Disputes
Klarna may initiate a dispute if the customer claims that you haven’t delivered the relevant goods or services as expected. Before initiating a dispute, Klarna will contact you via email, providing details of the customer’s claim. Klarna may request additional information in order to resolve it. If Klarna ultimately rules in favor of the customer, they may initiate a dispute.
If Klarna creates a dispute, a charge.dispute.created
webhook event is sent and Stripe deducts the amount of the dispute from your Stripe balance.
Klarna disputes are final and there is no appeal process.
Source expiration
A source must be used within one hour of becoming chargeable
. If unused after an hour, its status automatically transitions to canceled
and your integration receives a source.canceled
webhook event.
Testing Klarna payments
Below is a set of test email addresses and test credit repayment options outlined by customer country. You can use these to test Klarna payments under various conditions while you develop your Klarna integration. Additional Klarna-specific test card and bank account numbers can be found in Klarna’s Testing Environment documentation.