NAV undefined
undefined
Examples

Integrating with Collector Checkout

Collector Checkout is hosted within your site by placing a <script> tag in pages in your web shop where the Checkout should be shown. The script tag will load an iframe which will guide the customer through the purchase. Once the purchase has been completed, you will be notified through a web request to an API URI of your choosing. Details about the purchase may then be acquired from the Checkout REST API.

Completed purchases may be managed by interacting with the Collector E-Commerce Integration. This includes activating pending invoices, making returns etc. For additional documentation on how to manage completed purchases and connect with the Collector E-Commerce Integration, please contact Collector Merchant Services at:

merchant@collectorbank.se

+46 10 161 01 99

Prerequisites

First of all you will need access to our environments. Contact Collector Merchant Services to acquire the following access credentials:

Once you have the credentials follow these steps:

  1. Initialize a Checkout Session
  2. Render the Checkout iframe on your page
  3. Set up a callback notification endpoint to which the Collector Checkout will send notifications for events that occur in the Checkout
  4. Acquire information about a Checkout Session to obtain information about the customer, delivery address, delivery contact details and the purchase

Checkout Environment Endpoints

The hostname in the example requests throughout this documentation should be changed to the environment currently being used. For testing and staging purposes, Collector Merchant Services will setup an account in the UAT environment where you can test your implementation before moving to production.

The credentials (username, shared access key and store ID) will differ between the environments.

UAT/Testing endpoints

No real money will be involved in transactions.

Environment Checkout Environment Endpoint Description
FrontEnd https://checkout-uat.collector.se Front end endpoint. Used to render the checkout iframe.
Backend API https://checkout-api-uat.collector.se Backend API endpoint. Called from your backend to initialize and update checkout sessions, and to obtain information about checkout sessions and completed purchases.

Production endpoints

All purchases are real and real money will be involved in transactions.

Environment Checkout Environment Endpoint Description
FrontEnd https://checkout.collector.se Front end endpoint. Used to render the checkout iframe.
Backend API https://checkout-api.collector.se Backend API endpoint. Called from your backend to initialize and update checkout sessions, and to obtain information about checkout sessions and completed purchases.

The Checkout Flow - Overview

Getting started

1. Initialize a Checkout Session

Initialize Checkout request

POST /checkout HTTP/1.1
Host: checkout-api-uat.collector.se
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",
  "cart": {
    "items": [
      {
        "id": "10001",
        "description": "A product description",
        "unitPrice": 95.00,
        "quantity": 1,
        "vat": 25.00,
        "requiresElectronicId": true,
        "sku": "a unique alphanumeric code for article identification"
      }
    ]
  },
  "fees": {
    "shipping": {
      "id": "shipping001",
      "description": "Shipping cost (incl. VAT)",
      "unitPrice": 59.00,
      "vat": 25.00
    }
  },
  "customer": {
      "email": "test@collectorbank.se",
      "mobilePhoneNumber": "+46701234567",
      "nationalIdentificationNumber": "19520101-1234"
  },
  "metadata":  {
    "administrator": "John Doe",
    "someOtherData": [ 1, { "myObj": { "key": 1 } } ]
  }
}

Initialize Checkout response

{
  "id": "91714012-6ae9-4780-a927-fe459bc95bf6",
  "data": {
    "privateId": "1eec44b5-66d3-4058-a31f-3444229fb727",
    "publicToken": "public-SE-7f1b3d2a2a73d348dfbd17d3965ff1458c249f84c695eac1",
    "expiresAt": "2017-12-07T07:16:49.8098107+00:00",
    "paymentUri": "https://checkout-uat.collector.se/p/npBc87EFB"
  },
  "error": null
}

Example of Initialize Checkout response where an invalid StoreId was provided

{
  "id": "1da39a61-d3e1-4da5-a1a0-7a315ea66d2f",
  "data": null,
  "error": {
    "code": 400,
    "message": "Bad or faulty request. Please examine the errors property for details.",
    "errors": [
      {
        "reason": "Store_Invalid",
        "message": "Invalid store id or country code."
      }
    ]
  }
}

The first step of integrating with Collector Checkout consists of acquiring a public Checkout token that is used to render the Checkout iframe. The public Checkout token is acquired as part of the response for a HTTP POST to the Checkout API sent from your backend. The HTTP POST request to acquire the public Checkout token should contain the following:

Request headers

Header Required Explanation
Authorization Yes Instructions 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

