Guide customers through Klarna’s step-up authentication process by integrating the Purchase Journey for seamless payment completion.
As seen previously, upon calling Klarna's Payment Authorization API it is possible to trigger a step-flow. In such scenario, the Payment Authorization API returns a Payment Request in the response. The expectation is that the consumer will go through Klarna’s Purchase Journey to complete the payment, usually triggering authentication and payment option selection.
How Partner will redirect customer to Klarna's Purchase Journey
The Payment Request is the resource used to let the consumer go through Klarna's Purchase Journey. For this to happen, Acquiring Partners have to:
- Properly configure the step up configuration upon calling Payment Authorization API
- Use the response from the Payment Authorization API together with the Klarna SDK to trigger the Klarna Purchase Journey
To create a Payment Request, Acquiring Partners must configure multiple properties based on their integration. These properties depend on the Partner's own implementation and require specific values to be provided to Klarna through the Acquiring Partner's APIs:
- A
return_urlwhere the customer is redirected after approving the payment. - An
app_return_urlused when redirecting the customer to a mobile banking application.
For Partners to be able to ensure a seamless experience across different ecosystems, Klarna supports multiple integration patterns that require data points sent by Partners:
Redirection after customer accepts the Payment
Klarna needs to be able to return the consumer to the Partner through an HTTP redirection. This can be achieved either through the Acquiring Partner’s usual integration mechanism, or by allowing the Partner to explicitly submit a Klarna redirect URL and forward it on the configuration.
website redirection
When the Acquiring Partner is already asking a suitable return_url from the Partner, it is advised to not ask for a second one as this would increase the minimal integration requirements for Klarna to work.
The Partner-facing field should be named either klarna_return_url or return_url in a Klarna-specific context, ensuring that it’s easy for any Partner to identify and use. In case the Acquiring Partner has a global handling of redirection, this field can be avoided as long as it is clear for the Partner.
Handover to third-party applications during Klarna's Purchase Journey
Klarna needs to be able to handover to a Mobile Application and return back. In many flows happening on a mobile application, Klarna will try to handover to its own application or any other Mobile Bank Application for approvals.
App handover diagram
For the experience to work, Partners have to be able to define an Mobile Application return URL. This parameter can either be generic to the Acquiring Partner’s API or specific to Klarna. When the Acquiring Partner is already asking a suitable app_return_url from the Partner, it is advised to not ask for a second one as this would increase the minimal integration requirements for Klarna to work.
The Partner-facing field should be named either klarna_app_return_url or app_return_url in a Klarna-specific context, ensuring that it’s easy for any Partner to identify and use. In case the Acquiring Partner has a global handling of redirection, this field can be avoided as long as it is clear for the Partner.
To build the step-up configuration, Acquiring Partners have to build the different values required using the values received from the Partners and their own infrastructure.
Return URL
As previously mentioned, return_url should be either the Acquiring Partner's own mechanism, or directly the value coming from the Partner.
It is possible to add Placeholders in the return_url. Read more about it in the section to track the Payment Request state.
Acquiring Partners can provide an internal return_url instead of the Partner’s own confirmation url. This enables the Acquiring Partner to be in control of the final redirection and create the transaction before redirecting the customer to the Partner confirmation page.
While this is convenient, webhook integration is still mandatory as redirection of the customer back to the return_url cannot be guaranteed in many flows, especially in the mobile ecosystem. By doing so, the Acquiring Partner can make sure that no transaction creation is lost.
App Return URL
In most cases, the app_return_url is directly owned by the Partner. But similarly, if the Acquiring Partner is already requesting such a parameter, then it can be directly re-used.
Parameters
| initiationMode | Description |
|---|---|
DEVICE_BEST | Automatically selects the best way to launch the Klarna Purchase Journey depending on the device - this is the default and recommended value:
|
ON_PAGE | The Klarna Purchase Journey is triggered on the same page. The customer never leaves the page. The Klarna Purchase Journey is open in a pop-up if possible and fallback to fullscreen iframe if necessary. |
REDIRECT | The customer will be redirected to the Klarna Purchase Journey.Note: a return_url is required either in the step_up_config object when calling the Payment Authorize API or in the paymentButton authorize options |
returnUrl: This url will be used by Klarna SDK to redirect the customer. This parameter can be used to override thereturn_urlprovided through the Payment Authorize API as described in the previous section.
The Klarna Purchase Journey allows the customer to choose their payment method and input any necessary information. The process also requires the customer to log in to their Klarna account, if needed, to proceed with the payment.
Phone collection in the Klarna Purchase Journey
After completing these steps, the customer is automatically redirected to the URL specified in the customer_interaction_config.return_url.
When the consumer has been approved by Klarna, the Acquiring Partner will receive a webhook with the payment_token that can be used to finalize the authorization of the payment.
The Klarna SDK enables Acquiring Partners to register event handlers to follow the different stage of the purchase and provide the best user experience to consumers.
The on(event: "complete", callback: OnCompleteCallback) method in the Klarna SDK is an essential tool to detect the completion of a payment request. By registering an event handler, you can dynamically respond to updates related to the ongoing payment request.
When involved in a redirection flow, the handler activates once your page has loaded. This feature ensures that all pending updates are handled immediately upon registration of the event handler, eliminating the need for polling. This is particularly useful for maintaining smooth and responsive payment processing workflows.
The OnCompleteCallback allows you to access various properties of the ongoing paymentRequest. This access allows developers to handle payment requests with greater precision and awareness of the payment’s current state: