On This Page

Klarna Integration Developer Guide

This section describes how to use this developer guide and where to find further information.

Audience and Purpose

This guide is written for merchants who want to offer Klarna payments services to customers. It describes tasks that a merchant must complete in order to make a payment, request the status of a payment, or refund a payment. It is intended to help the merchant provide a seamless customer payment experience.

Convention

These statements appear in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
A
Warning
 contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.

Customer Support

For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.01

Added support for Klarna chargeback notifications. See Klarna Chargebacks.
Add new status for chargebacks. See Capture a Payment and Check a Request Status.
Updated and added new workflow graphics that describe how to process Klarna transactions. See Overview of Processing Klarna Transactions.

24.01

Updated reason code descriptions.

23.03

Added link to the legacy
Klarna Services Developer Guide
. See Introduction to Klarna Integration.

23.02

Added a link to the previous version of the
Klarna Developer Guide
. See Introduction to Klarna Integration.
Added HOP and inline transaction workflows. See HOP Session Workflow and Inline Session Workflow.
Updated widget install workflow. See Widget Installation for Inline Workflow

23.01

The guide has undergone a major reorganization.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for Visa Platform Connect (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT VISA PLATFORM CONNECT ACQUIRER.

Introduction to Klarna Integration

Klarna is a Buy Now Pay Later (BNPL) payment method that you can offer your customers through
Cybersource
. With Klarna, you can enable your customers to split their payments into multiple installments. You can display the Klarna payment method to your customers during checkout by either presenting a Klarna widget or redirecting your customers to a Klarna-hosted webpage.
If you integrated with Klarna through
Cybersource
 before September 2023, review this document and reintegrate to the latest fields and values. To reference the previous version of the Klarna integration, see the no-longer-supported .

Klarna API Requests

These are the API requests you must integrate with to process a Klarna transaction:
  • Session
  • Authorization
  • Capture
  • Refund
  • Authorization-reversal
  • Check status

Requirements

You must obtain a
Cybersource
 merchant ID and a Klarna API key for each country in which you process transactions. Contact your
Cybersource
 account manager for more information.

Supported Countries and Currencies

Contact your account manager for the latest supported countries and currencies information.
For information about the country codes, currency codes, and language codes, see these relevant guides:

Klarna Review Process

Before you can launch Klarna payments, Klarna reviews your integrations. For more information about Klarna's pre-launch review process, contact your
Cybersource
 account manager.

Shipping Policies

Always follow the shipping policies for each country as outlined by Klarna to ensure that Klarna assumes liability for fraudulent transactions. For Klarna's shipping policy, see:

Disputes and Fraud

Klarna has a standard process for handling risky transactions and disputes between you and your customers. For more information, contact your technical account manager or customer support.

Chargeback Notifications

Customers can file payment disputes directly to Klarna to receive a chargeback payment for the disputed amount.
For information about setting up notifications for chargebacks, see Klarna Chargebacks.

Simple Order API Endpoints

Send your API requests to one of these
Cybersource
 endpoints using version 1.187 or later:
  • Production
    :
    https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
  • Test
    :
    https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor
Use the Klarna test triggers when directly connected to Klarna, which consist of email addresses. For more information, see:

Merchant Account Types

There are two types of
Cybersource
 merchant accounts,
Cybersource
 settlement services account
 and
processor direct contract account
.

Cybersource
 Settlement Services Account

This merchant account has no direct contract with a payment provider partner. The
Cybersource
 Financial Settlement Partner (FSP) collects funds on your behalf and settles them to your merchant account.
Cybersource
 requests the export compliance service for every transaction using the
Cybersource
 settlement services account. The export compliance service compares customer information to export control lists maintained by government agencies. If a customer's name appears on any government list, the transaction is declined.
To facilitate compliance checks for
Cybersource
 settlement services accounts, you must include these fields in your authorization service requests.
You must include these fields in the live environment to avoid receiving error messages.

Mandatory Authorization Fields for a
Cybersource
 Settlement Services Account

billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1

Processor Direct Contract Account

This merchant account must use the payment provider selected by
Cybersource
. If you have existing direct contracts, you must inform your sales representative.

Overview of Processing Klarna Transactions

This section provides an overview of the two methods for processing a payment using Klarna, as well as the order in which to send the Klarna API requests for these two methods.
There are two methods for processing a payment that are determined by how the customer accesses their Klarna account to complete the checkout:
Hosted Order Page
The customer is redirected to a Klarna-hosted order page (HOP) to complete the checkout. For overview information about how to process a payment using the HOP method, see HOP Session Workflow.
Inline
The customer uses the Klarna widget that is installed into the merchant website to complete the checkout. For overview information about how to process a payment using the inline method, see Inline Session Workflow.
For information about how to install the Klarna widget into the merchant website, see Widget Installation for Inline Workflow.

HOP Session Workflow

This workflow describes the sequence of events that comprises a successful payment using a Klarna hosted-page.

Figure:

Klarna HOP Workflow
  1. The customer begins to checkout on the merchant website and chooses the Klarna payment option.
  2. The merchant sends a HOP session API request to
    Cybersource
    . For more information, see Creating a HOP Session.
    If the customer changes their purchase selection after the merchant sends the session API request, the merchant must send an update session API request. For more information, see Updating a Session.
  3. Cybersource
     responds to the merchant with an
    INITIATED
     status and a Klarna redirect URL.
  4. The merchant redirects the customer to the Klarna URL.
  5. The customer completes checkout on the Klarna hosted-page and is redirected back to the merchant website. Klarna appends a unique authorization token to the merchant redirect URL.
  6. The merchant sends an authorization API request to
    Cybersource
     and includes the authorization token Klarna appended to the merchant URL. For more information, see Authorize a Payment.
  7. Cybersource
     responds to the merchant with the
    PENDING
     status and a request ID.
  8. The merchant sends periodic check status API requests to
    Cybersource
     with the request ID until the status updates. For more information, see Check a Request Status.
  9. Cybersource
     responds to the merchant with the
    AUTHORIZED
     status when the authorization is completed.
  10. The merchant sends a capture API request with the request ID. For more information, see Capture a Payment.
  11. Cybersource
     responds to the merchant with the
    PENDING
     status and a request ID.
  12. The merchant sends periodic check status API requests to
    Cybersource
     with the request ID until the status updates.
  13. Cybersource
     responds to the merchant with the
    SETTLED
     status when the capture is completed.
  14. The merchant displays a payment confirmation to the customer.

Inline Session Workflow

This workflow describes the sequence of events that comprises a successful payment using a Klarna widget.
For information about how to install the Klarna widget, see Widget Installation for Inline Workflow.

Figure:

Klarna Inline Workflow
  1. The customer begins to checkout on the merchant website using the displayed Klarna widget.
  2. The merchant sends an inline session API request to
    Cybersource
    . For more information, see Creating an Inline Session.
    If the customer changes their purchase selection after the merchant sends the session API request, the merchant must send an update session API request. For more information, see Updating a Session.
  3. Cybersource
     responds to the merchant with the
    INITIATED
     status and a pre-approval token.
  4. The merchant sets the
    Session Token ID
     in the Klarna widget to the pre-approval token.
  5. The customer completes checkout using the Klarna widget, and the Klarna widget generates a unique authorization token.
  6. The merchant sends an authorization API to
    Cybersource
     request and includes the unique authorization token the Klarna widget displayed. For more information, see Authorize a Payment.
  7. Cybersource
     responds to the merchant with the
    PENDING
     status and a request ID.
  8. The merchant sends periodic check status API requests to
    Cybersource
     with the request ID until the status updates. For more information, see Check a Request Status.
  9. Cybersource
     responds to the merchant with the
    AUTHORIZED
     status when the authorization is completed.
  10. The merchant sends a capture API request with the request ID. For more information, see Capture a Payment.
  11. Cybersource
     responds to the merchant with the
    PENDING
     status and a request ID.
  12. The merchant sends periodic check status API requests to
    Cybersource
     with the request ID until the status updates.
  13. Cybersource
     responds to the merchant with the
    SETTLED
     status when the capture is completed.
  14. The merchant displays a payment confirmation to the customer.

Widget Installation for Inline Workflow

This workflow describes how to install the Klarna widget and complete a successful transaction. For a description of a successful transaction with the Klarna widget already installed, see Inline Session Workflow.

Figure:

Widget Installation for Inline Workflow
  1. Add the container for the Klarna widget to the HTML for your checkout page. This is a one-time operation and provides an iframe into which the Klarna widget will be dynamically loaded when the Klarna widget is initialized. 
    <div id=#klarna_container"></div>
  2. When the customer displays your checkout page, send a create session request to
    Cybersource
    . The sessions service creates a unique customer session and returns a pre-approval token. See Creating a HOP Session and Updating a Session.
  3. Present the available payment methods to the customer. When the customer chooses the Klarna payment method on your checkout page, install the Klarna software developer kit (SDK) and initialize it by calling
    Klarna.Payments.init
    . In the request, set the client token field to the value of the pre-approval token returned by
    Cybersource
    .
    Initializing the Klarna SDK can take up to 10 seconds.
    Cybersource
     recommends that you try to initialize the SDK every three seconds, up to a maximum of three attempts.
    For additional information about initializing the Klarna SDK, see: 
    Klarna.Payments.init({client_token: '<%=processorToken%>'})
    if (count < 3)
    {    
        setTimeout(initializeKlarna.bind(null, count), 3000);
    }
    else
    {
        showError()
    }
  4. Load the Klarna widget into the Klarna container by calling
    Klarna.Payments.load
     and specifying the Klarna container. 
    Klarna.Payments.load({
    container: "#klarna_container",
    (...)
})
  5. Display the Klarna payment options on your checkout page. The
    show_form = true
     statement dynamically updates the payment options in the Klarna widget. 
    if (res["show_form"] == true)
{
    logging("Klarna Available Payment Option");

    document.getElementById("auth_button").innerHTML =
    "<br><button type=\"button\" name=\"buy\"
    onclick=\"authorizeKlarnaOrder();\">Pay</button>"
}
else
{
    logging("Klarna Not Available As A Payment Option");
}
  6. When the customer chooses one of the Klarna payment options:
    Klarna.Payments.authorize({}, function(res) {
    var auth_token = res["authorization_token"];
    var isApproved = res["approved"];
    var show_form = res["show_form"];
})
  7. Klarna validates the customer’s information and determines whether to authorize the order. When Klarna authorizes the order, Klarna returns an authorization token.
  8. Send an authorization request to
    Cybersource
    . Set the pre-approval token field to the value of the authorization token returned by Klarna. See Authorize a Payment.
  9. When
    Cybersource
     approves the authorization, send a capture request to complete the purchase. See Capture a Payment.
    When the authorization response indicates that the purchase is pending, send a check status request every hour until the payment status changes. See Check a Request Status.

Refunding a Payment Workflow

This workflow describes the sequence of events that comprises issuing a successful refund with Klarna.

Figure:

Refund Workflow
  1. The customer returns the purchase to the merchant.
  2. The merchant sends a refund API request to
    Cybersource
     with the request ID from the successful capture. For more information, see Refund a Payment.
  3. Cybersource
     responds to the merchant with the
    PENDING
     status and a refund request ID.
  4. The merchant sends periodic check status API requests to
    Cybersource
     until the status updates. For more information, see Check a Request Status.
  5. Cybersource
     responds to the merchant with the
    REFUNDED
     status when the refund is processed.
  6. The merchant displays a refund confirmation to the customer.

Reversing an Authorized Payment Workflow

This workflow describes the sequence of events that comprises reversing an authorization, also known as cancelling a payment, with Klarna.

Figure:

Authorization Reversal Workflow
  1. The customer begins to checkout on the merchant website and either chooses the Klarna payment option or uses the Klarna widget.
  2. The merchant sends either a HOP or inline session API request to
    Cybersource
    . For more information, see Creating a HOP Session and Creating an Inline Session.
  3. Cybersource
     responds with the initiated status and either a Klarna redirect URL or Klarna pre-approval token.
  4. The merchant either redirects the customer to a Klarna URL or sets the Klarna widget to a unique token.
  5. The customer completes the checkout using either the Klarna URL or widget. If the customer used the Klarna URL, the customer is redirected to the merchant website.
  6. The merchant sends an authorization API request to
    Cybersource
    . For more information, see Authorize a Payment.
  7. Cybersource
     responds to the merchant with the
    PENDING
     status and an authorization request ID.
  8. The merchant sends periodic check status requests to
    Cybersource
     with the authorization request ID.
  9. Cybersource
     responds to the merchant with the
    AUTHORIZED
     status when the authorization is complete.
  10. The customer or merchant decides to cancel the payment.
  11. The merchant sends an authorization reversal API request to
    Cybersource
    . For more information, see Reverse an Authorized Payment.
  12. Cybersource
     responds to the merchant with the
    AUTH_REVERSED
     status.
  13. The merchant displays a payment cancellation confirmation to the customer.

Transaction Statuses Workflow

This workflow describes the sequence of possible statuses you can receive when processing a Klarna transaction.

Figure:

Transaction Statuses Workflow
  1. The merchant sends a session API request to
    Cybersource
     and receives one of these possible statuses:
    • COMPLETED
      : The customer completed the checkout process. You can now authorize the funds.
    • 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.
  2. The merchant sends an authorization API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The authorization request is not successful. Send a new authorization request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The authorization request is accepted but is not authorized. Request the check status service to retrieve status updates. For more information, see Check Status.
  3. The merchant sends a check status API request to
    Cybersource
     and receives one of these possible statuses:
    • ABANDONED
      : The customer did not complete the payment using the redirect URL or widget.
    • AUTHORIZED
      : The customer's funds are authorized. You can now capture the authorized amount.
    • FAILED
      : The authorization request is not successful. Send a new authorization request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The authorization request is successful and is still processing. Request the check status service again to retrieve status updates.
  4. If the customer or merchant decides to cancel the purchase, the merchant sends an authorization reversal API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The authorization reversal is not successful. Send a new request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • AUTH_REVERSED
      : The authorization is successfully reversed.
  5. The merchant sends a capture API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The capture request is not successful. Send a new capture request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The capture request is accepted but is not completed. Request the check status service again to retrieve status updates.
    • SETTLED
      : The capture request is settled for the requested amount.
  6. The merchant sends a check status for the capture API request to
    Cybersource
     and receives one of these possible statuses:
    • CHARGEBACK
      : The customer submitted a payment dispute for the purchase, and Klarna reviewed and approved a chargeback to the customer. For more information about chargebacks, see Klarna Chargebacks.
    • FAILED
      : The capture request is not successful. Send a new capture request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The capture request is accepted but is not completed. Request the check status service again to retrieve status updates.
    • SETTLED
      : The capture request is settled for the requested amount.
  7. If the customer returns a purchase, the merchant sends a refund API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The refund request is not successful. Send a new refund request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The refund request is successful and is currently processing. Request the check status service again to retrieve status updates.
    • REFUNDED
      : The captured payment is successfully refunded.
  8. The merchant sends a check status for the refund API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The refund request is not successful. Send a new refund request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
    • PENDING
      : The refund request is successful and is currently processing. Request the check status service again to retrieve status updates.
    • REFUNDED
      : The captured payment is successfully refunded.

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.
  1. 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.
    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.
    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
    Set to
    true
    .
    Set to
    N
    .
    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}}
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
  2. 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.
  3. To include an optional coupon in the request, include these fields:
    Set to
    coupon
    .
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
  4. Redirect the customer to the URL in the
    merchantURL
     response field.
    <merchantURL>
    https://pay.playground.klarna.com/na/hpp/payments/1vmXvue
    </merchantURL>
  5. 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
  6. 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>