Property Required Explanation
storeId Yes Received from Collector Merchant Services. Store id is configured for either B2C or B2B.
countryCode Yes The country code to use. SE, NO, FI, DK and DE is supported.
reference No A 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.
redirectPageUri No * 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.
merchantTermsUri Yes The page to which the Checkout will include a link for customers that wish to view the merchant terms for purchase.
notificationUri Yes The 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.
validationUri No Specify this uri when you want us to make an extra backend call to validate the articles during purchase. Use HTTPS here for security reasons.
profileName No A name that referes to a specific settings profile. The profiles are setup by Merchant Services, please contact them for more information merchant@collectorbank.se
cart Yes The initial Cart object with items to purchase (details below)
fees No Shipping fee (details below)
customer No Customer information for identification (details below)
metadata No Metadata information associated with this checkout session (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.

Property Required Explanation
id Yes The article id or equivalent. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
description Yes Descriptions longer than 50 characters will be truncated. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPrice Yes The unit price of the article including VAT. Positive and negative values allowed. Max 2 decimals, i.e. 100.00
quantity Yes Quantity of the article. Allowed values are 1 to 99999999.
vat Yes The VAT of the article in percent. Allowed values are 0 to 100. Max 2 decimals, i.e. 25.00
requiresElectronicId No When 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/B2B on the Swedish market.
sku No A stock Keeping Unit is a unique alphanumeric code that is used to identify product types and variations. Maximum allowed characters are 1024.

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

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.

The shipping object contain the following properties:

Property Required Explanation
id Yes An id of the fee item. Max 50 characters. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
description Yes Descriptions longer than 50 characters will be truncated. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPrice Yes The unit price of the fee including VAT. Allowed values are 0 to 999999.99. Max 2 decimals, i.e. 25.00
vat Yes The 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

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.

Some examples

Property Required Explanation
email Yes The customer's email address.
mobilePhoneNumber Yes The customer's mobile phone.
nationalIdentificationNumber No The 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

Property Explanation
publicToken The publicToken is used to render the Checkout iframe. The public token has a limited lifetime of 168 hours (7 days).
privateId A 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.
expiresAt The 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.
paymentUri A 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.

  1.1 Templating the uri values

The notificationUri and the validationUri 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.

If this is done the following uri values:

https://your-backend.com/checkout/{checkout.id}/something/happened

https://your-backend.com/something/happened?reference={checkout.id}

https://your-backend.com/something/happened?reference={checkout.publictoken}

https://your-backend.com/something/happened?id={checkout.id}&token={checkout.publictoken}

... will result in the following HTTP GET calls being sent once something of potential interest occurs in the Checkout:

https://your-backend.com/checkout/1eec44b5-66d3-4058-a31f-3444229fb727/something/happened

https://your-backend.com/something/happened?reference=1eec44b5-66d3-4058-a31f-3444229fb727

https://your-backend.com/something/happened?reference=public-SE-6d0ed138881fd548d8c7c81450d1c54483e257f4720e419d

https://your-backend.com/something/happened?id=1eec44b5-66d3-4058-a31f-3444229fb727&token=public-SE-6d0ed138881fd548d8c7c81450d1c54483e257f4720e419d

2. Render the Checkout iframe

Place this script on the pages where you want the Checkout to appear

<script
  src="https://checkout-uat.collector.se/collector-checkout-loader.js"
  data-token="public-SE-7f1b3d2a2a73d348dfbd17d3965ff1458c249f84c695eac1"
></script>

To render the Collector Checkout, use a <script> element as the example to the right shows. The value provided in the data-token attribute corresponds to the public token received when initializing the Checkout session. When the script is executed, the Checkout iframe is dynamically fetched and rendered on the page. (Remember to use the correct endpoint in the src attribute, as specified in Checkout Environment Endpoints.)

It is required that you also include the Checkout iframe in your purchase confirmation page as the Checkout iframe will show important purchase details to the customer. To display the "thank you" page on another page, for example when redirecting the user to a custom thank you page, put an identical <script> element on this page as well. When the checkout is in the state of PurchaseCompleted it will show a thank you page instead of the normal checkout flow.

Please use the same public token for each customer session

You should store and re-use the same public token (and the corresponding private id) during the whole session for each customer. The public token should stay the same even if:

Some of the advantages with using the same token for a single purchase session:

The expiresAt property from the Initialize Checkout response will let you know when it is time to create a new Checkout session.

Script element attributes

Attribute                    Explanation
src https://checkout-uat.collector.se/collector-checkout-loader.js see FrontEnd endpoints in Checkout Environment Endpoints
data-token The publicToken acquired when Initializing a Checkout Session.
data-lang (optional) The display language. Currently supported combinations are: sv-SE, en-SE, nb-NO, fi-FI, sv-FI, da-DK and en-DE. Both sv-SE and en-SE are available for use with swedish partners. In the other cases, the country part must match the country code used when initializing the checkout session or it will be ignored. Setting this attribute is optional and will only be of interest when there is more than one language for any single country.
data-padding (optional) Set this to none in order to cancel out the left and right padding inside the iframe (by adjusting its margins and width).
data-container-id (optional) Set this to the id of an element on the page and the iframe will render inside this element instead of immediately above the script element of the loader script. Put the container element somewhere above the script element. This is to make sure the container element is loaded before trying to populate it with the iframe.
data-action-color (optional) Set this to a hexadecimal color code to change the background color of call to action buttons, formatted as the following example #582f87. Button text color will automatically be set to dark gray instead of white if not enough contrast according to WCAG 2.0 level AA for large text.
data-action-text-color (optional) Set this to override the automatic text color of call to action buttons. Valid values are black, white, #000000 and #ffffff. Other hexadecimal color values are also valid, but will be interpreted as either black or white (and instead of black, the actual text color will be dark gray).

Iframe element details

The loader script will create an <iframe> element directly above itself. This iframe will have its class attribute set to collector-checkout-iframe and both the id and the name attributes will bet set to collector-checkout-iframe- followed by the public token given by the data-token attribute of the <script> element.

The iframe will use 100% of the available width (inside its container element) and will have its own padding. Therefore it is recommended that you don't add any extra margin or padding to the sides of the iframe yourself (this is extra important for narrow device widths). If you still feel the need to you may set the attribute data-padding to none.

3. Setup a notification callback endpoint

Collector Checkout will send a HTTP(s) GET request to the notification URI that was provided in the initialize Checkout step for the following events:

1. Completed Purchase
A purchase has been successfully completed by the end customer.
When you acquire checkout information the state of the Checkout has transferred to PurchaseCompleted and the invoice status is one of the values described in data.purchase.result below.

2. Invoice Status update
An invoice has been approved or rejected by Collector's anti-fraud system (if that feature is configured on your account), or the Invoice required the end customer to digitally sign a credit agreement and this has been completed by the end customer. When you acquire checkout information the invoice status has transferred to one of the values described in data.purchase.result below. Please note that if the invoice was Cancelled before the notification callback arrived, the invoice is considered Cancelled regardless what the value of data.purchase.result is.

Idempotency and retries

Please note the Checkout will attempt to notify the provided notification URI multiple times with increasing backoff time until a HTTP status code 200 is received in the response.
Our retry mechanism is built in a way that we guarantee at-least-once-delivery and the notification URI endpoint must therefore support being called multiple times without side effects.

The notification callback is sent instantly and if the endpoint did not answer with a 200 OK status a retry will be made after:

If the notification endpoint did not answer with a 200 OK status after the last retry, we will handle this manually and contact you before retrying again.

4. Acquire information about a Checkout session

Get Merchants Checkout Information request

GET /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727 HTTP/1.1
Host: checkout-api-uat.collector.se
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

Get Merchant Checkout Information response for a private customer strongly identified with a national identification number

{
  "id": "9eec015f-4b97-44be-a711-d22f3af75069",
  "data": {
    "customerType": "PrivateCustomer",
    "customer": {
      "email": "test@collectortest.se",
      "mobilePhoneNumber": "+4670707071",
      "deliveryContactInformation": {
        "mobilePhoneNumber": "+46701111111"
      },
      "deliveryAddress": {
        "firstName": "Lars-Erik Rudolf",
        "lastName": "Viberg",
        "coAddress": null,
        "address": "Sommarstugevägen 2",
        "address2": null,
        "postalCode": "85353",
        "city": "Sundsvall",
        "country": "Sverige"
      },
      "billingAddress": {
        "firstName": "Lars-Erik Rudolf",
        "lastName": "Viberg",
        "coAddress": null,
        "address": "Lingonstigen 10",
        "address2": null,
        "postalCode": "85352",
        "city": "Sundsvall",
        "country": "Sverige"
      }
    },
    "businessCustomer": null,
    "countryCode": "SE",
    "status": "PurchaseCompleted",
    "paymentName": "Account",
    "reference": "123456789",
    "cart": null,
    "fees": null,
    "purchase": {
      "amountToPay": 279,
      "paymentName": "Account",
      "invoiceDeliveryMethod": "Paper",
      "purchaseIdentifier": "640173",
      "result": "Preliminary"
    },
    "order": {
      "totalAmount": 200,
      "items": [
        {
          "id": "1",
          "description": "Some product",
          "unitPrice": 200,
          "quantity": 1,
          "vat": 20,
          "sku": "Product SKU"
        },
        {
          "id": "998",
          "description": "Shipping cost (incl. VAT)",
          "unitPrice": 59,
          "quantity": 1,
          "vat": 25.0
        }
      ]
    },
    "hasSessionExpired": false,
    "metadata": {
      "administrator": "John Doe",
      "someOtherData": [ 1, { "myObj": { "key": 1 } } ]
    }
  },
  "error": null
}

Get Merchant Checkout Information response for a private customer identified without a national identification number. Note that the billing address is set to the same address as the delivery address in this case.

{
  "id": "9eec015f-4b97-44be-a711-d22f3af75069",
  "data": {
    "customerType": "PrivateCustomer",
    "customer": {
      "email": "test@collectortest.se",
      "mobilePhoneNumber": "+4670707071",
      "deliveryContactInformation": {
        "mobilePhoneNumber": "+46701111111"
      },
      "deliveryAddress": {
        "firstName": "Lars-Erik Rudolf",
        "lastName": "Viberg",
        "coAddress": null,
        "address": "Lingonstigen 10",
        "address2": null,
        "postalCode": "85352",
        "city": "Sundsvall",
        "country": "Sverige"
      },
      "billingAddress": {
        "firstName": "Lars-Erik Rudolf",
        "lastName": "Viberg",
        "coAddress": null,
        "address": "Lingonstigen 10",
        "address2": null,
        "postalCode": "85352",
        "city": "Sundsvall",
        "country": "Sverige"
      }
    },
    "businessCustomer": null,
    "countryCode": "SE",
    "status": "PurchaseCompleted",
    "paymentName": "Account",
    "reference": "123456789",
    "cart": null,
    "fees": null,
    "purchase": {
      "amountToPay": 279,
      "paymentName": "Account",
      "invoiceDeliveryMethod": "Paper",
      "purchaseIdentifier": "640173",
      "result": "Preliminary"
    },
    "order": {
      "totalAmount": 200,
      "items": [
        {
          "id": "1",
          "description": "Some product",
          "unitPrice": 200,
          "quantity": 1,
          "vat": 20,
          "sku": "Product SKU"
        },
        {
          "id": "998",
          "description": "Shipping cost (incl. VAT)",
          "unitPrice": 59,
          "quantity": 1,
          "vat": 25.0
        }
      ]
    },
    "hasSessionExpired": false,
    "metadata": {
      "administrator": "John Doe",
      "someOtherData": [ 1, { "myObj": { "key": 1 } } ]
    }
  },
  "error": null
}

Get Merchant Checkout Information response for a business customer

{
  "id": "80a0b38b-2f8b-47db-81a5-8b56baa4ad84",
  "data": {
    "customerType": "BusinessCustomer",
    "customer": null,
    "businessCustomer": {
      "invoiceTag": "Fakturamärkning: 5678",
      "companyName": "Bra Byggare AB",
      "organizationNumber": "620306-1400",
      "invoiceReference": "Reparation dusch Collector",
      "email": "bosse@brabyggare.se",
      "firstName": "Bosse",
      "lastName": "Byggare",
      "mobilePhoneNumber": "+46730481277",
      "invoiceAddress": {
        "companyName": "Bra Byggare AB",
        "coAddress": null,
        "address": "Storgatan 1",
        "address2": null,
        "postalCode": "50332",
        "city": "Borås",
        "country": "Sverige"
      },
      "deliveryAddress": {
        "companyName": "Collector AB",
        "coAddress": null,
        "address": "Östra Hamngatan 24",
        "address2": "att: Bosse Byggare",
        "postalCode": "41109",
        "city": "Göteborg",
        "country": "Sverige"
      }
    },
    "countryCode": "SE",
    "status": "PurchaseCompleted",
    "paymentName": "DirectInvoice",
    "reference": "1231",
    "cart": null,
    "fees": null,
    "purchase": {
      "amountToPay": 377,
      "paymentName": "DirectInvoice",
      "invoiceDeliveryMethod": "Email",
      "purchaseIdentifier": "33074878",
      "result": "Preliminary"
    },
    "order": {
      "totalAmount": 377,
      "items": [
        {
          "id": "scap001",
          "description": "Shower Cap",
          "unitPrice": 10,
          "quantity": 1,
          "vat": 25
        },
        {
          "id": "shipping001",
          "description": "Shipping fee (incl. vat)",
          "unitPrice": 59,
          "quantity": 1,
          "vat": 25
        },
        {
          "id": "dirfee001",
          "description": "Order administration fee (incl. vat)",
          "unitPrice": 299,
          "quantity": 1,
          "vat": 25
        }
      ]
    },
    "hasSessionExpired": false,
    "metadata": {
      "administrator": "John Doe",
      "someOtherData": [ 1, { "myObj": { "key": 1 } } ]
    }
  },
  "error": null
}

Example of Merchant Checkout Information response where an invalid StoreId was provided in the request URL

{
  "id": "0b18555c-3c84-4bfd-901a-f15c368ba3d9",
  "data": null,
  "error": {
    "code": 400,
    "message": "Bad or faulty request. Please examine the errors property for details.",
    "errors": [
      {
        "reason": "Store_Invalid",
        "message": "Invalid store id or country code."
      }
    ]
  }
}

The privateId property, also referred to as the private Checkout ID, is used to acquire information about an ongoing or completed Checkout. The information is acquired by issuing a HTTP GET request to the following URI:

https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}

