Skip to main content

Create a checkout session

The chekout API is a headless service for creating checkouts and payments. Beeing headless you have to provide your own user interface for your customers to use.

The checkout API is described in detail here.

Checkout session​

The first step is to create a checkout session. A checkout session holds the required information about who is paying and what they are paying for. Once the session is created you will get a response with a unique session id and a list of available payment products to choose from.

Payment​

Once a session is created you can create a payment for the session. The response will contain a list of redirects you need to send the user to.

info

As we currently only support Vipps and creditcard payments through our partner WorldLine the redirect will be to their payment page.

Callbacks​

When creating a session you must provide a set of URLs. The accept and cancel URLs are used for client side redirects, and must not be used as proof of payment. We will send relevant events to the callback URL.

info

Currently we only send the payment-authorized event. This event is sent when the payment is authorized, and contains the payment id and the checkout session id.

All events are signed so you can verify the content. The signature is found in the Authorization header of the request and follows this format: <Signing algorithm> Signature=<signature>. For now we use HMAC-SHA256 for signing, but this could change in the future.

Authorization: HMAC-SHA256 Signature=be0009af056e7bfc48b5e866fc5923679e87d5d4c64296a9f6dfce92772b26d9

{
  "type": "payment-authorized",
  "payload": {
    "amount": 2000,
    "paymentId": "e7dbc6b9fc2542c69eb53f9e9b978294",
    "sessionId": "4e0d7dd3c12441fba02981f60732a13f"
  }
}

To verify the payload you need to hash the payload with with the given algorithm and you secret key, provided alongside your merchant id and API key. And then compare the result with the signature.

// NOTE: You must ensure all whitespace is removed from the payload before hashing
var hash = hmacsha256(request.payload, secret_key);

if (hash == signature) // everything is good
else // someting is fishy

If, for some reason, we don't receive a 200 OK response to the callback. We will retry the request. We use a retry algorithm with exponential back-off, minimizing the risk of getting stopped by transient failures in your system. If we still get an error after 24 hours we will stop.

Authentication​

The checkout API is available for merchants only.