Creating an Inline Session

Create a new session whenever the customer displays your checkout page.
Inline Specifications
When you send a session request, set the
apSessionsService_paymentFlowMode
 field to
inline
.
Cybersource
 responds with a pre-approval token in the
apSessionsReply_processorToken
 field. Set the Klarna widget installed in the merchant website to token. When the customer completes the checkout using the Klarna widget, the widget responds with an authorization token. Include the authorization token in the authorization request to link the authorization 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>

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.

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

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 an Inline Session

Follow these steps to successfully create an inline session.
  1. 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.
    Set to
    KLI
    .
    apSessionService_paymentFlowMode
    Set to
    inline
     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.
    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
    Set to
    true
    .
    Set to
    N
    .
    Set to the URL to which the customer is redirected after successfully completing the Klarna payment.
    Add
    /Klarna/Reply.jsp
     to the end of the URL.
    https://www.test.com
    /Klarna/Reply.jsp
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
  2. 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.
  3. To include an optional coupon in the request, include these fields:
    Set to
    coupon
    .
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
    Replace the
    #
     character with the number
    0
     for the first item and consecutive numbers for any additional items.
  4. Set the Session Token ID in the Klarna widget to the
    processorToken
     field value from the session response.
    ID
    eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy...
  5. When the customer completes the payment using the Klarna widget, the Klarna widget creates a unique authorization token. Store the token for the authorization request.
    Authorizaiton Token: 
    a6b2229c-665b-5660-a5fe-063bef3d9a1e
  6. When you send the follow-on authorization request, set the
    apAuthService_preapprovalToken
     request field to the authorization token value created by the Klarna widget.
    <preapprovalToken>a6b2229c-665b-5660-a5fe-063bef3d9a1e</preapprovalToken>