... replacing storeId and privateIdin the URL with their respective values. The request can be used to acquire information about a Checkout session regardless if the purchase has been completed or not.

Request headers

Header Required Explanation
Authorization Yes Instructions 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.

Important properties in the response body

Some of the properties listed below may have their values set to null if they are not applicable in the current state for a Checkout. For example, the customer property is set to null if the customer has not been identified yet.

Property Explanation
data.countryCode The country code you specify in initialize Checkout request
data.status Contains the current status of the Checkout. Possible values include Initialized, CustomerIdentified, CommittedToPurchase, PurchaseCompleted. An explanation of the different statuses can be found further down in this section.
data.paymentName The name of the Payment option the customer has chosen when committed to purchase. For a payment name of a successful purchase use the data.purchase.paymentName property instead.
data.reference Equal to the reference field provided in the initialize Checkout request.
data.cart Contains all items for a purchase that has not yet been completed. Once the purchase is complete, all items are moved in under the data.order property and the data.cart is set to null.
data.fees Contains the fees, like shipping, when the the purchase is not yet completed. Once the purchase is complete, the fee items are moved last in the data.order.items property and the data.fees.shipping is set to null.
data.customerType Indicates what type of customer the checkout is initialized for. Values are PrivateCustomer or BusinessCustomer
data.customer Contains all customer details for a private customer including the delivery address to which the order should be sent. If the customer is strongly identified with a national identification number, billing address will be included. For a private customer who is identified without a national identification number, the billing address will be the same as the delivery address. We only accept card purchase for those customers and hence a billing address is not needed. For a business customer data.customer is null.
data.customer.deliveryContactInformation Only used if the contact information that has been optionally entered by the user in the delivery address view differs from billing address and will override the corresponding customer property values. Contains mobile phone number. For Private Customers (B2C) only.
NOTE! Previously email was also provided for private customer but is now deprecated and will be removed.
data.businessCustomer Contains all customer details for a business customer including the invoice address and a delivery address to which the order should be sent. Also includes delivery contact information such as mobile phone number for delivery notification (only used if delivery address differs from invoice address). For a private customer data.businessCustomer is null.
data.purchase Contains details for a completed purchase.
data.purchase.paymentName The name of the chosen Payment option the customer used to pay for the purchase.
data.purchase.amountToPay The total amount for the customer to pay for the purchase. This value may be greater than the data.order.totalAmount property due to fees issued by Collector for the chosen payment method.
data.purchase.purchaseIdentifier Required in order to manage the invoice for the purchase, for example to activate or make changes to an invoice. The purchase identifier is the identifier for a purchase when interacting with the Collector E-Commerce Integration.
data.purchase.result The status for the purchase at time when the purchase was made. Any subsequent changes made to the status for a purchase are not reflected in the value of this field, and therefore it cannot be used to track a status for an invoice for example. For details regarding different possible statuses for a purchase, see possible values here.
data.order Contains the total amount and all items for a completed purchase.
data.order.totalAmount The total amount to be settled, i.e. the sum to be paid to you as a merchant for the purchase.
data.hasSessionExpired If true, the Checkout session has expired and a new session must be initialized.
data.metadata Metadata provided during intialization or using the set metadata endpoint. This property will not be included if no metadata exist.

