Reserve action

Reserve Request

The reserve action is the first step to process the payment of an order with Klarna. It will return a redirect URL to forward the consumer. It is important to handle the push sent by Buckaroo of the reservation that contains the Klarna order reference ID. This will require handling the follow-up actions.

Minimal Reserve Request

{
    "Currency": "EUR",
    "Invoice": "Ref.1 OrderID",
    "ClientIP": {
        "Type": 0,
        "Address": "0.0.0.0"
    },
    "Services": {
        "ServiceList": [
            {
                "Name": "klarnakp",
                "Action": "Reserve",
                "Parameters": [
                    {
                        "Name": "locale",
                        "Value": "de-DE"
                    },
                    {
                        "Name": "OperatingCountry",
                        "Value": "DE"
                    },
                    {
                        "Name": "ArticleTitle",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "Blue Toy Car"
                    },
                    {
                        "Name": "ArticleNumber",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "12345"
                    },
                    {
                        "Name": "ArticleType",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "General"
                    },
                    {
                        "Name": "ArticleQuantity",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "2"
                    },
                    {
                        "Name": "ArticlePrice",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "12.34"
                    }
                ]
            }
        ]
    }
}

 

Full Reserve Request

{
    "Currency": "EUR",
    "Invoice": "Ref.1 OrderID",
    "PushURL": "https://merchantURL.domain",
    "ClientIP": {
        "Type": 0,
        "Address": "0.0.0.0"
    },
    "Services": {
        "ServiceList": [
            {
                "Name": "klarnakp",
                "Action": "Reserve",
                "Parameters": [
                    {
                        "Name": "locale",
                        "Value": "de-DE"
                    },
                    {
                        "Name": "ArticleTitle",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "Blue Toy Car"
                    },
                    {
                        "Name": "ArticleNumber",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "12345"
                    },
                    {
                        "Name": "ArticleType",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "General"
                    },
                    {
                        "Name": "ArticleQuantity",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "2"
                    },
                    {
                        "Name": "ArticlePrice",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "12.34"
                    },
                    {
                        "Name": "ArticleVat",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "21"
                    },
                    {
                        "Name": "ArticleImageUrl",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "https://apod.nasa.gov/apod/image/2210/ngc4631_sherick.jpg"
                    },
                    {
                        "Name": "ArticleProductUrl",
                        "GroupType": "Article",
                        "GroupID": "1",
                        "Value": "https://apod.nasa.gov/apod/astropix.html"
                    },
                    {
                        "Name": "ArticleType",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "Discount"
                    },
                    {
                        "Name": "ArticleTitle",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "Discount on product"
                    },
                    {
                        "Name": "ArticleNumber",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "1234567"
                    },
                    {
                        "Name": "ArticleQuantity",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "1"
                    },
                    {
                        "Name": "ArticlePrice",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "-2.50"
                    },
                    {
                        "Name": "ArticleVat",
                        "GroupType": "Article",
                        "GroupID": "2",
                        "Value": "0"
                    },
                    {
                        "Name": "BillingFirstName",
                        "Value": "Testperson-de"
                    },
                    {
                        "Name": "BillingLastName",
                        "Value": "Approved"
                    },
                    {
                        "Name": "BillingStreet",
                        "Value": "Neue SchΓΆnhauser Str. 2 XII"
                    },
                    {
                        "Name": "BillingStreet2",
                        "Value": "Bill ErgΓ€nzungen"
                    },
                    {
                        "Name": "BillingPostalCode",
                        "Value": "10178"
                    },
                    {
                        "Name": "BillingCity",
                        "Value": "Berlin"
                    },
                    {
                        "Name": "BillingCountry",
                        "Value": "DE"
                    },
                    {
                        "Name": "BillingCellPhoneNumber",
                        "Value": "01761528435"
                    },
                    {
                        "Name": "BillingEmail",
                        "Value": "[email protected]"
                    },
                    {
                        "Name": "ShippingFirstName",
                        "Value": "Testperson-de"
                    },
                    {
                        "Name": "ShippingLastName",
                        "Value": "Approved"
                    },
                    {
                        "Name": "ShippingStreet",
                        "Value": "Neue SchΓΆnhauser Str. 3 IIV"
                    },
                    {
                        "Name": "ShippingStreet2",
                        "Value": "Shipp ErgΓ€nzungen"
                    },
                    {
                        "Name": "ShippingPostalCode",
                        "Value": "10178"
                    },
                    {
                        "Name": "ShippingCity",
                        "Value": "Berlin"
                    },
                    {
                        "Name": "ShippingCountry",
                        "Value": "DE"
                    },
                    {
                        "Name": "ShippingPhoneNumber",
                        "Value": "01761428434"
                    },
                    {
                        "Name": "ShippingEmail",
                        "Value": "[email protected]"
                    },
                    {
                        "Name": "OperatingCountry",
                        "Value": "DE"
                    },
                    {
                        "Name": "Pno",
                        "Value": "10071970"
                    },
                    {
                        "Name": "ShippingSameAsBilling",
                        "Value": "false"
                    },
                    {
                        "Name": "ContentType",
                        "GroupType": "Attachment",
                        "Value": "application/vnd.klarna.internal.emd-v2+json"
                    },
                    {
                        "Name": "Body",
                        "GroupType": "Attachment",
                        "Value": "{\"ExtraMerchantData\":\"Value\"}"
                    }
                ]
            }
        ]
    }
}