XML Example: Creating a Session

Inline 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>john@email.com</email>
	</billTo>
	<item>
		<unitPrice>9.00</unitPrice>
		<quantity>1</quantity>
		<productCode>A4890B5023</productCode>
		<productName>Skirt on the sky</productName>
		<productSKU>skirtonsky$bluegreen</productSKU>
		<taxAmount>1.00</taxAmount>
		<totalAmount>10.00</totalAmount>
		<productDescription>Amnesiac Shirt</productDescription>
	</item>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>10.00</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>KLI</apPaymentType>
	<apSessionsService run="true">
		<cancelURL>https://www.merchant.com/Klarna/Reply.jsp</cancelURL>
		<successURL>https://www.merchant.com/Klarna/Reply.jsp</successURL>
		<failureURL>https://www.merchant.com/Klarna/Reply.jsp</failureURL>
		<sessionsType>N</sessionsType>
		<paymentMethod_name>pay_now</paymentMethod_name>
		<paymentFlowMode>inline</paymentFlowMode>
	</apSessionsService>
</requestMessage>
Inline Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6958601255246857703007</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeTn93WXAQw5f/6IZYjWmdmbZq0orKCojmjrTtjSBX0GY0MmkmXoxZaH/pN5Of3dZcBDDl8AA9DNl</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<apSessionsReply>
		<reasonCode>100</reasonCode>
		<responseCode>00000</responseCode>
		<processorToken>eyJhbGciOiJSUzI1NiIsIm_TEST_TOKEN_1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhM</processorToken>
		<amount>10.00</amount>
		<reconciliationID>XFZ3YMYURE2A</reconciliationID>
		<status>COMPLETED</status>
		<dateTime>2023-09-28T00:15:26Z</dateTime>
	</apSessionsReply>
</replyMessage>

Updating a Session

You can update a session for 48 hours after creating it. The session update service enables you to update items in the cart and customer information, with or without sending customer billing details. However, when you send customer billing details in the session update request, send as many billing details as possible for the best customer checkout experience. For a list of all of the information you can update in a session, see the Optional Fields for Updating a Session.
Updating a session requires the request ID from the original session, which is in the
requestID
 response field.