Possible values for the data.status property:

Possible values for the data.purchase.paymentName property:
Please note: These values are subject to change and we strongly encourage you to handle them dynamically. New payment names may emerge without any notice and you should design your system to handle this situation.

Possible values for the data.purchase.result property:

Optional features

Update cart

/*
  javascript client side flow to update Cart
*/

// Suspend the Checkout, showing a spinner...
window.collector.checkout.api.suspend();

// ... then call the backend API to set the new Cart
yourSetCartRequestFunction();

// ... and finally resume the Checkout after the backend call is completed to update the Checkout
window.collector.checkout.api.resume();

Update cart request

PUT /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727/cart HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "items": [
    {
      "id": "2",
      "description": "Another product",
      "unitPrice": 123.45,
      "quantity": 1,
      "vat": 20,
      "requiresElectronicId": true,
      "sku": "a unique alphanumeric code for article identification"
    }
  ]
}

Update cart successful response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": null
}

Update cart example error response

{
  "id": "862336bb-86a5-418b-b6ff-5547398d5c6b",
  "data": null,
  "error": {
    "code": 423,
    "message": "The resource requested is currently locked for modification. Try again.",
    "errors": [
      {
        "reason": "Resource_Locked",
        "message": "The resource requested is currently locked for modification. Try again."
      }
    ]
  }
}

To update the Cart while the Checkout is rendered on the screen, a call to the Checkout Client API's suspend() function shall be performed before calling the Checkout Backend API.

Once in suspend mode, the Checkout cart can be updated by sending in a new cart to the Checkout API from your backend. The content of this request will replace the old cart. This is accomplished by issuing a HTTP PUT request to the following URI:

https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}/cart

... replacing storeId and privateIdin the URL with their respective values.

Once the backend request has completed, a call to the Checkout Client API's resume() function shall be made to update the state of the Checkout session.

Request headers

Header Required Explanation
Authorization Yes The authorization header is generated with the access credentials (usename and shared access key) received from Collector Merchant Services. Instructions on how to generate the authorization header value can be found under the authorization section.

Request Body properties

Property Required Explanation
id Yes The article id or equivalent. Max 50 characters. The combination of id and description (property below) must be unique within the Checkout session including the fees in the cart. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
description Yes Descriptions longer than 50 characters will be truncated. Description and id (property above) must be unique within the Checkout session including the fees in the cart. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPrice Yes The unit price of the article including VAT. Both positive and negative values allowed. Max 2 decimals, i.e. 100.00
quantity Yes Allowed values are 1 to 99999999.
vat Yes The VAT of the article in percent. Allowed values are 0 to 100. Max 2 decimals, i.e. 25.00
requiresElectronicId No When 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.
sku No A stock Keeping Unit is a unique alphanumeric code that is used to identify product types and variations. Maximum allowed characters are 1024.

Important error responses

Error code Error Reason Cause
400 Duplicate_Articles Can't add article/fees since multiple articles/fees with same id and description already exist.
400 Validation_Error The request contains properties with invalid values. Details are provided in the response body.
423 Resource_Locked Another modifying request is currently being executed for the Checkout session. Retry by sending the request again.
900 Purchase_Commitment_Found The customer is currently in the process of signing the purchase with BankID.
900 Purchase_Completed Purchase is already complete.

Update fees

/*
  javascript client side flow to update Fees
*/

// Suspend the Checkout, showing a spinner...
window.collector.checkout.api.suspend();

// ... then call the backend API to set the new Cart
yourSetFeesRequestFunction();

// ... and finally resume the Checkout after the backend call is completed to update the Checkout
window.collector.checkout.api.resume();

Update shipping fee request

