Initialize a Checkout Session

To initialize a Checkout session, a POST request to the checkout endpoint is performed. This will return a public token that is used to render the Checkout iframe and a private id that is used to retrieve information about the Checkout session at a later step.

/*
POST /checkout HTTP/1.1
Host: checkout-api-uat.collector.se (Please note! Different hostname in production)
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
*/
{
"storeId": 123,
"countryCode": "SE",
"reference": "123456789",
"redirectPageUri": "https://example.com/purchase-completed-confirmation-page",
"merchantTermsUri": "https://example.com/merchant-purchase-terms",
"notificationUri": "https://example.com/my-notification-endpoint",
"validationUri": "https://example.com/my-validation-endpoint",
"profileName": "MyExampleProfile",
"settlementReference": "shop1",
"cart": {
"items": [
{
"id": "10001",
"description": "A product description",
"unitPrice": 95.0,
"quantity": 1,
"vat": 25.0,
"requiresElectronicId": true,
"sku": "a unique alphanumeric code for article identification"
}
]
},
"fees": {
"shipping": {
"id": "shipping001",
"description": "Shipping cost (incl. VAT)",
"unitPrice": 59.0,
"vat": 25.0
}
},
"customer": {
"email": "test@collectorbank.se",
"mobilePhoneNumber": "+46701234567",
"nationalIdentificationNumber": "19520101-1234"
},
"metadata": {
"administrator": "John Doe",
"someOtherData": [1, { "myObj": { "key": 1 } }]
}
}

Request

Request headers

HeaderRequiredExplanation
AuthorizationYesInstructions on how to generate the authorization header value can be found here. Note that the authorization header is generated with the access credentials (usename and shared access key) received from Collector Merchant Services.

Request Body Properties

PropertyRequiredExplanation
storeIdNoReceived from Collector Merchant Services. The store ID is only required in the request when integrating multiple stores with Collector Checkout.
countryCodeYesThe country code to use. SE, NO, FI, DK and DE is supported.
referenceNoA reference to the order, i.e. order ID or similar. Note that the reference provided here will be shown to the customer on the invoice or receipt for the purchase. Max 50 chars.
settlementReferenceNo *Set this if you would like to group your settlement reports based on this value. Can for example be used when you have several shops connected to one storeId and want purchases to be grouped by individual shops. Max 50 chars. * To use this feature you must contact Merchant Services to setup Settlement Settings on this specific Store ID
redirectPageUriNo *If set, the browser will redirect to this page once the purchase has been completed. Used to display a thank-you-page for the end user. Hereafter referred to as the purchase confirmation page. * Required if the Store is an InStore type.
merchantTermsUriYesThe page to which the Checkout will include a link for customers that wish to view the merchant terms for purchase.
notificationUriYesThe endpoint to be called whenever an event has occurred in the Collector Checkout that might be of interest. For example, this callback is typically used to create an order in the merchant's system once a purchase has been completed. Use HTTPS here for security reasons.
validationUriNoSpecify this uri when you want us to make an extra backend call to validate the articles during purchase. Use HTTPS here for security reasons.
profileNameNoA name that referes to a specific settings profile. The profiles are setup by Merchant Services, please contact them for more information merchant@collectorbank.se
cartYesThe initial Cart object with items to purchase (details below)
feesNoShipping fee (details below)
customerNoCustomer information for identification (details below)

Cart object

The Cart object contains an array of items with the following properties. Please note that at least one article has to be included in order to initialize a checkout session.

PropertyRequiredExplanation
idYesThe article id or equivalent. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
descriptionYesDescriptions longer than 50 characters will be truncated. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPriceYesThe unit price of the article including VAT. Positive and negative values allowed. Max 2 decimals, i.e. 100.00
quantityYesQuantity of the article. Allowed values are 1 to 99999999.
vatYesThe VAT of the article in percent. Allowed values are 0 to 100. Max 2 decimals, i.e. 25.00
requiresElectronicIdNoWhen set to true it indicates that a product needs strong identification and the customer will need to strongly identify themselves at the point of purchase using Mobilt BankID. An example would be selling tickets that are delivered electronically. At the moment it is only applicable to B2C on the Swedish market.
skuNoA stock Keeping Unit is a unique alphanumeric code that is used to identify product types and variations. Maximum allowed characters are 1024.
Please note