Only update a session after the customer consents to sharing their data with Klarna.
PII data about a customer should be sent only after the customer chooses the Klarna payment option on your checkout page and consents to sharing their data with Klarna.

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>

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

Response Status

The session service responds with one of these statuses as the
apSessionReply_status
 field value:
  • INITIATED
    : The session is initiated and the customer may now checkout.
  • COMPLETED
    : The customer completed the checkout process.
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.

Response Statuses

The session service responds with one of these statuses as the
apSessionReply_status
 field value:
  • COMPLETED
    : The customer completed the checkout process.
  • INITIATED
    : The session is initiated and the customer may now checkout.
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.

Required Fields for Updating a Session

Set to
KLI
.
apSessionsService_cancelURL
Set to the URL the customer is directed to after cancelling the Klarna payment.
Set to the URL the customer is directed to after the Klarna payment fails.
apSessionsService_requestID
Set to
true
.
Set to
U
.
Set to the URL the customer is directed to after successfully completing the Klarna payment.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.

Country-Specific Fields

Coupon Fields

To include a coupon in your request, include these fields.
Set to
coupon
.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.

Optional Fields for Updating a Session

These are the optional fields you can include to update an existing session.
Set to the same value as the
billTo_state
 field if the field is present.
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.
Set to the same value as the
billTo_district
 field.

XML Example: Updating a Session

Request
<requestMessage
	xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<billTo>
		<firstName>Anna</firstName>
		<lastName>Schmidt</lastName>
		<street1>Leopoldstrasse 4</street1>
		<street2>Apt 2</street2>
		<city>Lichtenberg</city>
		<district>Berlin</district>
		<state>Berlin</state>
		<postalCode>10318</postalCode>
		<country>DE</country>
		<phoneNumber>5551234567</phoneNumber>
		<email>
test@cybs.com
</email>
		<dateOfBirth>19820101</dateOfBirth>
		<language>DE-DE</language>
	</billTo>
	<shipTo>
		<firstName>Anna</firstName>
		<lastName>Schmidt</lastName>
		<street1>Leopoldstrasse 4</street1>
		<street2>Apt 2</street2>
		<city>Lichtenberg</city>
		<state>Berlin</state>
		<district>Berlin</district>
		<postalCode>10318</postalCode>
		<country>DE</country>
		<phoneNumber>5551234567</phoneNumber>
		<email>
test@cybs.com
</email>
	</shipTo>
	<item id="0">
		<unitPrice>19.99</unitPrice>
		<quantity>1</quantity>
		<productName>Green Widget</productName>
		<taxAmount>1.00</taxAmount>
		<totalAmount>20.99</totalAmount>
	</item>
	<item id="1">
		<unitPrice>10.00</unitPrice>
		<quantity>2</quantity>
		<productName>Blue Widget</productName>
		<taxAmount>2.00</taxAmount>
		<totalAmount>22.00</totalAmount>
	</item>
	<item id="2">
		<unitPrice>5.00</unitPrice>
		<quantity>1</quantity>
		<productName>shipping</productName>
		<totalAmount>5.00</totalAmount>
	</item>
	<purchaseTotals>
		<currency>EUR</currency>
		<discountAmount>3.00</discountAmount>
		<grandTotalAmount>44.99</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>KLI</apPaymentType>
	<apSessionsService run="true">
		<sessionsType>U</sessionsType>
		<sessionsRequestID>4848446567036715804007</sessionsRequestID>
	</apSessionsService>
</requestMessage>
Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>4848446567036715804007</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<purchaseTotals>
		<currency>EUR</currency>
	</purchaseTotals>
	<apSessionsReply>
		<reasonCode>100</reasonCode>
		<responseCode>00000</responseCode>
	</apSessionsReply>
</replyMessage>

Authorize a Payment

Authorizing a purchase requires the Klarna generated token from a completed session creation. Set the
apAuthService_preapprovalToken
 request field value to the token value. Where you retrieve the token is dependent on whether you created a HOP session or inline session. If you created a HOP session, the token is appended to the success URL the customer is redirected to after completing the checkout using their Klarna account. If you created an inline session, the token is generated by the Klarna widget when the customer completes the checkout.
After authorizing a payment, you can capture the authorization for up to 28 days.

Merchant-Defined Data

Merchant-defined data is included in the
merchantDefinedData_mddField_5
 field.
This field has replaced the
merchantDefinedData_field5
 field. If you submit a request with the
merchantDefinedData_field5
 field,
Cybersource
 automatically replaces the field with
merchantDefinedData_mddField_5
.
You are prohibited from including personally identifying information (PII) in the
merchantDefinedData
 fields for the purposes of capturing, obtaining, and/or transmitting any PII. PII includes, but is not limited to, address, credit card number, social security number, driver's license, state-issued identification number, passport number, and card verification number (CVV, CVC2, CVV2, CID, CVN). In the event
Cybersource
 discovers you are capturing and/or transmitting PII in the
merchantDefinedData
 fields, whether or not intentionally,
Cybersource
 immediately suspends your merchant account, which results in a rejection of any and all transaction requests submitted by the merchant account after the point of suspension.

Endpoints

Set the
apAuthService_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

Response Status

The authorization service responds with one of these statuses as the
apAuthReply_status
 field value:
  • FAILED
    : The authorization request is not successful. Send a new authorization request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The authorization request is accepted but is not authorized. Request the check status service to retrieve status updates. For more information, see Check Status.
The authorization service also responds with a reason code as the
apAuthReply_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 a pending authorization, you can receive this status when the authorization updates:
  • AUTHORIZED
    : The customer's funds are authorized. You can now capture the authorized amount.

Required Fields for an Authorization

Set to the token value created by Klarna.
If you created a HOP session, the token is appended to the merchant success URL.
If you created an inline session, the token is generated by the Klarna widget.
Set to
true
.
Set to
KLI
.
Set to the same value used in the sessions request.
merchantDefinedData_mddField_5
Set to the same value used in the create session request. Possible values:
  • HOP
    : display the Klarna widget on your checkout page.
  • inline
    : redirect the customer to the Klarna-hosted page.
Set to the same value as the
purchaseTotals_grandTotalAmount
 field in the latest sessions update request.

Country-Specific Fields

XML Example: Authorization

Authorization 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>Happy St</street1>
		<street2>123</street2>
		<city>Austin</city>
		<district>TX</district>
		<state>TX</state>
		<postalCode>78757</postalCode>
		<country>US</country>
		<email>