PUT /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727/fees HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "shipping": {
    "id":"shipping1",
    "description": "Shipping fee (incl. VAT)",
    "unitPrice": 59,
    "vat": 25
  }
}

Update shipping fee successful response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": null
}

Update shipping fee error response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": {
    "code": 423,
    "message": "The resource requested is currently locked for modification. Try again.",
    "errors": [
      {
        "reason": "Resource_Locked",
        "message": "The resource requested is currently locked for modification. Try again."
      }
    ]
  }
}

To update the shipping fee while the Checkout is rendered on the screen, a call to the Checkout Client API's suspend() function shall be performed before calling the Checkout Backend API.

The shipping fee can then be updated by sending a fee object to the Checkout API from your backend. The fee is optional but will be shown last on the receipt after all the cart items if present and be presented separately on the thank you-page.

Once the backend request has completed, a call to the Checkout Client API's resume() function shall be made to update the state of the Checkout session.

To update the shipping fee, issue a HTTP PUT request to the following URI:

https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}/fees

... replacing storeId and privateIdin the URL with their respective values.

Request headers

Header Required Explanation
Authorization Yes The authorization header is generated with the access credentials (usename and shared access key) received from Collector Merchant Services. Instructions on how to generate the authorization header value can be found under the authorization section.

To set the shipping fee, add a shipping object to the fees object of the request. The shipping object can be null to remove the shipping fee for the current Checkout.

The shipping object contain the following properties:

Property Required Explanation
id Yes An id of the fee item. Max 50 characters. The combination of id and description (property below) must be unique within the Checkout session including the articles in the cart. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
description Yes Descriptions longer than 50 characters will be truncated. Description and id (property above) must be unique within the Checkout session including the articles in the cart. Values are trimmed from leading and trailing white-spaces. Shown on the invoice or receipt.
unitPrice Yes The unit price of the fee including VAT. Allowed values are 0 to 999999.99. Max 2 decimals, i.e. 25.00
vat Yes The VAT of the fee in percent. Allowed values are 0 to 100. Max 2 decimals, i.e. 25.00

Important error responses

Error code Error Reason Cause
400 Duplicate_Articles Can't add article/fees since multiple articles/fees with same id and description already exist.
400 Validation_Error The request contains properties with invalid values. Details are provided in the response body.
423 Resource_Locked Another modifying request is currently being executed for the Checkout session. Retry by sending the request again.
900 Purchase_Commitment_Found The customer is currently in the process of signing the purchase with BankID.
900 Purchase_Completed Purchase is already complete.

Update metadata

/*
  javascript client side flow to update metadata
*/

// Suspend the Checkout, showing a spinner...
window.collector.checkout.api.suspend();

// ... then call the backend API to set the new metadata
yourSetMetadataRequestFunction();

// ... and finally resume the Checkout after the backend call is completed to update the Checkout
window.collector.checkout.api.resume();

Update metadata request

PUT /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727/metadata HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "metadata": {
      "myCustomKey": 1234,
      "myComplexObject": {
        "firstKey": true,
        "CasingIsKept": [1, 2, 3]
      }
  }
}

Update metadata successful response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": null
}

Update metadata example error response

{
  "id": "862336bb-86a5-418b-b6ff-5547398d5c6b",
  "data": null,
  "error": {
    "code": 423,
    "message": "The resource requested is currently locked for modification. Try again.",
    "errors": [
      {
        "reason": "Resource_Locked",
        "message": "The resource requested is currently locked for modification. Try again."
      }
    ]
  }
}

To update the metadata while the Checkout is rendered on the screen, a call to the Checkout Client API's suspend() function shall be performed before calling the Checkout Backend API.

Once in suspend mode, the Checkout metadata can be updated by sending in a new metadata object to the Checkout API from your backend. The content of this request will replace any existing metadata. This is accomplished by issuing a HTTP PUT request to the following URI:

https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}/metadata

... replacing storeId and privateIdin the URL with their respective values.

Once the backend request has completed, a call to the Checkout Client API's resume() function shall be made to update the state of the Checkout session.

Request headers

Header Required Explanation
Authorization Yes The authorization header is generated with the access credentials (usename and shared access key) received from Collector Merchant Services. Instructions on how to generate the authorization header value can be found under the authorization section.

Request Body properties

Property Required Explanation
metadata No Metadata object that will replace any existing metadata. Each key in the object must be a string but the value can be any valid JSON value. Providing null will remove any existing metadata.

Important error responses

Error code Error Reason Cause
400 Validation_Error Metadata object could not be parsed as a valid JSON object.
423 Resource_Locked Another modifying request is currently being executed for the Checkout session. Retry by sending the request again.
900 Purchase_Commitment_Found The customer is currently in the process of signing the purchase with BankID.
900 Purchase_Completed Purchase is already complete.

Client-side events

Client-side JavaScript for listening to events

// Start listening to the customer updated event
document.addEventListener( 'collectorCheckoutCustomerUpdated', listener );

// Start listening to the order validation failed event
document.addEventListener( 'collectorCheckoutOrderValidationFailed', listener );

// Start listening to the locked event
document.addEventListener( 'collectorCheckoutLocked', listener );

// Start listening to the unlocked event
document.addEventListener( 'collectorCheckoutUnlocked', listener );

// Start listening to the reloadedByUser event
document.addEventListener( 'collectorCheckoutReloadedByUser', listener );

// Start listening to the expired event
document.addEventListener( 'collectorCheckoutExpired', listener );

// Start listening to the resumed event
document.addEventListener( 'collectorCheckoutResumed', listener );

// Start listening to the purchase completed event
document.addEventListener( 'collectorCheckoutPurchaseCompleted', listener );

In order to provide a better customer experience you can listen to custom client-side events and take appropriate action. All events are dispatched using the global document object as target and cannot be cancelled and does not bubble.

Description of available events

Event Description
collectorCheckoutCustomerUpdated Occurs when the Checkout client-side detects any change to customer information, such as a changed email, mobile phone number or delivery address. This event is also fired the first time the customer is identified.
collectorCheckoutOrderValidationFailed This event is only used if you use the optional validate order functionality. Occurs if a purchase is denied due to the result of the backend order validation (in other words if the response from the validationUri set at initialization is not successful). This usually means that one or more items in the cart is no longer in stock.
collectorCheckoutLocked Occurs when no user input should be accepted, for instance during processing of a purchase.
collectorCheckoutUnlocked Occurs after a locked event when it is safe to allow user input again. For instance after a purchase has been processed (regardless of whether the purchase was successful or not).
collectorCheckoutReloadedByUser Occurs when the user has clicked a "reload" button in the Checkout. This can occur when there is a version mismatch in the Checkout. An example is when adding an item to the cart and before calling suspend/resume trying to set an alternative delivery address. This will show a message to the user that there is a conflict and the Checkout must be reloaded.
collectorCheckoutExpired Occurs when the Checkout session has expired. A new Checkout session must be initialized and the new public token set on a new loader script.
collectorCheckoutResumed Occurs when the Checkout has loaded new data and is back in its normal state after a suspend. See section Client-side API for more details.
collectorCheckoutPurchaseCompleted Occurs when the purchase has been completed.

