Klarna Shipping Service Callback API (1.3.0)

Obtain a bearer authorization token. Aggregator specific merchant identifier and API key will be provided in the payload body, it's recommended that a merchant unique token is returned using a signed Json Web Token (JWT).

The token will be used for subsequent request for this merchant identifier using HTTP bearer authorization in the Authorization HTTP header with the format Authorization: Bearer <token>.

More about how this works:

When a Merchant has an agreement with the TMS, the TMS provides the Merchant with an Identifier and a Key. The Merchant then configures Klarna to use the TMS with the provided Identifier and Key. So let's say the TMS gives the Merchant these credentials:

Identifier: "sweMerch123"
Key: "smOOOth"

As KSS prepares its authorization request to the TMS, it generates a random Nonce. KSS appends the Key to the Nonce, and then runs the Sha256 algorithm on that value to create a Digest.

To further the example, let's say KSS provided a Nonce of 'lRFUpqW7Xd':

Nonce: "lRFUpqW7Xd"
Nonce+Key: "lRFUpqW7XdsmOOOth"
Digest: "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B"

Then KSS sends the authorization request with the Identifier, Nonce, and Digest.

The TMS authenticates the credentials by looking up their local Key for the Identifier, appending the Key to the Nonce provided by KSS, running the Sha256 algorithm on that value to create their own Digest, and then comparing that Digest to the Digest provided by KSS. If the Digests are identical, the TMS accepts the request and returns a bearer token.

Gets shipping options for the given customer data, address and order lines.

It's always important to display proper expected delivery date and time, to create a smoooth customer experience. Below you can find a table with examples of how customer will see delivery date and time that is provided in the delivery_time field of shipping option. Representation can vary in case provided date points to the same date or a period, in case the date is today, tomorrow or any date in the future. Dates in the past are ignored.

This operation reserves the user selected shipping option so that the merchant is able to query and find the data and create a shipment of it.

The shipment reservation should be unique per session_id provided in the request body.

This call happens when the user clicks buy, but before the purchase has gone through. A HTTP 201 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been saved successfully.

A HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.

If the purchase is successfully completed, KSS will call POST /shipment/{id}/confirm to confirm the reservation. See the /confirm call.

KSS will occasionally update a created shipment. This can happen because of a failure to finalize the order or for other reasons, which will restart the shipping selection process. See the PUT /shipment call. If the TMS is not able to return a shipment_id in the response, identifying the reserved shipment, then KSS is forced to invoke POST on succeeding updates instead of PUT.

Get carrier product codes for the shipment, shipment status and optional carrier tracking data.

This operation updates the previously created shipment reservation (POST -> /shipment).

The shipment reservation should be unique per session_id provided in the request body.

This call happens when the user clicks buy, but before the purchase has gone through. This request takes place if relevant data were updated or if the user was denied a preceding purchase after /shipment call took place. The user then has the potential to change his previous selections and retry the purchase.

A HTTP 200 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been updated successfully.

A HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.

This operation confirms the previously created shipment reservation (POST -> /shipment).

After the last POST /shipment or PUT /shipment/{id} call, one of two things can happen:

• If the purchase goes through, this endpoint is called. The call is guaranteed to happen within an hour of the last call to POST /shipment or PUT /shipment/{id}. In most cases, the call to this endpoint will come within seconds.
• If the purchase does not go through, this endpoint is never called. If an hour has passed since the last call to POST /shipment or PUT /shipment/{id}, it is safe to remove the reservation of the shipment.

A HTTP 401 error code will trigger an auth call. Any other HTTP response will be ignored as this is a best effort call without any possibility for consumer interaction.