test@cybs.com
</email>
	</billTo>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>154.50</grandTotalAmount>
	</purchaseTotals>
	<merchantDefinedData>
		<field5>inline</field5>
	</merchantDefinedData>
	<apPaymentType>KLI</apPaymentType>
	<apAuthService run="true">
		<preapprovalToken>d9b4496b-f4b1-5ad5-bbe0-7f6666821260</preapprovalToken>
	</apAuthService>
</requestMessage>
Authorization Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6957570615206883603012</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeSuwS73eT7JE/6IZYjWmdqbZrNGMpuojmjMMSTSB3i0ZiwyaSZejFlof+k3krsEu93k+yRAABS1G</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<exportReply>
		<reasonCode>100</reasonCode>
		<ipCountryConfidence>-1</ipCountryConfidence>
	</exportReply>
	<apReply>
		<productID>paylaterbycard</productID>
	</apReply>
	<apAuthReply>
		<reasonCode>100</reasonCode>
		<status>AUTHORIZED</status>
		<processorResponse>00003</processorResponse>
		<amount>154.50</amount>
		<dateTime>2023-09-26T19:37:43Z</dateTime>
		<paymentStatus>authorized</paymentStatus>
		<responseCode>00003</responseCode>
		<reconciliationID>XFZ3ZMYV41J7</reconciliationID>
		<processorTransactionID>a3367116-69e7-4ddf-b1fe-645413b6c63d</processorTransactionID>
	</apAuthReply>
</replyMessage>

Update an Authorized Payment

Successfully processed authorizations can be updated as follow-on authorizations before you capture or reverse the payment. Follow-on authorizations enable you to update the billing, shipping, itemization, and item break up information of already submitted orders. When updating an authorization, set the
linkToRequest
 field to the
requestID
 field value from the original authorization response in order to link your request to the original authorization.

Endpoints

Set the
apAuthService_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

Response Status

The authorization service responds with one of these statuses as the
apAuthReply_status
 field value:
  • AUTHORIZED
    : The payment is successfully authorized.
  • FAILED
    : The authorization request failed.
  • PENDING
    : The authorization request is accepted but is not authorized. Request the check status service to retrieve status updates. For more information, see Check Status.

Required Fields for Updating an Authorization

Set to the token generated by Klarna.
Set to
true
.
Set to
KLI
.
Set to the same value used in the sessions request.
Set to the
requestID
 from the initial authorization response.
merchantDefinedData_mddField_5
Set to the same value used in the create session request. Possible values:
  • HOP
    : display the Klarna widget on your checkout page
  • inline
    : redirect the customer to the Klarna-hosted page
Set to the same value as the
purchaseTotals_grandTotalAmount
 field in the latest sessions update request.

Country-Specific Fields

Include these country-specific field in addition to the required fields listed above.

Example: Updating an Authorized Payment

Follow-on Authorization Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<billTo>
		<firstName>Jane</firstName>
		<lastName>Smith</lastName>
		<street1>Happy St</street1>
		<street2>456</street2>
		<city>Austin</city>
		<district>TX</district>
		<state>TX</state>
		<postalCode>78797</postalCode>
		<country>US</country>
		<email>
test@cybs.com
</email>
	</billTo>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>10.00</grandTotalAmount>
	</purchaseTotals>
	<merchantDefinedData>
		<field5>inline</field5>
	</merchantDefinedData>
	
<linkToRequest>6958684668456844304007</linkToRequest>

	<apPaymentType>KLI</apPaymentType>
	<apAuthService run="true">
		<preapprovalToken>9cb0b304-c901-5a58-afd5-06c87d7bb217</preapprovalToken>
	</apAuthService>
</requestMessage>
Follow-on Authorization Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6958688084846249104011</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeTsyWHVD+dKL/6IZYjWmjCbZrSIzSWojmjst4nSBX0GY0MmkmXoxZaH/pN5OzJYdUP50osAA8wHb</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<exportReply>
		<reasonCode>100</reasonCode>
		<ipCountryConfidence>-1</ipCountryConfidence>
	</exportReply>
	<apReply>
		<productID>paylaterbycard</productID>
	</apReply>
	<apAuthReply>
		<reasonCode>100</reasonCode>
		<status>AUTHORIZED</status>
		<processorResponse>00003</processorResponse>
		<amount>10.00</amount>
		<dateTime>2023-09-28T02:40:10Z</dateTime>
		<paymentStatus>authorized</paymentStatus>
		<responseCode>00003</responseCode>
		<merchantURL>https://js.playground.klarna.com/na/kp/v1/sessions/f2bebdbb-b46c-551e-a8a4-048a4a185c10/redirect</merchantURL>
		<reconciliationID>XFZ40MYVHF4K</reconciliationID>
		<processorTransactionID>fc2b177e-f70a-4ff6-8847-3ab7b8db6d9c</processorTransactionID>
	</apAuthReply>
</replyMessage>

Reverse an Authorized Payment

The authorization reversal service enables you to reverse the amount that was authorized. To reverse an authorization, you must have the authorization request ID, which is the
requestID
 field value from the authorization response. To reverse a follow-on authorization, use the request ID from the follow-on authorization response.

Endpoints

Set the
apAuthReversalService_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

Response Status

The authorization reversal service responds with one of these statuses as the
apAuthReversalReply_status
 field value:
  • PENDING
    : The authorization reversal request is successful and is currently processing. Send periodic check status requests until you receive an updated status. For more information, see Check a Request Status.
  • FAILED
    : The authorization reversal is not successful. Send a new request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
The authorization reversal service also responds with a reason code as the
apAuthReversalreply_reasonCode
 field value. For more information on reason codes, see the Reason Codes for the Simple Order API.
When you send a check status request for a pending authorization reversal, you can receive this status when the authorization reversal updates:
  • AUTH_REVERSED
    : The authorization is successfully reversed.

Required Fields for Authorization Reversal

Include these required fields to reverse an authorization.
Set to the request ID included in the authorization response. If you sent a follow-on authorization, use the request ID from the follow-on authorization response.
Set to
true
.
Set to
KLI
.

XML Example: Authorization Reversal

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>ref-123456</merchantReferenceCode>
	<apPaymentType>KLI</apPaymentType>
	<apAuthReversalService run="true">
		<authRequestID>6958688084846249104011</authRequestID>
	</apAuthReversalService>