Client-side API

JavaScript client side API examples

// Suspend the Checkout, showing a spinner...
window.collector.checkout.api.suspend();

// ... then do something...

// ... and finally resume the Checkout.
window.collector.checkout.api.resume();

After the script collector-checkout-loader.js has been loaded it will be possible to interact with the iframe using the provided API. The API functions are exposed via the global object window.collector.checkout.api.

Function Parameters      Description
init (none) This re-executes the initialization of the loading script. Not needed under normal circumstances.
suspend publicToken (optional string) Sets the Checkout iframe in suspend mode. This results in all inputs and buttons being disabled and a spinner to be shown. If publicToken is not specified all Checkout iframes on the page will be suspended.
resume publicToken (optional string) Resumes the Checkout to its normal state after a suspend. This results in data being loaded from the Checkout backend in order to stay up to date with any changes. If publicToken is not specified all Checkout iframes on the page will be resumed.

Validate order

Example of validate order request made by the Checkout API

GET /validation-uri-provided-in-initialize HTTP/1.1
Host: yourdomain.se

Example of successful validate order response

{
  "orderReference": "123456789"
}

Example of unsuccessful validate order response

{
  "title": "Title to be displayed",
  "message": "Message to be displayed"
}

In order to make sure that the articles the customer is buying indeed exists in stock, you can provide a validation uri in the Initialize a Checkout Session request. If this uri is provided, we will call this uri before the purchase is completed.

During this validate call, your backend can (optionally) create an order and send the order reference back in the response as json. Note that this order should not have a Completed status since the purchase is not done yet. Please read up on notification will be sent since the notification callback is the only valid place to consider a purchase to be successful.

If an order reference is provided in the response it will be shown on the thank you page.

Please note that even if the validate call was successful (2xx, e.g. 200 OK) the purchase might not be completed due to various reasons. For example, the credit check on the customer might be rejected.

If this call returns a non-2xx http status code, we will stop the purchase and emit a frontend event, read more in section Client-side events. We will follow redirects, e.g. 301.

This call has a timeout of 10 seconds, if the call does not return a response within this timeout the purchase will not be completed and the customer will be shown a message and given the opportunity to try again. Please note that this endpoint might be called several times. For example when the end customer fails the credit check and chooses to purchase by card or direct bank transfer instead. In these cases there will be several calls to this endpoint.

Request properties

There are no request properties.

Properties for successful response

Property Required Explanation
orderReference No Order reference to the order just created during the validate call. This can later be used to track the purchase with merchant services. Max 50 chars.

Properties for unsuccessful response

Property Required Explanation
title No The title of the validation failure displayed in the Checkout. Truncated to max 512 chars.
message No The message with a more descriptive text why the validation failed, and how the customer should proceed. Truncated to max 512 chars.

In order to override the default title and message both title and message must be specified in the response.

The response must be empty or a valid Json document.

Set Order Reference

Example of set order reference request


PUT /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727/reference HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
{
"Reference": "ABCDEFGHJIKLMNOP"
}

Example of successful set order reference response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": null
}

To update the Order Reference for a Checkout session after it has been completed, typically in the callback implementation of Notification, issue a HTTP PUT request to the following URI: https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}/reference

replacing storeId and privateId in the URL with their respective values, and providing a json object with the new Reference in the Body of the request.

It is only allowed to set the Order Reference one time if the Purchase has already been completed.

Request properties

Property Required Explanation
Reference Yes A reference to the order, i.e. order ID or similar. Note that the reference provided here will not be shown to the customer but can be correlated with the PurchaseIdentifier shown to the customer. Max 50 chars.

Example of a pay link request

POST /merchants/123/checkouts/1eec44b5-66d3-4058-a31f-3444229fb727/paylink HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
{
    "destination": {
            "mobilePhoneNumber": "0730481277"
        }
}

Example of a pay link response

{
  "id": "f5f4e86d-95b1-4c1a-8ad0-1d5907236bd7",
  "data": null,
  "error": null
}

It is possible to send a Pay Link to a customer. This enables end customers to receive a ready-to-pay checkout session where they can finalize the purchase on their own device by identifying themselves and selecting a payment option. The rest of the flow will be the same as for a regular Checkout session i.e. the notification callback to your system will be performed once the purchase is successful and if you have implemented the validate call it will be performed as usual.

To push a Pay Link you must first create the Checkout session as you normally do by following the Getting started guide here

When the session has been created you use the privateId in that response and your merchant credentials to issue a POST request to the following URL:

https://checkout-api-uat.collector.se/merchants/{storeId}/checkouts/{privateId}/notification

replacing storeId and privateId in the URL with their respective values.

The body of the request should contain a json object with the receivers mobile telephone number as shown in the example request.

Request headers

Header Required Explanation
Authorization Yes The authorization header is generated with the access credentials (usename and shared access key) received from Collector Merchant Services. Instructions on how to generate the authorization header value can be found under the authorization section.

Request properties

Property Required Explanation
destination.mobilePhoneNumber Yes The recepients mobile phone number. Currently the phone number must match the country where the purchase is made. Country prefix will automatically be added if needed, i.e. +46730 and 0730 are both accepted as start of a valid phone number.

Error responses

Error code Error Reason Cause
400 Validation_Error The request contains properties with invalid values. Details are provided in the response body.
503 Could not notify customer The service provider to push a deep-link returned an error or was unavailable.

In-store mode

Collector Checkout supports running in in-store mode. In-store mode is intended to be used on a tablet or computer in a physical store where merchandise is then collected at a drop off point inside the store.

When running in in-store mode the following rules apply:

In-store mode is configured per store id. Please contact Collector Merchant services to configure your store id as a in-store merchant.

Settings Profiles

Collector Checkout supports a concept of settings profiles to allow merchants to control which features can be used by the end customer. The profiles are setup by Merchant Services merchant@collectorbank.se and each profile is given a unique name that is used by the Merchant when inititalizing the Checkout.

