Klarna integration guide

KlarnaKlarna Klarna is a payment provider allowing consumers to pay using their payment methods saved to their Klarna account. This section is intended to help you implement Klarna based on your preferred integration workflow.

Services and compatibility

Payment method gateway nameKlarna Payments (klarnaPayments)
Klarna Checkout (klarnaCheckout)
Supported transaction types
Supported integration methods
Supported processing currenciesFor Klarna Payments:
  • AUD, CAD, CHF, DKK, EUR, GBP, NOK, NZD, SEK, USD
For Klarna Checkout:
  • AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD
Webhook event types
  • TRANSACTION_AUTHORIZED
  • TRANSACTION_CAPTURED
  • TRANSACTION_REFUNDED
  • TRANSACTION_SETTLED

Gateway-specific information

Nexio supports the following countries and regions for the customer's billing country with Klarna:

  • Australia (AU)
  • Austria (AT)
  • Canada (CA)
  • Denmark (DK)
  • Finland (FI)
  • Germany (DE)
  • Great Britain (GB)
  • The Netherlands (NL)
  • New Zealand (NZ)
  • Norway (NO)
  • Sweden (SE)
  • Switzerland (CH)
  • United States (US)

The merchant needs to go through Klarna’s underwriting process and the merchant needs to contract with Klarna directly for them to provision a production merchant ID (MID) with the payment methods for the region that the merchant wants to process. Only the payment methods approved and contracted with Klarna and the merchant will be the ones available at checkout for the consumer.

Configuration

Apart from working with Integrations Support to add Klarna as a payment method, you do not need to do any other configuration steps. In order to add Klarna, Integrations Support needs your Klarna username, password, and clientID.

If you want to add Pay Later messaging to the merchant site, see the Pay Later messaging topic.

Required fields

The following table shows the required and optional fields for Klarna transactions in the Create APM one-time-use token request.

FieldRequired?Description
data.amountYesThe transaction amount. This value must equal data.cart.items[n].quantity multipled by the data.cart.items[n].price.
data.cart.items[n].itemYesItem number or code.
data.cart.items[n].descriptionYesA description of the item.
data.cart.items[n].quantityYesThe quantity sold.
data.cart.items[n].priceYesThe price per item.
data.cart.items[n].typeYesThe transaction type.
data.currencyYesThe three-character ISO currency code for the transaction.
For Klarna (with Klarna Payments) (klarnaPayments), supported currencies are AUD, CAD, CHF, DKK, EUR, GBP, NOK, NZD, SEK, and USD.
For Klarna through Checkout.com (klarnaCheckout), supported currencies are AUD, CHF, DKK, EUR, GBP, NOK, SEK, and USD.
data.customer.orderNumberYesThe order number.
data.customer.firstNameYesThe customer's first name, as it is set for the payment method.
data.customer.lastNameYesThe customer's last name, as it is set for the payment method.
data.customer.emailYesThe customer's email address.
data.customer.billToCountryYesThe two-character (Alpha-2) ISO country code .
Supported countries are AU, AT, CA, DK, FI, DE, GB, NL, NZ, NO, SE, CH, and US.
data.customer.billToAddressOneConditionalThe street address for the customer.
Required for klarnaPayments.
Optional for klarnaCheckout.
data.customer.billToCityConditionalThe city for the address record.
Required for klarnaPayments.
Optional for klarnaCheckout.
data.customer.billToStateConditionalThe state or province on file with the payment provider. (If in the US, this must be the two-character state abbreviation).
Required for klarnaPayments.
Optional for klarnaCheckout.
data.customer.billToPostalConditionalThe postal code on file.
Required for klarnaPayments.
Optional for klarnaCheckout.
data.customer.billToPhoneConditionalThe billing phone number.
Required for klarnaPayments.
Optional for klarnaCheckout.
data.customer.billToAddressTwoNoAdditional street address information, if required.
data.customer.shipToAddressOneNoThe shipping address, if different from the billing address.
data.customer.shipToAddressTwoNoAdditional shipping address information, if required.
data.customer.shipToCityNoThe shipping city.
data.customer.shipToStateNoThe shipping state or province. (If in the US, this must be the two-character state abbreviation).
data.customer.shipToPostalNoThe shipping postal code.
data.customer.shipToCountryNoThe two-character (Alpha-2) ISO shipping country code.
data.customer.shipToPhoneNoThe shipping phone number.
data.customerRefNoCustomer identifier. You can use this field to pass a customer ID to the APM or to manage user subscriptions.
data.descriptionNoA description of the transaction.
data.descriptorNoInclude this parameter to dynamically change the descriptor on the customer's statement.
data.paymentMethodNoThe identifier for the alternative payment method. Use this parameter when you want to only return the Klarna iframe button URL (rather than data for all payment methods associated with the account).