</requestMessage>
Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6958693435966100704008</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeTtFW0Xx4YsI/6IZYjWmjCbZrSIzaQojmjs01PSBX0GY0MmkmXoxZaH/pN5OzJYdUP50osAAFAIu</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<apAuthReversalReply>
		<reasonCode>100</reasonCode>
		<status>AUTH_REVERSED</status>
		<processorResponse>00007</processorResponse>
		<amount>10.00</amount>
		<dateTime>2023-09-28T02:49:04Z</dateTime>
		<paymentStatus>auth_reversed</paymentStatus>
		<responseCode>00007</responseCode>
		<reconciliationID>XFZ40MYVHF6H</reconciliationID>
	</apAuthReversalReply>
</replyMessage>

Capture a Payment

The capture service enables you to capture the entire authorized amount or part of the authorized amount. Klarna supports multiple capture requests when the total amount of all captures is less than the authorized amount.
You can capture an authorization for up to 28 days after a payment is authorized.

Endpoints

Set the
apCaptureService_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

Response Statuses

The capture service responds with one of these statuses as the
apCaptureReply_status
 response field value:
  • FAILED
    : The capture request is not successful. Send a new capture request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The capture request is accepted but is not captured. Request the check status service to retrieve status updates. For more information, see Check Status.
The capture service also responds with a reason code as the
apCaptureReply_reasonCode
 field value. For more information on reason codes, see the Reason Codes for the Simple Order API.
When you send a check status request for a pending capture, you can receive this status when the status updates:
  • CHARGEBACK
    : The customer submitted a payment dispute for the purchase, and Klarna reviewed and approved a chargeback to the customer. For more information about chargebacks, see Klarna Chargebacks.
  • SETTLED
    : The capture request is settled for the requested amount.

Required Fields for a Capture

Optional Fields for a Capture

Choose from these optional fields to include additional information when capturing a payment.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.

XML Example: Capture

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>154.50</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>KLI</apPaymentType>
	<apCaptureService run="true">
		<authRequestID>6957570615206883603012</authRequestID>
	</apCaptureService>
</requestMessage>
Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6957576170986768803011</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeSvECLGs0aTD/6IZYjWmrWbZoV7NKCojmjMTOvSB3i0ZiwyaSZejFlof+k3krsEu93k+yRAAAy04</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<apCaptureReply>
		<reasonCode>100</reasonCode>
		<status>SETTLED</status>
		<processorResponse>00004</processorResponse>
		<amount>154.50</amount>
		<dateTime>2023-09-26T19:46:58Z</dateTime>
		<reconciliationID>XFZ55MYPWYRA</reconciliationID>
		<paymentStatus>settled</paymentStatus>
		<responseCode>00004</responseCode>
	</apCaptureReply>
</replyMessage>

Refund a Payment

Refunding a payment returns the entire captured amount or part of the captured amount to the customer's account. Klarna supports multiple refund requests when the total amount of all refunds is less than the captured amount.'
Cybersource
 recommends using the optional fields for a refund to ensure the request is successful. For more information, see Optional Fields for a Refund.

Endpoints

Set the
apRefundService_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

Response Statuses

The refund service responds with one of these statuses as the
apRefundReply_status
 field value:
  • FAILED
    : The refund request is not successful. Send a new refund request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The refund request is accepted but is not refunded. Request the check status service to retrieve status updates. For more information, see Check a Request Status.
  • REFUNDED
    : The captured payment is successfully refunded.

Required Fields for a Refund

Include these required fields to

Optional Fields for a Refund

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.
Set to
coupon
.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.

XML Example: Refund

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<purchaseTotals>
		<currency>USD</currency>
		<grandTotalAmount>154.50</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>KLI</apPaymentType>
	<apRefundService run="true">
		<refundRequestID>6957576170986768803011</refundRequestID>
	</apRefundService>
</requestMessage>
Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6957582387066840103011</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeSvaHi+ZXThj/6IZYjWmrWbZoV7NKCojmjMcX7SB3i0ZiwyaSZejFlof+k3krsEu93k+yRAABS1G</requestToken>
	<purchaseTotals>
		<currency>USD</currency>
	</purchaseTotals>
	<apRefundReply>
		<reasonCode>100</reasonCode>
		<transactionID>b30d7de1-215d-4989-8b82-f190d39457a4</transactionID>
		<status>REFUNDED</status>
		<processorResponse>00006</processorResponse>
		<amount>154.50</amount>
		<dateTime>2023-09-26T19:57:19Z</dateTime>
		<reconciliationID>XFZ55MYPWYRA</reconciliationID>
		<returnRef>XFZ40MYVGPWJ</returnRef>
		<paymentStatus>refunded</paymentStatus>
		<responseCode>00006</responseCode>
	</apRefundReply>
</replyMessage>

Check a Request Status

Request the check status service when the authorization response status is
PENDING
. A pending status occurs when Klarna reviews an authorization.
Cybersource
 recommends that you request the check status service hourly until the payment status changes.

Endpoints

Set the
apCheckStatusService_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

Response Statuses

The check status service responds with one of these statuses in the
apCheckStatusReply_status
 field value:
Session
  • 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.
Authorization
  • AUTHORIZED
    : The customer's funds are authorized. You can now capture the authorized amount.
  • FAILED
    : The authorization request is not successful. Send a new authorization request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The authorization request is successful and is still processing. Request the check status service again to retrieve status updates.
Authorization Reversal
  • AUTH_REVERSED
    : The authorization is successfully reversed.
  • FAILED
    : The authorization reversal is not successful. Send a new request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The authorization reversal request is accepted but is not completed. Request the check status service again to retrieve status updates.
Capture
  • CHARGEBACK
    : The customer submitted a payment dispute for the purchase, and Klarna reviewed and approved a chargeback to the customer. For more information about chargebacks, see Klarna Chargebacks.
  • FAILED
    : The capture request is not successful. Send a new capture request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The capture request is accepted but is not completed. Request the check status service again to retrieve status updates.
  • SETTLED
    : The capture request is settled for the requested amount.
Refund
  • FAILED
    : The refund request is not successful. Send a new refund request. A failed request can be due to either Klarna rejecting the transaction or a technical error.
  • PENDING
    : The refund request is successful and is currently processing. Request the check status service again to retrieve status updates.
  • REFUNDED
    : The captured payment is successfully refunded.

Required Fields for Check Status

Set to the request ID included in the service response you are checking.
Set to
true
.
Set to
KLI
.

XML Example: Check Status

Request
<requestMessage
	xmlns="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantID>test_merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<apPaymentType>KLI</apPaymentType>
	<apCheckStatusService run="true">
		<checkStatusRequestID>6957582387066840103011</checkStatusRequestID>
	</apCheckStatusService>
