Initialize a Checkout Session

Initialize a Checkout session by making a POST request to the checkout backend API endpoint. This returns a public token for rendering the Checkout iframe and a private ID for retrieving checkout information.

Explore All Features

This guide covers the basic steps to initialize a checkout session. For comprehensive coverage of all available features, optional configurations, and advanced use cases, see the Initialize Checkout Features Guide.

Quick Start

Minimal Request

Basic example to get started:

/*
POST /checkouts HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json
*/

{
  "storeId": 123,
  "countryCode": "SE",
  "merchantTermsUri": "https://example.com/terms",
  "notificationUri": "https://example.com/notifications",
  "cart": {
    "items": [
      {
        "id": "10001",
        "description": "Product Name",
        "unitPrice": 100.0,
        "quantity": 1,
        "vat": 25.0
      }
    ]
  }
}

With Callbacks

With order validation callback:

{
  "storeId": 123,
  "countryCode": "SE",
  "merchantTermsUri": "https://example.com/terms",
  "notificationUri": "https://example.com/notifications",
  "callback": {
    "callbackUri": "https://example.com/callbacks",
    "callbackTypes": ["ValidateOrder", "PaymentFailed"]
  },
  "cart": {
    "items": [
      {
        "id": "10001",
        "description": "Product Name",
        "unitPrice": 100.0,
        "quantity": 1,
        "vat": 25.0
      }
    ]
  }
}

See Callback Guide for callback configuration details.

Success Response

{
  "id": "91714012-6ae9-4780-a927-fe459bc95bf6",
  "data": {
    "privateId": "1eec44b5-66d3-4058-a31f-3444229fb727",
    "publicToken": "public-SE-7f1b3d2a2a73d348dfbd17d3965ff1458c249f84c695eac1",
    "expiresAt": "2025-12-07T07:16:49.8098107+00:00"
  },
  "error": null
}

Use the response:

• publicToken - Pass to render the checkout iframe
• privateId - Use to get checkout information
• expiresAt - Checkout session valid for 90 days from creation

Error Response

{
  "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."
      }
    ]
  }
}

See Error Codes for troubleshooting.

---

Required Properties

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication. See Authorization
Content-Type	Yes	Must be application/json

Request Body

Property	Required	Type	Description
storeId	Yes	number	Your unique store identifier
countryCode	Yes	string	Market code: SE, NO, FI, DK, DE, or EU
merchantTermsUri	Yes	string	URL to your terms and conditions page
notificationUri	Yes	string	HTTPS endpoint for purchase notifications
cart	Yes	object	Shopping cart with items. See Cart Object

Production vs UAT

• UAT: https://api.uat.walleydev.com/checkouts
• Production: https://api.walleydev.com/checkouts

See Endpoints for complete list.

---

Cart Object

The cart must contain at least one item with these required properties:

Property	Required	Type	Description
id	Yes	string	Unique item identifier
description	Yes	string	Product name/description
unitPrice	Yes	decimal	Price per unit (including VAT)
quantity	Yes	integer	Number of items
vat	Yes	decimal	VAT percentage (e.g., 25.0 for 25%)

Cart Example

{
  "cart": {
    "items": [
      {
        "id": "product-123",
        "description": "Premium Widget",
        "unitPrice": 299.0,
        "quantity": 2,
        "vat": 25.0
      }
    ]
  }
}

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 180 days 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.