Request Parameters

ParameterTypeOCMDescription
localestringOAllowed ValuesΒ nl-NL / en-NL / nl-BE / fr-BE / be-BE / en-BE / de-DE / en-DE / de-AT / en-AT / de-CH / fr-CH / it-CH / en-CH / sv-SE / en-SE / nb-NO / en-NO / da-DK / en-DK / fi-FI / sv-FI / en-FI / en-GB / en-IE / fr-FR / en-FR / it-IT / en-IT / es-ES / en-ES / pt-PT / en-PT / pl-PL / en-PL
OperatingCountrystringMAllowed valuesΒ NL / BE / DE / AT / CH / DK / SE / NO / GB / FI / PL / IE / FR / IT / ES / PT
ArticleTitlestringMName of article
ArticleNumberstringOUnique product number
ArticleTypestringOAllowed values:Β physicalΒ / digital / shipping_fee / surcharge / discount / gift_card / store_credit
ArticlePricedecimalMPrice Including VAT
ArticleQuantityintegerMNumber of articles
ArticleVatdecimalOVAT percentage
ArticleImageUrlstringOUrl of Product image
ArticleProductUrlstringOUrl of PDP
BillingFirstNamestringOCustomer first name
BillingLastNamestringOCustomer last name
BillingStreetstringOCustomer 1st line address
BillingStreet2stringOCustomer 2nd line address
BillingPostalCodestringOCustomer postal code
BillingCellPhoneNumberstringOCustomer phone number
BillingCitystringOCustomer city
BillingCountrystringOCustomer Country
BillingEmailstringOCustomer email address
PnostringOCustomer birthdate format: DDMMYYYY or Customer PNO
ShippingSameAsBillingbooleanOCustomer address and shipping address is the same TRUE / FALSE
ShippingCareOfstringOPerson/company receiving the shipment on behalf of the shipping recipient
ShippingFirstNamestringODelivery address first name.
ShippingLastNameStringODelivery address last name.
ShippingStreetstringODelivery address 1st address line
ShippingStreet2stringODelivery address 2nd address line
ShippingPostalCodestringODelivery address postal code
ShippingCitystringODelivery address city
ShippingCountrystringODelivery address country code. It should be the same as Billing country.
ShippingEmailstringODelivery address email address
ShippingCellPhoneNumberstringODelivery address phone number
ShippingCompanystringODelivery address company name
ContentTypestringOContent type agreed with Klarna ex. "application/vnd.klarna.internal.emd-v2+json"
BodystringOAdditional Parameters based on agreed format with Klarna

Reserve Response

A successful request will return a requiredAction redirect URL to forward the consumer to the Hosted page of Klarna.

General Reserve Response

{
    "Key": "49EF793FC7AC404EABC4F57A32F5F08D",
    "Status": {
        "Code": {
            "Code": 791,
            "Description": "Pending processing"
        },
        "SubCode": {
            "Code": "S002",
            "Description": "An additional action is required: Redirect to KlarnaKp"
        },
        "DateTime": "2019-12-03T14:48:27"
    },
    "RequiredAction": {
        "RedirectURL": "https://checkout.buckaroo.nl/html/redirect.ashx?r=3D349C783491413EBAF06660932EF0BF",
        "RequestedInformation": null,
        "Name": "Redirect",
        "TypeDeprecated": 0
    },
    "Services": null,
    "CustomParameters": null,
    "AdditionalParameters": null,
    "RequestErrors": null,
    "ServiceCode": "KlarnaKp",
    "IsTest": true,
    "ConsumerMessage": null
}

Reserve Push

{
  "DataRequest": {
    "Key": "34C088DBD9244F27B3C62C21C7D6D6C8",
    "Invoice": "Ref.1 OrderID Reserve",
    "ServiceCode": "KlarnaKp",
    "ActionCode": "Reserve",
    "Status": {
      "Code": {
        "Code": 190,
        "Description": "The request was successful."
      },
      "SubCode": null,
      "DateTime": "2023-03-27T07:28:26"
    },
    "IsTest": true,
    "Order": null,
    "Currency": "EUR",
    "AmountDebit": 0,
    "Services": [
      {
        "Name": "KlarnaKp",
        "Action": null,
        "Parameters": [
          {
            "Name": "ReservationNumber",
            "Value": "11ab9249-95c7-41e8-86fa-0a60030d9eef"
          }
        ],
        "VersionAsProperty": 1
      }
    ],
    "CustomParameters": null,
    "AdditionalParameters": null,
    "MutationType": 0,
    "IssuingCountry": null,
    "StartRecurrent": false,
    "Recurring": false,
    "CustomerName": null,
    "PayerHash": null,
    "PaymentKey": null
  }
}

Push Parameters

ParameterTypeOCMDescription
ServiceCodestringMKlarna service label is KlarnaKp
CodestringMContains the status of the transaction
IsTestbooleanMIf there are actual funds processed
ReservationNumberstringOContains ReservationNumber of Klarna for future actions