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.

Before you start

You need API credentials from Merchant Hub. Call this endpoint from your backend only. If you initialize a session from client-side code, customers can read your credentials.

Explore all features

This guide covers the basic steps to initialize a checkout session. For every available property, optional configuration and advanced use case, see Advanced initialization.

Quick start

Minimal Request

Basic example to get started:

POST /checkouts HTTP/1.1
Host: api.uat.walleydev.com
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:

POST /checkouts HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json

{
  "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 object for callback configuration details.

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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",
    "paymentUri": "https://checkout.uat.walleydev.com/p/npBc87EFB",
    "paymentQrCodeUri": "https://api.uat.walleydev.com/checkouts/paylinks/npBc87EFB/qrcode"
  },
  "error": null
}

Use the response:

• publicToken - Pass to render the checkout iframe
• privateId - Use to get checkout information
• expiresAt - When the session expires. A session is valid for 7 days from creation

See Response for the full property list.

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

---

Request 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	No *	number	Your unique store identifier
countryCode	Yes	string	Market code: SE, NO, FI, DK, DE, NL, or EU
merchantTermsUri	Yes	string	URL to your terms and conditions page. Must be https.
notificationUri	Yes	string	Endpoint for purchase notifications. Must be https.
cart	Yes	object	Shopping cart with items. See Cart Object

* Only needed when countryCode and salesSegment do not identify a single store. The examples above send it because it always resolves on its own. See Selecting a store.

Production vs UAT

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

See Endpoints for the 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 Validation

The cart cannot consist entirely of items with negative unitPrice values. At least one item in the cart must have a non-negative unit price.

Cart example

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

Response

A successful response returns all five properties below in the data object, alongside the top-level id and a null error.

Property	Explanation
publicToken	Renders the Checkout iframe. Valid for 168 hours (7 days).
privateId	Identifies the session in every backend call. Use it to acquire information for up to 90 days after the session was created, and to update the session until it completes or expiresAt passes.
expiresAt	When the session expires. After this timestamp the customer cannot complete the purchase and you cannot update the cart, so initialize a new session.
paymentUri	A shortcut link to this session, used when distributing a Pay Link.
paymentQrCodeUri	A QR code image of paymentUri. The URL needs no authentication, so you can embed it directly.

For the callback, prefill, custom field and URI templating properties, see Advanced initialization.