Pay Now Standalone Integration Guide

At Klarna, we're dedicated to providing customized solutions for every business scenario. That's why we are excited to introduce "Pay Now Standalone," a pioneering payment option starting with the payment method “Pay Now by Bank” designed exclusively for partners from restricted segments such as Gaming, Gambling and Crypto (see Klarna Ethical instructions for more information on restricted segments). By offering this specialized product, we ensure that partners from restricted segments can access a reliable and efficient bank transfer solution.

Consumers will be able to enjoy the familiar and seamless payment experience they're accustomed to with Klarna. Once their Klarna account/identity is verified, they have the freedom to choose their favorite way to pay. With Pay Now Standalone, instead of selecting from the various Klarna payment options available under the categories of Pay Now, Pay Later, or Pay over Time, consumers will skip the payment selection step and proceed directly with Pay Now by Bank.

With Pay Now Standalone, Klarna offers a tailored solution for restricted segments with state-of-the art technology. Pay Now Standalone covers the full order lifecycle including support for Order Management (e.g refunds). Payment status notifications will keep your systems up-to-date.

Pay Now by Bank is not a new service, in fact, it has been available for many years across all of Klarna's payment products, such as Klarna Payments and Klarna Checkout. The key differentiators to Pay Now Standalone include a modified settlement process and the introduction of a new notification system through a webhook to keep you informed about the payment status.

From an integration perspective, this means you have to integrate with Klarna payments API for the payment processing and the Order management API to support post-purchase functionalities.

It is especially important to understand when and how you create and capture an order.

• Orders: Only created orders initiate payment status notifications.
• Captures: Only captured orders initiate payouts/settlements.

In case you offer mobile apps, the Mobile SDK is the recommended and official method to integrate Klarna's products into your mobile app. 

This is particularly crucial when incorporating the payment method Bank Transfer, as it ensures a seamless experience for customers. They will be smoothly redirected back to your app after confirming the bank transfer within their banking app, which is commonly referred to as 'app2app redirects'.

Read more about the Klarna Mobile SDK here.

To facilitate testing the integration with your product, Klarna offers a dedicated environment known as the "playground". To ensure a smooth testing process, please follow the steps below and carefully review the provided information to adequately prepare for your integration work.

Follow the Testing Klarna products chapter in our documentation, and

Step 1: Create a new test account.

Step 2: Get API credentials for the playground environment via the Merchant Portal. Click in the left navigation on Payment Settings and then Klarna API Credentials.

Step 3: Share just the Username, e.g. “PKXXXXX”, with your Klarna contact. We will make a few configuration changes necessary for Pay Now Standalone and will inform you once done so you can continue testing.

Step 4: Use sample data to test your integration.
After you went through the documentation and have integrated Pay now standalone, you should familiarize yourself with the test cases, the testing procedure and the sample customer data.

Step 5: Go-live. If everything is tested (see Go-live checklist) and Klarna signed off your integration, you are ready to go-live.

Before we proceed, here are some important documentation links you should review:

• Klarna payments documentation and Klarna payments API specification.
• Order management documentation and Order Management API specification.
• Mobile SDK documentation.

From a high-level perspective, the integration process involves the following key steps:

1. Initiate a payment.
2. Check out.
3. Create an order.
4. Post-purchase activities (Order management) such as receiving payment status notifications, capturing orders or performing refunds.

By following these steps and referring to the provided documentation, you can seamlessly integrate Pay Now Standalone into your platform.

When a customer wishes to pay with Klarna, you need to start a payment session by sending a POST request to the {apiURL}/payments/v1/sessions endpoint. In this request, include the (shopping) cart details and indicate the intent of the payment.

Specifics for Pay now standalone

• For Pay Now by Bank, set intent: buy.
• Mandatory usage of the merchant_urls.authorization to get the authorization_token through a server-side Authorization callback.

IP addresses for the authorization callback

The authorization callback will use the following source IP addresses when connecting to your configured endpoint. This is important if the target systems have firewall rules that restrict the IP addresses allowed to connect.