The following is a subset of the features that can be set using profiles. Please contact Merchant Services merchant@collectorbank.se for additional information.

Checkout API reference

Authorization

Javascript Example on how to generate the authorization header value. For an executable example, please refer to https://jsfiddle.net/wmLg1s35/12/ (POST/PUT) or https://jsfiddle.net/te2n8bqe/ (GET)

var username = 'myUsername';
var path = '/checkout';
var sharedAccessKey = 'mySharedKey';

// Note, blank spaces and rows have been formatted in the example for readability. This will have impact on the hashed result.
var requestBody = {
   "storeId":123,
   "countryCode":"SE",
   "reference":"123456789",
   "notificationUri":"http://your-backend-api-notification-uri.com",
   "redirectPageUri":"http://your-purchase-completed-confirmation-page.com",
   "merchantTermsUri":"http://your-merchant-purchase-terms.com",
   "cart":{
     "items":[
        {
          "id":"1",
          "description":"Some product",
          "unitPrice":200,
          "quantity":1,
          "vat":20,
          "requiresElectronicId": true,
          "sku": "a unique alphanumeric code for article identification"
        }
      ]
   }
}

var hash = username + ":" + CryptoJS.SHA256(requestBody + path + sharedAccessKey);
var key = 'SharedKey ' + btoa(hash); //btoa = encodeBase64

console.log(key);
// Should be SharedKey bXlVc2VybmFtZTpmNTJiYzE3YmIyNWFmOWYzMzVlY2M2MjhjOWY0N2RiNGMwNTdmY2ZhYmVlYzRjM2Y0ZDRiMjRiMTU2N2QwYWNk

PHP Example on how to generate the authorization header value. Note, the request_body is formatted here for readability. For a GET request that does not have a request body, the request_body is simply omitted from the calculation.

<?php
$user_name = 'myUsername';
$path = '/checkout';
$shared_access_key = 'mySharedKey';
$request_body = '{"storeId":123,
                  "countryCode":"SE",
                  "reference":"123456789",
                  "notificationUri":"http://backend-api-notification-uri.com",
                  "redirectPageUri":"http://purchase-completed-confirmation-page.com",
                  "merchantTermsUri":"http://merchant-purchase-terms.com",
                  "cart":{
                    "items":[
                      {
                        "id":1,
                        "description":"a product description of your choice",
                        "unitPrice":200,
                        "quantity":1,
                        "vat":20},
                        "requiresElectronicId": true,
                        "sku": "a unique alphanumeric code for article identification"
                      ]
                        }
                  }';

$hash = $user_name.":".hash("sha256",$request_body.$path.$shared_access_key);
$key = 'SharedKey '.base64_encode($hash);

echo $key;
// Should be SharedKey bXlVc2VybmFtZTpmNTJiYzE3YmIyNWFmOWYzMzVlY2M2MjhjOWY0N2RiNGMwNTdmY2ZhYmVlYzRjM2Y0ZDRiMjRiMTU2N2QwYWNk
?>

All communication with the Checkout API requires specifying an authorization header. To generate the authorization header, concatenate the string "SharedKey " with the base64 encoded value of your userName and the SHA-256 hash of the request_body, path and the shared_access_key.

"SharedKey " + base64({userName} + ":" + sha256({request_body} + {path} + {shared_access_key}))

The formula above explains how to generate the authorization header value, where:

An example illustrating how the authorization header value may be calculated using JavaScript can be found here: https://jsfiddle.net/wmLg1s35/12/

The same example for a GET request, where the request body is simply omitted, can be found here: https://jsfiddle.net/te2n8bqe/

Errors

The Checkout API may return the following HTTP error codes:

Error Code Meaning
400 Bad or faulty request. Please examine the errors property for details.
401 The resource requested requires authentication.
403 Access to the requested resource is denied.
404 The resource requested was not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
423 The resource requested is currently locked for modification. Try again.
500 An unhandled exception has occured. Please contact Collector!
503 Service unavailable.
900 The request was rejected by the server due to a business error.

Payment types

The Checkout can be configured to offer multiple different payment types for the end customer. Below follows a brief explanation of the different possible payment types available.

Payment Type Description
Direct Invoice This payment type will send an invoice by email to the end customer.
Account The end customer's aggregated purchases during a month period will be invoiced in the end of the month. Notification fees from Collector can apply to this payment option.
Part Payment Splits the payment over several months. Either interest free or annuity payments. Disabled for amounts lower than 1000 SEK for B2C customers.
Campaign A Buy-Now-Pay-Later payment option.
Card The end customer pays directly with VISA or MasterCard.
Trustly The end customer signs into the bank to do a transfer using the Trustly user interface

Branding resources

Example: Standard badge image tag with a width of 340px

<img src="https://checkout.collector.se/resources/images/sv-SE/collector-checkout-badge-color.svg"
     style="width: 340px"
     alt="Collector Checkout" />

A badge is a good way to inform the customers that a safe payment solution is used on the site.

Format

The badge is delivered in the svg format and is fully scalable.

Background

Please select the badge that best matches the site. If you have a dark background color, the white badge might be used for optimal contrast and display.

Country

The country-code included in the path specifies the required language of the badge as well as other localizations such as what payment methods to include. Currently available: sv-SE, en-SE, fi-FI, sv-FI, nb-NO and da-DK

Resource location

Please link directly to the checkout domain resource to ensure the image to stay updated.

Badge Type Url
Standard https://checkout.collector.se/resources/images/sv-SE/collector-checkout-badge-color.svg
For dark backgrounds https://checkout.collector.se/resources/images/sv-SE/collector-checkout-badge-white.svg

Examples

Standard
Collector Checkout

For use with dark backgrounds (grey panel just for demonstration)
Collector Checkout



Test credentials

With our test credentials below you will be able to verify that our Collector Checkout Integration is working using our test environment. Make sure that you are going towards our UAT/Test environment with correct endpoints.

No real money will be involved in the transactions.

Test Credit Card

Credit card number: 4571999400007492

Expiration date: 12 / 22 (Or any other valid date in the future)

CVV: 123

Test Persons

We have different test persons for the different countries, but they are subject to change on a regular basis.

B2C Sweden:

Status Approved Approved Not Approved
Email address Your own Your own Your own
Phone Number Your own Your own Your own
First name Approved08 Approved16 Rejected00
Last name Sweden08 Sweden16 Sweden00
Address MELLANGATAN 2 MELLANGATAN 3 STORGATAN 2
Zip code 53431 53431 84093
City VARA VARA HEDE
CivRegNo 198010011008 198010011016 199901010000

