On This Page

Creating a HOP Session

Create a new session whenever the customer displays your checkout page.

HOP Specifications: When you send a HOP session request, set the
apSessionsService_paymentFlowMode
field value to
HOP
. Cybersource responds with a Klarna redirect URL in the
apSessionsReply_merchantUrl
field. Send the customer to the redirect URL to complete the checkout. When the customer completes the checkout, Klarna redirects the customer back to the merchant website and includes a token in the merchant URL. The token generated by Klarna can then be used in the authorization request to link it to the session.

Klarna Payment Methods

When you request the session service, you can determine the Klarna payment method you want to offer your customers. Set the optional

paymentMethod_name

request field to a value listed in the Payment Method column.

Payment Methods
Payment Method Field Value	Description	Klarna Products
pay_later	Customer pays total bill at a set date.	Klarna Invoice Klarna Pay Later Klarna Pay Later by Card (PLBC)
pay_now	Customer pays total bill at the time of checkout.	Klarna Direct Bank Transfer Klarna Direct Debit
pay_over_time	Customer pays bill in equal multiple installments.	Klarna Account Klarna Financing Klarna Fixed Installment Plans Klarna Interest Free

Example: Payment Methods in Session Request: <paymentMehtod_name>pay_later
</paymentMethod_name>

Calculating the Grand Total Amount

Klarna requires that the grand total amount of a purchase be included in the request using the

purchaseTotals_grandTotalAmount

field. The country of the transaction and the use of coupons affect how to calculate the grand total amount.

For more information about how to calculate the grand total amount, see Calculating the Grand Total Amount in the Reference Information section.

Language Specification

To set the language for your Klarna checkout experience, include the

billTo_language

field in your request. By not including this field, the Klarna checkout experience is set to English by default. For a list of all possible values, see the ISO Standard Language Codes
guide.

Example: Language Specification: <billTo> <language>es</language> </billTo>

Endpoints

Set the

apSessionsService_run

field to

true

, and send the request to one of these endpoints:

Production:

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

Test:

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Line Items

Klarna uses line items when you send a create session and update session requests. Line items are used to include information about the goods that your customers purchase, such as product name, quantity, and price.

Line items are represented as the

item_#_

fields, starting with

item_0_

, and increasing in numerical order.

For more information about how to properly format line items in your request, see Using Line Items in the Reference Information section.

Response Status

The session service responds with one of these statuses as the

apSessionReply_status

field value:

FAILED

: The session request is not successful. Send a new session request.

INITIATED

: The session is initiated and the customer may now checkout. Send periodic check status requests until the status updates to

COMPLETED

. For more information, see Check a Request Status.

The session service also responds with a reason code as the

apSessionReply_reasonCode

field value. For more information about reason codes, see the Reason Codes for the Simple Order API.

When you send a check status request for an initiated session, you can receive one of these statuses when the session updates:

ABANDONED

: The customer did not complete the payment using the redirect URL or widget.

COMPLETED

: The customer completed the checkout process. You can now authorize the funds.

Requesting to Create a HOP Session

Follow these steps to successfully create a HOP session.

Send a request to the

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

endpoint and include these required fields:

Do not send any personally identifiable information (PII) data about the customer in the request to create a session.

apPaymentType: Set to
KLI
.
apSessionService_paymentFlowMode: Set to
HOP
to display the Klarna widget on your checkout page.
apSessionsService_cancelURL: Set to the URL to which the customer is redirected after cancelling the Klarna payment.
apSessionsService_failureURL: Set to the URL to which the customer is redirected after the Klarna payment fails.
apSessionsService_paymentMethod_name: Set to one of these values to display the Klarna product you are offering:; pay_later
: pay later
pay_now
: pay now
pay_over_time
: pay over time
apSessionsService_run: Set to
true
.
apSessionsService_sessionsType: Set to
N
.
apSessionsService_successURL: Set to the URL to which the customer is redirected after successfully completing the Klarna payment.; Include
?auth-token={{authorization_token}}
to the end of the URL.; Example:
https://www.merchant.com
?auth-token={{authorization_token}}
billTo_country
item_#_productName: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_quantity: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_totalAmount: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_unitPrice: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
merchantID
merchantReferenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Non-US Countries: item_#_taxAmount
US: billTo_state; purchaseTotals_taxAmount

You can include these optional fields in the request:

billTo_language: If this field is not included, the language is set to English by default.; For a list of possible values, see the ISO Standard Language Codes
guide.
purchaseTotals_discountAmount

To include an optional coupon in the request, include these fields:

item_#_productCode: Set to
coupon
.; Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_productName: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_productSKU: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_quantity: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.
item_#_unitPrice: Replace the
#
character with the number
0
for the first item and consecutive numbers for any additional items.

Redirect the customer to the URL in the

merchantURL

response field.

<merchantURL>https://pay.playground.klarna.com/na/hpp/payments/1vmXvue</merchantURL>

When the customer completes the checkout using their Klarna credentials, Klarna redirects the customer to the URL you specified in the

apSessionsService_successURL

request field. Klarna appends the merchant's success URL with a unique Klarna generated token.

https://www.test.com?auth-token=d9b4496b-f4b1-5ad5-bbe0-7f666682126

When you send the authorization request, set the

apAuthService_preapprovalToken

field to the unique token Klarna appended to the success URL.

<preapprovalToken>d9b4496b-f4b1-5ad5-bbe0-7f666682126</preapprovalToken>

XML Example: Creating a Session

HOP Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<billTo>
		<firstName>John</firstName>
		<lastName>Smith</lastName>
		<street1>123 Happy St</street1>
		<city>Sunnyville</city>
		<state>VA</state>
		<postalCode>12345</postalCode>
		<country>US</country>
		<email>test@cybs.com</email>
	</billTo>
	<item>
		<unitPrice>150.00</unitPrice>
		<quantity>1</quantity>
		<productCode>A4890B5023</productCode>
		<productName>Skirt on the sky</productName>
		<productSKU>skirtonsky$bluegreen</productSKU>
		<taxAmount>4.50</taxAmount>
		<totalAmount>154.50</totalAmount>
		<productDescription>Amnesiac Shirt</productDescription>
	</item>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>154.50</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>kli</apPaymentType>
	<apSessionsService run="true">
		<cancelURL>https://www.merchant.com</cancelURL>
		<successURL>https://www.merchant.com?auth-token={{authorization_token}}</successURL>
		<failureURL>https://www.merchant.com</failureURL>
		<sessionsType>N</sessionsType>
		<paymentMethod_name>pay_now</paymentMethod_name>
		<paymentFlowMode>HOP</paymentFlowMode>
	</apSessionsService>
</requestMessage>

HOP Response

<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6957556550046839703010</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeSt+U42aL4Xi/6IZYjWmdqbZrNGMSeojmjL6m3SB3i0ZiwyaSZejFlof+k3krflONmi+F4gA7yG1</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<apSessionsReply>
		<reasonCode>100</reasonCode>
		<responseCode>00000</responseCode>
		<merchantURL>https://pay.playground.klarna.com/na/hpp/payments/1vmXvue</merchantURL>
		<processorToken>eyJhbGciOiJSUzI1NiIsI_TEST_TOKEN_I4MTEtMzYzNy1hYTRjLTY2ZW</processorToken>
		<amount>154.50</amount>
		<reconciliationID>XFZ3ZMYV41DO</reconciliationID>
		<status>COMPLETED</status>
		<dateTime>2023-09-26T19:14:16Z</dateTime>
	</apSessionsReply>
</replyMessage>