Read all the details on Step 1: initiate a payment and Create a new payment session (API specification).

During the checkout process, your customers will be able to view Klarna as a payment option, choose it, and proceed with the purchase. To enable these customer interactions, you need to perform two main actions:

• Display Klarna as a payment method in the checkout.
• Get authorization for the purchase.

Step 2.1: Display Klarna as a payment method in the checkout

Present Pay Now Standalone in the following way in your checkout.

• Payment method descriptor: “Pay with Klarna”
• Include the Klarna badge next to the descriptor.

Specifics for Pay Now Standalone

For Pay Now Standalone integrated inline, there is no need to display the Klarna widget. However, you can use the response parameters for name and asset_urls  in payment_method_categories to dynamically display the descriptor and badge.

Step 2.2: Get authorization

In this step, you provide all the necessary customer details for Klarna to assess and decide whether to accept the purchase. This helps minimize the risk of payment defaults.

Specifics on Pay Now Standalone

• No specifics. Continue with Get authorization for In-line integrations.

For comprehensive information, please review Step 2: Check out, and remember to handle the server-side Authorization callback mentioned earlier.

Once Klarna authorises the purchase, use the authorisation token to create an order and complete the one-time payment.

Once the order is created, you will receive the first payment status notification.

Ensure to save the order ID because it is required for all post-purchase activities like captures.

Specifics for Pay Now Standalone

• If your Klarna contract allows automatic capture of the order once an order is created, set auto_capture: true when creating the order.
• There is no pending fraud status for Pay Now Standalone.

Read all details on Step 3: Create an order for one-time payments.

When your customers choose Klarna as the payment method and their orders are created, Order Management comes into play for further order processing. This solution enables various post-purchase operations like captures and refunds.

Specifics for Pay Now Standalone

• No specifics in operations, except the Payment status notifications and Settlements which are described below. You can read more about Order management and the Order management API.

Step 4.1: Payment status notifications via webhooks

Pay Now Standalone leverages a new notification system for payment status via webhooks. As mentioned earlier, once an order is created for a Pay Now by Bank payment (not yet captured), Klarna will inform you through a webhook about the payment status for that particular order.

Payment status and transitions

Here is an overview of the different payment statuses and transitions specifically for Pay Now Standalone.

Check the swimlanes for more information on the Payment status notification flows.

Payload for Payment status notifications

Once the order is created or the payment status changes, you receive a notification which contains the following data.

Example of a webhook notification:

POST /notification
Host: example.com
Date: Tue, 30 May 2023 10:25:55 GMT
Content-Type: application/json
Payload-Signature: ts=1663750989096,sig=c4031d6fdc01e6654207...e9e5f1aa5cdfc8c3a,v=1

{
  "event_id": "a48e85ea-0c24-478f-9d8d-89a8a96d137a",
  "event_type": "non_guaranteed_payment.updated",
  "occurred_at": "2023-05-30T10:25:55.000Z",

Step 4.2: Settlement reports

Settlement reports provide a detailed breakdown of all payments made by Klarna to you, facilitating the reconciliation of your accounts. Each Settlement Report includes a unique payment reference, which corresponds to the entry on your bank account statement. Settlement Reports are available in CSV, PDF or JSON format and can be accessed in three different ways - using Klarna’s Merchant Portal, the Settlements API or by Klarna-SFTP.

Specifics for Pay Now Standalone

• In the event of an order being captured but experiencing a payment default, it will result in a RETURN (type) for the order, and the corresponding amount will be deducted from the next settlement or payout.

For complete information, please refer to the details on Settlement reports and Settlements API.

Note: As Pay Now Standalone follows a non-guaranteed settlement flow, Klarna does not handle disputes. Therefore, it is your responsibility to manage any dunning, including disputes.

Soon, configuring webhooks will be possible through the Webhook Notifications page in Merchant Portal Settings. In the meantime, and if you are a Distribution Partner wanting to integrate webhooks, please contact your Solutions & Delivery lead who will assist you with the integration process.

To integrate webhooks, follow these steps: 

1. Create an HTTPS URL (endpoint) for receiving webhooks on your server
2. Generate a signing key
3. Choose the events you want to listen to
4. Verify and respond to received webhooks with a 2xx HTTP status if they are valid.

To receive webhook notifications from Klarna, set up a publicly accessible HTTPS endpoint with a valid SSL certificate.

• You can create a single endpoint to receive multiple event types or set up individual endpoints for each event type.
• If you are subscribing to events based in the EU, the server receiving the events must be physically located in the EU.

Environments

Klarna provides two publicly available environments. Refer here for more information.

• Playground.
• Production.

IP addresses for the webhook

Depending on your network and security requirements, you might need to add our network to your firewall's allowlist to receive webhook events from us. To help your integration operate securely, it must also verify that it’s communicating with Klarna through one of our listed IP addresses.

Non-breaking changes

Non-breaking changes are modifications made to a system or codebase that do not disrupt existing functionality. Some examples of these changes include:

1. Addition of HTTP headers 
2. Addition of optional or read-only fields/properties
3. Re-ordering of fields in the JSON
4. Addition of new values to an enum if there is a default defined

To verify the authenticity of notifications sent by Klarna and prevent tampering by third parties, Klarna signs the HTTP messages using a signing key generated by you. The signature is set as the `Payload-Signature` header, which is computed as the HMAC-SHA512 over the message body and the signing key.

The `Payload-Signature` header conforms to RFC 8941 – Structured Field Values for HTTP and contains 3 fields:

• ts=1663750989096 – Timestamp (milliseconds)
• sig=c4031d6fdc01e66542079… – HMAC Signature
• v=1 – Signing key version

Example of a Payload-Signature: ts=1663750989096,sig=c4031d6fdc01e66542079b0608a3886788e1cb4e7c7201de4f1fbeedf4193491e2fffe2178a04387534bd168d902751e0546bf2ffb11628e9e5f1aa5cdfc8c3a,v=1

NOTE: The Klarna-Signature header present in the HTTP message contains only the signature value. This header is deprecated and shouldn’t be used.

How to generate and set your signing key 

You can generate your signing key by any of the following commands:

You can set and update your signing key through the Merchant Portal. Simply access the appropriate settings to manage this key.

If you are a Distribution Partner, please get in touch with your Solutions & Delivery lead, who will generate a signing key for you.

Verifying signatures

To verify the signature and ensure the authenticity of the message:

1. Compute the signature by applying the HMAC-SHA512 algorithm over the HTTP message body and using your generated signing key.
2. Parse the `Payload-Signature` header and compare the `sig` field to the computed signature's hexadecimal digest.

If the values match, you can be confident that the request originated from Klarna, and you can proceed to accept the message for further processing. However, if the values do not match, reject the message and respond with an HTTP 400 Bad Request status.

You can follow the following steps to properly validate a received notification:

For payment status updates, the event "non_guaranteed_payment.updated" is always included.

Upon receiving webhooks, ensure their validity by performing the following steps:

1. Check the Object: Klarna sends event data within the POST request body. Each event contains an event_type, event_id, and occurred_at timestamp, along with relevant nested fields.
2. Send a 2xx Response: After confirming the webhook's authenticity, respond with an HTTP status code in the 2xx range if both the message and signatures are valid. If any issue arises, respond with a 403 status code. If you do not receive a message, you can provide additional data for debugging purposes using an error object/description in the response.

Retry strategy 

To acknowledge receipt of a notification, your endpoint must respond with either an HTTP 200, 201, 202, or 204 status code. Any other status code indicates that the notification couldn't be processed. In such cases, Klarna will attempt to resend the notification at increasing intervals. It is crucial to respond immediately upon receiving the notification, before proceeding with any resource-intensive server-side tasks.

Idempotent delivery

Occasionally, the same event may be delivered multiple times. Your endpoint should be idempotent, meaning it handles duplicates without affecting data integrity.

Each notification contains an event_id field, which is a unique identifier (UUIDv4). You can use this ID to identify and dismiss duplicate messages if you have already received and processed them.