B2B Sweden:

Status Approved Not Approved
Organization no 5562000116 5563698488
Company namne Test No 3 mining enterprise Beslutstest AB
Address1 Rosenborgsgatan 4
Postal Code 16974 11479
City Solna Stockholm
Authorised Signatory 5001010007, 5001010023 N/A

B2C Norway:

Status Approved Approved Not Approved
Email address Your own Your own Your own
Phone Number Your own Your own Your own
First name Approved23 Approved42 Rejected49
Last name Norway23 Norway42 Norway49
Address STORGATA 1 STORGATA 15 RADARVEIEN 22
Zip code 9300 9300 1152
City FINNSNES FINNSNES OSLO
CivRegNo 01028049923 01028049842 01019949849

B2B Norway:

Status Approved Not Approved
Organization no 937340303 927822334
Company namne Svar Direkte As Not Approved AS
Address1 C/O Testgruppen Testgatan 1
Postal Code 0508 0508
City Oslo Oslo

B2C Denmark:

Status Approved Not Approved
Email address Your own Your own
Phone Number Your own Your own
First name Approved18 Rejected01
Last name Denmark18 Denmark01
Address Skolegade 27 Havnegade 87
Zip code 1659 7600
City København V Struer
CivRegNo 0104820018 0101990001

B2C Finland:

Status Approved Approved Not Approved
Email address Your own Your own Your own
Phone Number Your own Your own Your own
First name Approved0P Approved1R Rejected0A
Last name Finland0P Finland1R Finland0A
Address Kluuvikatu 16 Puutarhakatu 88 Kankaanpääntie 71
Zip code 01510 01620 94700
City VANTAA VANTAA KEMI
CivRegNo 010380-000P 010380-001R 010199-010A

B2B Finland:

Status Approved Not Approved
Organization no 08302150 20148387
Company namne Bisnode D&B Finland Oy Bisnode Finland Oy
Address1 Kumpulantie 3 C Kumpulantie 3
Postal Code 00520 00520
City Helsinki Helsinki

Go live checklist

Before we can inspect and approve your integration with our Collector Checkout, you need to ensure that all check boxes below have been marked. Please go through the list and if you have any questions, feel free to contact us!

Do you save the public token-session and use it throughout the interaction with Collector Bank? The public token is valid for 7 days. Read more at Render the checkout iFrame.

Do you always react on our GET-request when being sent to your notification Uri? When you receive the notification callback, do you perform a request to our API to get the latest customer and purchase information?

Do you keep the amount of requests to our API on a necessary level? For example handle the update fees and cart separately as stated in our documentation.

Have you sent in a correct page for terms of purchase?

Do you render our checkout Iframe on your confirmation page correctly?

If use of validate-callback, make sure the response is in accordance to our documentation.

Have you contacted merchant@collectorbank.se to verify the integration?


















Widgets

Widgets are small components that can be used in any place of your website to enhance the customer experience around payments and checking out.
They can for example be used to boost sales on a specific product by showing alternatives to pay already on the product detail view

Initialize a Widget session

Initialize widget session request

POST /widget HTTP/1.1
Host: checkout-api-uat.collector.se
Content-Type: application/json
Authorization: SharedKey bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "storeId": 123,
}

Initialize widget session response

{
  "id": "91714012-6ae9-4780-a927-fe459bc95bf6",
  "data": {
    "widgetToken": "widget-NO-0TTJOMERnUGlVN1JtazFwZUo2UmFZVW92dFA5cXpEOXVzZit5dFJlcVZ4QUdpMlF5MmdUNVVqN3I4T3BzVEpCekJCelNY",
    "expiresAt": "2019-12-07T07:16:49.8098107+00:00"
  },
  "error": null
}

The initialization of a widget session is similar to the way it is done for the Checkout.

Request headers

Header Required Explanation
Authorization Yes Instructions 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

Property Required Explanation
storeId Yes Received from Collector Merchant Services.

Response

Property Explanation
widgetToken The widgetToken is used to render the widget iframe. NB! The token should be reused for all widgets until it expires.
expiresAt The timestamp when this widget session expires.

Part Payment Widget

The Part Payment Widget can be placed at a product page to show the customers what the monthly amount will be if choosing to purchase the item with part payment. If the amount is below the threshold for part payment, the widget will inform the customer that direct invoice is available.

Render the Part Payment Widget iframe

Place this script at the pages where you want the widget to appear

<script
  src="https://checkout-uat.collector.se/collector-checkout-loader.js"
  data-token="widget-NO-0TTJOMERnUGlVN1JtazFwZUo2UmFZVW92dFA5cXpEOXVzZit5dFJlcVZ4QUdpMlF5MmdUNVVqN3I4T3BzVEpCekJCelNY"
  data-widget="part-payment"
  data-amount="123450"
></script>

The Part Payment Widget iframe is rendered in the same way as the Checkout iframe

Script element attributes

Attribute Explanation
data-token The widget token received when initializing the widget session. NB! The token should be reused for all Part Payment Widgets until it expires.
data-widget The name of the widget. In this case part-payment.
data-amount The price of the item. NB! To avoid decimals the amount must be multiplied by 100, e.g. 1234.50 becomes 123450. Allowed values are 100 to 9999999900.
data-lang (optional) The display language. Currently supported combinations are: sv-SE, en-SE, nb-NO, fi-FI and sv-FI.
data-padding (optional) Set this to none in order to cancel out the left and right padding inside the iframe (by adjusting its margins and width).
data-container-id (optional) Set this to the id of an element on the page and the iframe will render inside this element instead of immediately above the script element of the loader script. Put the container element somewhere above the script element. This is to make sure the container element is loaded before trying to populate it with the iframe.

Update the Part Payment Widget

Step 1: Set the data-amount attribute

<script
  src="https://checkout-uat.collector.se/collector-checkout-loader.js"
  data-token="widget-NO-0TTJOMERnUGlVN1JtazFwZUo2UmFZVW92dFA5cXpEOXVzZit5dFJlcVZ4QUdpMlF5MmdUNVVqN3I4T3BzVEpCekJCelNY"
  data-widget="part-payment"
  data-amount="123450"
></script>

Step 2: Call the JavaScript client side API to update

// Update the widget with the new data
window.collector.checkout.api.update();

If the amount is updated, the data-amount script element attribute should be set to the new value. Thereafter a call to the update event of the window.collector.checkout.api must be made.