</requestMessage>
Response
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.213">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>6957587006586637103010</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<requestToken>AxjnrwSTeSvqh51d5a+i/6IZYjWmjCbZrR6FeUojmjMjRvSB3i0ZiwyaSZejFlof+k3kr2h4vmV04YwAnSiT</requestToken>
	<apCheckStatusReply>
		<reasonCode>100</reasonCode>
		<reconciliationID>XFZ40MYVGPWJ</reconciliationID>
		<paymentStatus>refunded</paymentStatus>
	</apCheckStatusReply>
</replyMessage>

Reference Information

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.

US Grand Total with Coupons

To calculate the grand total amount for US transactions with coupons, use this formula:
sum of (unit price x quantity) for all items + item-level tax amount – sum of (
coupon
 amount x quantity) for all items – item-level discount amount
This is the same formula with the respective API fields:
sum of (
item_#_unitPrice
 x
item_#_quantity
) for all items +
purchaseTotals_taxAmount
 – sum of coupons (
item_#_unitPrice
 x
item_#_quantity
) –
purchaseTotals_discountAmount
US Grand Total Amount with Coupons
This example shows the proper syntax and calculation of a grand total amount within an API request.
<item id="0">
    <unitPrice>100</unitPrice>
    <quantity>1</quantity>
    <totalAmount>100</totalAmount>
</item>
<item id="1">
    <unitPrice>75</unitPrice>
    <quantity>2</quantity>
    <totalAmount>150</totalAmount>
</item>
<item id="2">
    <unitPrice>30</unitPrice>
    <quantity>1</quantity>
    <productCode>coupon<productCode>
    <productName>first-time customer<productName>
    <productSKU>12345</productSKU>
</item>
<purchaseTotals>
    <taxAmount>40</taxAmount>
    <discountAmount>10</discountAmount>
    <grandTotalAmount>250</grandTotalAmount>
</purchaseTotals>

US Grand Total without Coupons

To calculate the grand total amount for US transactions without coupons, use this formula:
sum of (unit price x quantity) for all items + item-level tax amount – item-level discount amount
This is the same formula with the respective API fields:
sum of (
item_#_unitPrice
 x
item_#_quantity
) for all items +
purchaseTotals_taxAmount
 –
purchaseTotals_discountAmount
Grand Total Amount
This example shows the proper syntax and calculation of a grand total amount within an API request.
<item id="0">
    <unitPrice>100</unitPrice>
    <quantity>1</quantity>
    <totalAmount>100</totalAmount>
</item>
<item id="1">
    <unitPrice>75</unitPrice>
    <quantity>2</quantity>
    <totalAmount>150</totalAmount>
</item>
<purchaseTotals>
    <discountAmount>10</discountAmount>
    <taxAmount>40</taxAmount>
    <grandTotalAmount>280</grandTotalAmount>
</purchaseTotals>

Non-US Countries Grand Total with Coupons

To calculate the grand total amount for non-US transactions with coupons, use this formula:
sum of (unit price x quantity) for all items + sum of (item-level tax amount) for all items – sum of (coupon amount x quantity) for all items – item-level discount amount
This is the same formula with the respective API fields:
sum of (
item_#_unitPrice
 x
item_#_quantity
) for all items + sum of (
item_#_taxAmount
) for all items – sum of coupons (
item_#_unitPrice
 x
item_#_quantity
) for all times –
purchaseTotals_discountAmount
Grand Total Amount
This example shows the proper syntax and calculation of a grand total amount within an API request.
<item id="0">
    <unitPrice>100</unitPrice>
    <quantity>1</quantity>
    <taxAmount>20</taxAmount>
    <totalAmount>120</totalAmount>
</item>
<item id="1">
    <unitPrice>75</unitPrice>
    <quantity>2</quantity>
    <taxAmount>20</taxAmount>
    <totalAmount>170</totalAmount>
</item>
<item id="2">
    <unitPrice>30</unitPrice>
    <quantity>1</quantity>
    <productCode>coupon<productCode>
    <productName>first-time customer<productName>
    <productSKU>12345</productSKU>
<purchaseTotals>
    <discountAmount>10</discountAmount>  
    <grandTotalAmount>290</grandTotalAmount>
</purchaseTotals>

Non-US Countries Grand Total without Coupons

To calculate the grand total amount for non-US transactions without coupons, use this formula:
sum of (unit price x quantity) for all items + sum of (item-level tax amount) for all items – item-level discount amount
This is the same formula with the respective API fields:
sum of (
item_#_unitPrice
 x
item_#_quantity
) for all items + sum of (
item_#_taxAmount
) for all items
Grand Total Amount
This example shows the proper syntax and calculation of a grand total amount within an API request.
<item id="0">
    <unitPrice>100</unitPrice>
    <quantity>1</quantity>
    <totalAmount>120</totalAmount>
</item>
<item id="1">
    <unitPrice>75</unitPrice>
    <quantity>2</quantity>
    <taxAmount>20</taxAmount>
    <totalAmount>170</totalAmount>
</item>
<purchaseTotals>
    <grandTotalAmount>280</grandTotalAmount>
</purchaseTotals>

Using 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.
These fields are required for each line item that you use:
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Including Line Items in a Service Request
This example shows three valid line items.
<item id="0">
	<productCode>123456</productCode>
	<productDescription>Red</productDescription>
	<productName>Shirt</productName>
	<quantity>1</quantity>
	<unitPrice>30.00</unitPrice>
</item>
<item id="1">
	<productCode>456789</productCode>
	<productDescription>Green</productDescription>
	<productName>Pants</productName>
	<quantity>3</quantity>
	<unitPrice>19.99</unitPrice>
</item>
<item id="2">
	<productCode>987654</productCode>
	<productDescription>Blue</productDescription>
	<productName>Dress</productName>
	<quantity>2</quantity>
	<unitPrice>25.50</unitPrice>
</item>

Reason Codes and Klarna Response Codes

Response fields and reason codes can be added at any time.
Cybersource
 recommends these best practices to ensure you keep up-to-date with the latest possible responses:
  • Parse the response data according to the field names instead of the field order in the response message. For more information about parsing response fields, see the documentation for your client.
  • Your error handler must be able to process new reason codes without problems.
  • Your error handler must use the
    decision
     field to determine the result if it receives a reason code that it does not recognize.
This table lists the possible reason codes that are returned by the
Simple Order API
 in the
reasonCode
 field. For a list of all of the possible reason codes and descriptions, see the .
Reason Codes
Reason Code
Processor Response Code
Description
100
  • 00000—status: completed.
  • 00001—status: pending.
  • 00002—status: abandoned.
  • 00003—status: authorized.
  • 00004—status: settled.
  • 00006—status: refunded.
  • 00008—status: reversed.
  • 00009—status: cancelled.
  • 00010—status: accepted.
  • 00011—status: chargeback.
  • 00012—status: settle_initiated.
  • 00013—status: settle_accepted.
  • 00014—status: refund_initiated.
  • 00015—status: active.
  • 00016—status: revoked.
  • 00017—status: expired.
  • 00020—status: refund_rejected.
The transaction was successful.
101
The request is missing one or more required fields. Examine the response fields
missingField_0
 through
missingField_N
 to identify which fields are missing. Resend the request with all the required fields.
102
  • 10000—status: failed.
One or more fields in the request contain invalid data. Examine the response fields
invalidField_0
 through
invalidField_N
 to identify which fields are invalid. Resend the request with valid data.
150
  • 20000—status: failed.
  • 20001—status: failed.
  • 20002—status: failed.
  • 30000—status: failed.
  • 30100—status: failed.
A system error caused the request to fail. You must design your transaction management system to include a way to correctly handle system errors. Depending on which payment processor is handling the transaction, the error might indicate a valid
Cybersource
 system error, or it might indicate a processor rejection because of invalid data. For either reason,
Cybersource
 recommends you to not design your system to keep resending a transaction when a system error occurs. See the documentation for the
Cybersource
 client (SDK) that you are using for important information about how to handle system errors and retries.
Other possible reasons for a failed status:
  • The signature was not included in the HTTP header.
  • The signature in the HTTP header has expired or it is not a valid signature.
151
The request was received but a server timeout occurred. This error does not include timeouts that occur between the client and the server. To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the
Business Center
. See the documentation for your
Cybersource
 client for information about handling retries in the case of system errors.
152
The request was received, but a service did not finish processing in time. To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the
Business Center
. See the documentation for your
Cybersource
 client for information about handling retries in the case of system errors.
153
Your account is not enabled for the OCT service. Contact your
Cybersource
 account manager to have your account enabled for this service.
202
The payment method is expired. You might also receive this value if the expiration date that you provided does not match the date that the issuing bank has on file. Request a different form of payment.
203
  • 30000—status: failed.
  • 30100—status: failed.
  • 30200—status: failed.
  • 30400—status: failed.
  • 30500—status: failed.
The payment method was declined. No other information was provided by the issuing bank. Request a different form of payment.
204
  • 30350—status: failed.
The account does not contain sufficient funds. Request a different form of payment.
223
  • 30600—status: failed.
  • 30700—status: failed.
The processor declined the transaction due to tax errors or government compliance errors.
233
  • 30600—status: failed.
  • 30700—status: failed.
The processor declined the payment method. For more information about the decline, search for the transaction in the
Business Center
 and view the transaction details. Request a different form of payment.

Klarna Chargebacks

Customers can file payment disputes directly to Klarna to receive a chargeback payment for the disputed amount.
Eligibility
Only captured payments that are in the settled status can be issued a chargeback.
Results
If Klarna approves the customer's payment dispute, you are charged for the disputed amount and a chargeback fee. These charges are deducted from your next settlement and the invoice will document the chargeback details. The disputed payment amount is issued to the customer by Klarna.
If Klarna does not approve the customer's payment dispute, you are charged for any fees associated with the dispute.
Cybersource
 is not involved with the payment dispute review process. All payment disputes are handled between the customer and Klarna.

Generating Reports Using the
Business Center

You can generate various types of reports for your financial and reconciliation data. For more information about how to automate your reports, see the
Reporting Developer Guide
. For more information about how to use your
Business Center
 account to generate reports, see the
Reporting User Guide
.
The
Reporting User Guide
 contains these relevant topics:
  • How and When Reports Are Generated
  • Downloading Available Reports
  • Subscribing to Standard Reports

Additional Resources

For additional information about how to use the
Business Center
 and work with reports, see these helpful resources.
Business Center
 Navigation
For an overview of the various resources available in the
Business Center
, see this YouTube video:
Getting Started with the
Business Center
For a step-by-step demonstration of how to navigate in the
Business Center
, see this YouTube video:
Managing Report Subscriptions
For an overview of how to manage report subscriptions in the Downloadable Reports section in the
Business Center
, see this YouTube video:
Downloading Reports
For an overview of how to download available reports in the Reports section in the
Business Center
, see this YouTube video:

Simple Order
 API Field Map

Field Map
Klarna API Field Name
Simple Order
 API Field Name
authorization_token
apAuthService_preapprovalToken
billing_address.city
billTo_city
billing_address.country
billTo_country
billing_address.email
billTo_email
billing_address.family_name
billTo_lastName
billing_address.given_name
billTo_firstName
billing_address.phone
billTo_phoneNumber
billing_address.postal_code
billTo_postalCode
billing_address.region
billTo_district
billing_address.street_address
billTo_street1
billing_address.street_address2
billTo_street2
billing_address.title
billTo_title
customer.date_of_birth
billTo_dateOfBirth
customer.gender
billTo_gender
locale
billTo_language
merchant_urls.confirmation
apAuthService_successURL
options.color_border
apUI_colorBorder
options.color_border_selected
apUI_colorBorderSelected
options.color_button
apUI_colorButton
options.color_button_text
apUI_colorButtontext
options.color_checkbox
apUI_colorCheckbox
options.color_checkbox_checkmark
apUI_colorCheckboxCheckMark
options.color_header
apUI_colorHeader
options.color_link
apUI_colorLink
options.color_text
apUI_colorText
options.payment_method_category
paymentMethod_name
options.radius_border
apUI_borderRadius
order_amount
purchaseTotals_grandTotalAmount
order_lines.name
item_#_productName
order_lines.reference
item_#_productSKU
order_lines.tax_rate
item_#_taxRate
order_lines.total_amount
item_#_totalAmount
order_lines.unit_price
item_#_unitPrice
order_lines.quantity
item_#_quantity
order_lines.tax_amount
item_#_taxAmount
purchase_country
billTo_country
purchase_currency
purchaseTotals_currency
shipping_address.city
shipTo_city
shipping_address.country
shipTo_country
shipping_address.email
shipTo_email
shipping_address.family_name
shipTo_lastName
shipping_address.given_name
shipTo_firstName
shipping_address.phone
shipTo_phoneNumber
shipping_address.postal_code
shipTo_postalCode
shipping_address.region
shipTo_district
shipping_address.street_address
shipTo_street1
shipping_address.street_address2
shipTo_street2
shipping_address.title
shipTo_title

Optional Fields for an Authorization

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.
Set to
coupon
.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.
Replace the
#
 character with the number
0
 for the first item and consecutive numbers for any additional items.