The value to use is klarnaPayments or klarnaCheckout, depending on your integration.
data.totalTaxAmountNoTotal tax amount.
customerRedirectUrlNoThe URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment. This URL must use the HTTPS protocol. For more information about how this changes the process flow, see Response handling below.
isAuthOnlyNoSet to true to run an auth only transaction.
processingOptions.merchantIdNoThe Nexio merchant ID (MID).
processingOptions.paymentOptionTagNoA custom value used to route transactions to a specific gateway or merchant account.
uiOptions.displaySubmitButtonNoSet to true to include a submit button in the iframe.
uiOptions.cssNoThe URL where your custom CSS file is hosted.

Example requests

The following are example one-time-use token requests for Klarna for the iframe integration methods:

Example Request for Klarna (with Klarna Payments)
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "billToCountry": "US"
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToCity": "Scranton",
      "billToState": "PA"
      "billToPostal": "18503",
      "billToPhone": "1555555555"
    },
    "cart": {
      "items": [
        {
          "item": "E200",
          "description": "Platinum set",
          "quantity": 2,
          "price": 2,
          "type": 10
        }
      ]
    },
    "paymentMethod": "klarnaPayments"
  }
}'
Example Request for Klarna through Checkout.com
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "billToCountry": "US"
    },
    "cart": {
      "items": [
        {
          "item": "E200",
          "description": "Platinum set",
          "quantity": 2,
          "price": 2,
          "type": 10
        }
      ]
    },
    "paymentMethod": "klarnaCheckout"
  }
}'

A successful request returns a response similar to the following:
Example 200 Response with several payment methods
{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "54a0106y-7750-45b1-961e-29ad95763a23",
  "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
  "redirectUrls": [
    {
      "paymentMethod": "klarnaPayments",
      "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"
    },
    {
      "paymentMethod": "klarnaCheckout",
      "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaCheckout"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "klarnaCheckout",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaCheckout"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
    }
  ],
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
}

For the multi iframe integration method: You use the expressIFrameUrl value in the steps for the transaction.

For the individual iframe option: You use the buttonIFrameUrls.url of the appropriate Klarna APM for the transaction.

Transaction types and integration methods

Regardless of the integration method workflow you implement, consumers are redirected to Klarna to complete their transactions.

Nexio supports the following transaction types for Klarna:

Testing data

For testing data, see Klarna’s Testing Environment page.

Response handling

In the one-time-use token request, Klarna gets returned in the paymentMethod parameter as klarnaPayments or klarnaCheckout.

Nexio responds with transaction results in one of the following ways, depending on your integration workflow:

  • Event messages: This applies to integrations that do not pass a customerRedirectUrl in the request.
  • Response fields in the URL: This applies to integrations that do provide a customerRedirectUrl in the request.

In addition to one of the above, if your merchant account is configured to receive webhooks, Nexio provides responses to the webhook URLs that have been registered. For further explanation of the webhook event types, see the webhook Event types table.

For Klarna, these are the possible webhook event types:

  • TRANSACTION_AUTHORIZED
  • TRANSACTION_CAPTURED
  • TRANSACTION_REFUNDED
  • TRANSACTION_SETTLED

For information about how to run each of the integration workflows, see Transaction types and integration methods above.

Status workflows

The status of a successful transaction with Klarna varies, depending on the options you choose.

SaleWhen isAuthOnly is false, successful sale transactions have the following statuses:
  • pending*
  • settled
Auth onlyWhen isAuthOnly is true, successful sale transactions have the following statuses:
  • authOnlyPending
  • authOnly
CaptureSuccessful capture transactions have the following status:
  • settled
RefundSuccessful refund transactions have the following status:
  • settled

*Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the table).

Next steps

Now, you are ready to get started with running transactions:

If you have any additional questions or feedback, see Contact us.


Did this page help you?