The combination of id and description is the unique identifier of an article. Multiple articles with the same unique combination will be merged (quantities are summed) as long as all other properties (except quantity) are equal. Note that the uniqueness also spans to fees.

Fees object (optional)

The Fees object allows you to set a shipping fee. The fee will be shown last on the receipt after all the cart items and also on the purchase confirmation page for a completed purchase. This object is optional and can be set after initialization of the checkout through the Update fees endpoint.

PropertyRequiredExplanation
idYesAn id of the fee item. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
descriptionYesDescriptions longer than 50 characters will be truncated. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPriceYesThe unit price of the fee including VAT. Allowed values are 0 to 999999.99. Max 2 decimals, i.e. 25.00
vatYesThe VAT of the fee in percent. Allowed values are 0 to 100. Max 2 decimals, i.e. 25.00

The combination of id and description of a fee must be unique within the cart and fees objects.

Customer object (optional)

The customer object allows you to optionally provide customer information you might have if the customer is logged in into your site. When we retrieve this information we try to identify the customer for a faster checkout experience. If we cannot identify the customer we prompt the user for further identification details. The response and status code of the Initialize Checkout Session call is not affected by success or failure to identify the customer.

Examples

  • If email and mobilePhoneNumber are provided and the combination is matched for a previously known customer, the user will be logged in and ready for purchase.
  • If email and mobilePhoneNumber are provided but the combination does not match a previously known customer, we will prompt the user for further identification details.
  • If email and mobilePhoneNumber are provided together with nationalIdentificationNumber we will try to identify the customer using these values by doing a lookup in an address registry.
PropertyRequiredExplanation
emailYesThe customer's email address.
mobilePhoneNumberYesThe customer's mobile phone.
nationalIdentificationNumberNoThe customer's national identification number

Metadata object

The metadata object allows you to optionally provide custom metadata information in a key/value format. Metadata is not processed by Collector but will be returned when retrieving information about the checkout. This means that the metadata object can be used as an opaque reference for things that needs to be remembered without saving state locally.

Each metadata key must be a string but the value can be any valid JSON type.

Response

PropertyExplanation
publicTokenThe publicToken is used to render the Checkout iframe. The public token has a limited lifetime of 168 hours (7 days).
privateIdA reference that can be used by you to acquire information about a Checkout session at any given time no matter if the purchase has been completed or not. The privateId property value cannot be used to render the Checkout iframe, but is instead used to acquire information such as delivery address, total amount for the purchase etc. from the Checkout API. For more details about how the value from the privateId property is used, refer to the section how to acquire information about an ongoing or completed Checkout. Note that the private ID never expires but some operations are no longer permitted after expiresAt.
expiresAtThe timestamp when this Checkout session will expire. After this timestamp the purchase cannot be completed, no updates to the cart can be performed and a new Checkout session must be initialized.
paymentUriA shortcut link to this Checkout session. Used when distributing a Pay Link to a customer. Only visible if the merchant has been setup to use Pay Link. Contact Merchant Services if you are interested in this.

Templating the uri values

The notificationUri and the validationUri properties can optionally be templated to contain the privateId and the public token anywhere in the URI using {checkout.id} and {checkout.publictoken}. Note that the variable names checkout.id and checkout.publictoken are case-sensitive.

For redirectPageUri, only the {checkout.publictoken} is valid for templating the uri.

Examples

redirectPageUriWill be transformed into
https://your-backend.com/checkout/{checkout.id}/something/happenedhttps://your-backend.com/checkout/1eec44b5-66d3-4058-a31f-3444229fb727/something/happened
https://your-backend.com/something/happened?reference={checkout.id}https://your-backend.com/something/happened?reference=1eec44b5-66d3-4058-a31f-3444229fb727
https://your-backend.com/something/happened?reference={checkout.publictoken}https://your-backend.com/something/happened?reference=public-SE-6d0ed138881fd548d8c7c81450d1c54483e257f4720e419d
https://your-backend.com/something/happened?id={checkout.id}&token={checkout.publictoken}https://your-backend.com/something/happened?id=1eec44b5-66d3-4058-a31f-3444229fb727&token=public-SE-6d0ed138881fd548d8c7c81450d1c54483e257f4720e419d