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.
- Example Request
- Example Response
- Example Faulty Response
/*
POST /checkout HTTP/1.1
Host: api.checkout.uat.walleydev.com (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",
"checkoutAbortedRedirectPageUri": "https://example.com/back-to-your-shop",
"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,
"unitWeight": 0.3,
"quantity": 1,
"vat": 25.0,
"requiresElectronicId": true,
"sku": "a unique alphanumeric code for article identification"
}
],
"shippingProperties": {
"height": 10,
"width": 20,
"isBulky": true
}
},
"fees": {
"shipping": {
"id": "shipping001",
"description": "Shipping cost (incl. VAT)",
"unitPrice": 59.0,
"vat": 25.0
}
},
"privateCustomerPrefill": {
"email": "test@walleypay.se",
"mobilePhoneNumber": "+46701234567",
"nationalIdentificationNumber": "19520101-1234",
"deliveryAddress": {
"firstName": "John",
"lastName": "Doe",
"coAddress": "c/o Jane Doe",
"address": "Sunny road 2",
"address2": "Another address line if needed",
"postalCode": 12345,
"city": "Big Town"
}
},
"customFields": [
{
"id": "group1",
"metadata": {
"groupMeta": "content"
},
"fields": [
{
"id": "newsConsent",
"name": "I agree to receive marketing communications",
"type": "Checkbox",
"value": true,
"metadata": {
"field1Meta": "field-newsletter-consent"
},
"localizations": {
"fi-FI": {
"name": "Hyväksyn markkinointiviestinnän vastaanottamisen",
"value": false,
"metadata": {
"field1Meta": "fi-field-newsletter-consent"
}
}
}
},
{
"id": "comments",
"name": "Any additional comments?",
"type": "Text"
}
]
}
],
"metadata": {
"administrator": "John Doe",
"someOtherData": [1, { "myObj": { "key": 1 } }]
}
}
{
"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."
}
]
}
}
Request
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 Walley Merchant Services. |
Request Body Properties
| Property | Required | Explanation |
|---|---|---|
| storeId | No | Received from Walley Merchant Services. The store ID is only required in the request when integrating multiple stores with Walley Checkout. |
| 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. |
| settlementReference | No * | 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 |
| 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. |
| checkoutAbortedRedirectPageUri | No | If set and rendering a Pay Link, a go back button will appear for the customer and if clicked, the checkout session will be deleted and the browser will redirect to this page. |
| 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 Walley 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 help@walley.se |
| cart | Yes | The initial Cart object with items to purchase (details below) |
| fees | No | Shipping fee (details below) |
| privateCustomerPrefill | No | Customer information for identification (details below) |
| customFields | No | Custom inputs to be rendered inside the checkout (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 |
| unitWeight | No | The weight of the article. Only positive values are allowed (including zero) |
| 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 electronic id such as Mobilt BankID. An example would be selling tickets that are delivered electronically. This feature is supported for B2C and B2B on the Swedish, Norwegian and Finnish markets. |
| 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. |
Please note
Each item in the cart is identified by a unique identifier. The identifier used depends on which PaymentService version is used to active the purchase.
For PaymentService v10 or later: All properties except quantity are used as the unique identifier. Multiple articles with the same unique combination of properties will be merged (quantities are summed). Uniqueness does not span to fees.
For PaymentService v9 or earlier: 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. Uniqueness also spans to fees.
The shippingProperties is optional and only relevant if a Delivery Module is used.
It gives flexibility to customize what delivery methods should be available based on the items in the cart.
Read more about how these properties are included when Fetching Delivery Methods.
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.
| 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 |
Please note if using PaymentService v9 or older
The combination of id and description of a fee must be unique within the cart and fees objects.
PrivateCustomerPrefill object (optional)
The privateCustomerPrefill 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.
It is highly encourage to include as complete data as possible when using prefill.
Examples
- If
emailandmobilePhoneNumberare provided and the combination is matched for a previously known customer, the user will be logged in and ready for purchase. - If
emailandmobilePhoneNumberare provided but the combination does not match a previously known customer, we will prompt the user for further identification details. - If
emailandmobilePhoneNumberare provided together withnationalIdentificationNumberwe will try to identify the customer using these values by doing a lookup in an address registry. - If a complete
deliveryAddressis provided the address will be set as the customer's delivery address. - If a non-complete
deliveryAddressis provided the address will be shown upon initial identification for the customer if the customer choses to not enter their national registration number.
| Property | Required | Explanation |
|---|---|---|
No * | The customer's email address. | |
| mobilePhoneNumber | No * | The customer's mobile phone. When providing a number from a foreign country, it must have a valid prefix such as +46 or 0046. |
| nationalIdentificationNumber | No | The customer's national identification number. |
| deliveryAddress | No | The customer's delivery address containing firstName, lastName, coAddress, address, address2, postalCode and city. |
* email and mobilePhoneNumber are required when identifying a user using a profile with DeliveryMode: Digital
CustomFields (optional and only for checkout 2.0)
The customFields array allows you to optionally provide a blueprint for fields of your choosing to be rendered inside the checkout. These can be things like consent for newsletter or comments.
It will be rendered in it's own section after the payment methods.
You can specify multiple groups that will be rendered as their own separate sections, and the name field will set the header. We recommend not to have a name present if you only have one group.
Each group can contain fields. We currently support checkboxes (shown as animated switches) and text fields. They may have a default value.
Every group and field can also contain overriding localization information for markets with multiple languages, or to simplify with one configuration regardless of the current session language.
Every level also supports a metadata object (see below for more information).
Group object
| Property | Required | Explanation |
|---|---|---|
| id | Yes | An id for the group. Max 50 characters. Values are trimmed from leading and trailing white-spaces. |
| name | No | The header rendered above the group section |
| metadata | No | A metadata object for the group (see below for more info) |
| localizations | No | Specify a different name and metadata for other languages (specified with ISO language codes) |
| fields | Yes | An array of fields to render (see below) |
Fields object
| Property | Required | Explanation |
|---|---|---|
| id | Yes | An id for the field. Max 50 characters. Values are trimmed from leading and trailing white-spaces. |
| name | Yes | The label for the field |
| type | Yes | The type of field to be rendered. "Checkbox" or "Text" |
| value | No | The default value for the field. A string for text fields and true/false for checkboxes |
| metadata | No | A metadata object for the group (see below for more info) |
| localizations | No | Specify a different name/value/metadata for other languages (specified with ISO language codes) |
Metadata object
The metadata object allows you to optionally provide custom metadata information in a key/value format. Metadata is not processed by Walley 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 | The privateId is used to perform backend communication with the Checkout API for the given session. The privateId is used to acquire information for an ongoing or completed session for up to 6 months after it was created. The privateId is also used when modifying a session (e.g. cart update). Updates can be made for a session until it is completed or expiresAt has passed. |
| 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. |
Templating the uri values
The notificationUri, validationUri, redirectPageUri and the hostedPaymentPageAbortedRedirectUriUri properties can optionally be templated.
A correctly templated specified uri will replace the varibles with the real values for the given Checkout session when called.
Allowed template values:
| Uri | {checkout.publictoken} | {checkout.id} |
|---|---|---|
| notificationUri | ✔️ | ✔️ |
| validationUri | ✔️ | ✔️ |
| redirectPageUri | ✔️ | ❌ |
| hostedPaymentPageAbortedRedirectUri | ✔️ | ❌ |
The variable names {checkout.id} will be replaced by the privateId and {checkout.publictoken} will be replaced by publicToken. Note that the variables are case-sensitive.