HelpRegisterLogin

Klarna Payments via API

🟦

This document aims to provide guidance on how to integrate Billie's B2B payment methods via your existing Klarna Payments (KP) integration. Please reference the publicly available documentation for overall KP integration, if needed.


Introduction

Once Billie via Klarna is integrated, customers can select Billie's payment methods at the checkout. Klarna handles business customer identification by signaling the customer type: "organization" during session creation. Billie's integration uses the same calls as the existing KP integration but requires a few changes to the fields to ensure a successful integration.

When integrated correctly, the authorize call (Step 2) will open a modal widget with Billie, which will either authorize the transaction right away, decline it, or allow the buyer to add more information in order for Billie to correctly identify the B2B buyer. The confirm order call creates the order with Billie and closes the order creation workflow. Orders then can be handled through the Klarna order management API, similar to the existing Klarna integration.

🟨

Please note, that merchants with “allow partial address” flow in Klarna Payments are currently NOT supported.


Step 1: Create a session (B2B)

  1. You can create a Klarna Payments session by the merchant server side through your API. This step must be done before the Klarna widget is loaded.
  2. To start a B2B session and enable Billie’s B2B payment methods you must include customer.type in the create session call.

Below you find the minimum required data to start a B2B session: 

{

	"customer": {
		...
     "type": “organization”
		... 
  }
 ...,

}

🟥

Important: Due to GDPR restrictions, the merchant cannot share personal data with Klarna/Billie before the buyer chooses Klarna/Billie as a payment method. Personal data is anything that can be used to identify an individual. It is recommended that you don't send over any buyer data during the create session call and keep the information sent during this step to a minimum.

Additional information on how to create a Klarna Payments Session can be found here.


Step 2: Authorize the order (B2B)

Once Billie has authorized an order, it can’t be changed. The final confirmation of the order and the authorized response sent by Billie must have identical information (meaning: company name, address, order amount, tax amount, line items etc. must match). The data in the authorize response is the order approved by Billie’s identification, risk, and fraud checks and therefore can’t be changed.

If the checkout allows the buyer to change the order after the authorization call, the order will be declined. We recommend sending the authorization call at the final step of the check out (e.g. Buy Now) to avoid a declined order.

  1. To successfully create a B2B order:
    a. Billing_address - must contain required fields specified below
    b. Consumer object - must contain required fields specified below

  2. If not included at session creation, merchants must update the session with required data before authorizing the purchase, otherwise, the customer won't be able to complete the order & the merchant will receive an error message.

🟦

If it is necessary to allow buyers to change their order after the authorization, it is important to open a new session and place a new order. Orders that are in an authorized state and don’t receive a confirmation call will be canceled by Billie after 4 hours.


Required fields for "billing_address" and "customer" object

FieldsDependencies
"billing_address": {
country, city, email, given name, family_name, organization_name, postal_code, street address }

"customer": {
type }		Mandatory
(if not included in the authorize call, merchants will receive an error message from Klarna )
"billing_address": {
email, postal code }

"customer": {
organization_entity_type }		Required by Billie
(if not included in the authorize call, Billie will trigger a modal in checkout asking customer to provide missing data points.)
"billing_address": {
organization_name}

"customer": {
organization_entity_type, type, vat_id }		Fields specific for B2B
(if not included in the authorize call, customers can not be identified as business buyers)
"billing_address": {
email, postal code }

"customer": {
type }		Required by Klarna, but validated by Billie
(if provided data does not match Billie's criterias, Billie modal will be triggered in checkout asking customer to provide required format.)

Example of "billing_address" and "customer" object

{
	...,
  "billing_address": {
	 "country": “DE”
     "city": “Berlin”
     "email": “[email protected]”
 	 "given_name": “Tony”
	 "family_name": “Stark”
	 "organization_name": “Billie GmbH”
	 "postal_code": “10115”
 	 "street_address": “Chausseestraße 117”
  }
   "customer": {
    ...
      "organization_entity_type": “limited_company” //Available types
      "organization_registration_id": “”
      "type": “organization”
      "vat_id": “”
    ...
  }
  ...,
}

Find all available organization_entity_types here (in the customer object). Additional information on purchase authorization can be found here.


Order lines

For merchants that wish to offer Billie’s B2B payment methods, certain order line information is mandatory for ALL of the below operations, regardless of its B2B/B2C order:

  • order creation
  • updates
  • captures
  • refund
{
	...,
  “order_tax_amount”: 400 // Not null
  "order_lines": [
		 {
     	...
       "name": “Battery Power Pack” //Not null, not blank
       "quantity": 2 //Not null, >0
       "tax_rate": 2500 //Not null
       "total_amount": 2000 //Not null
       "total_tax_amount": 400 //Not null
       "unit_price": 1000 //Not null
      ...
    }
  ]
  ...,
}

🟥

If the order lines do not comply with required data, the operation will fail, and merchants will get an error.


Example of a complete B2B session

{
  "purchase_country": "DE",
  "purchase_currency": "EUR",
  "locale": "de-DE",
  "order_amount": 100,
  "order_tax_amount": 0,
  "order_lines": [
  	{
   	 "type": "physical",
   	 "reference": "19402",
     "name": "Battery Power Pack",
     "quantity": 1,
     "unit_price": 100,
     "tax_rate": 0,
     "total_amount": 100,
     "total_discount_amount": 0,
     "total_tax_amount": 0,
     "image_url": "https://www.exampleobjects.com/logo.png",
     "product_url": "https://www.estore.com/products/f2a8d7e34"
     }
    ],
    "billing_address": {
      "organization_name": "Billie GmbH",
      "street_address": "Charlottenstr 4",
      "postal_code": "10969",
      "city": "Berlin",
      "phone": "+491522530345",
      "country": "DE",
      "given_name": "John",
      "family_name": "Doe",
      "email": "[email protected]"
     },
     "customer": {
      "type": "organization",
      "vat_id": "DE310295470",
      "organization_entity_type": "LIMITED_COMPANY",
      "organization_registration_id": "DE310295470"
     }
 }

Step 3: Confirm the order (B2B)

The confirm order call needs to have the exact same information that Billie/Klarna sent over in the authorize response. It is recommended to send the confirm order call right after you received the authorize response from Billie. The reason for this is explained within “Step 2: Authorize the order”.

🟦

Additional information on the authorize response

Billie tries to identify the buying company by the billing and delivery address and queries different databases with official company data. If both addresses can’t be found, the Billie modal widget pops up and asks the buyer for their registered company address. After a successful identification and authorization (still depending on risk scoring), Billie will send the address back to Klarna as the billing address for the purchase.

For the connecting PSP / platform / merchant, this address is available via the Klarna order management API and will also be shown as the billing address for this purchase in the Klarna merchant portal.