---
id: initcheckout
title: Initialize checkout
hide_title: true
description: "Basic steps to initialize a new Checkout session from the Merchant API"
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Ingress from "../../src/components/ingress/ingress.react";

<Ingress title="Initialize a Checkout session">
  Initialize a Checkout session by making a POST request to the checkout backend API
  <a href="/docs/checkout/endpoints">endpoint</a>. This returns a public token for
  <a href="/docs/checkout/renderiframe">rendering the Checkout iframe</a> and a
  private ID for <a href="/docs/checkout/getcheckoutinformation">retrieving checkout information</a>.
</Ingress>

:::info Before you start
You need [API credentials](/docs/checkout/prerequisites) from Merchant Hub. Call this endpoint from your backend only. If you initialize a session from client-side code, customers can read your credentials.
:::

:::tip 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](/docs/checkout/optional/init-checkout-features).
:::

## Quick start

<Tabs defaultValue="minimal" values={[
{ label: 'Minimal Request', value: 'minimal' },
{ label: 'With Callbacks', value: 'callbacks' },
{ label: 'Success Response', value: 'res' },
{ label: 'Error Response', value: 'fault' }
]}>
<TabItem value="minimal">

**Basic example to get started:**

```http
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
      }
    ]
  }
}
```

</TabItem>

<TabItem value="callbacks">

**With order validation callback:**

```http
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](/docs/checkout/optional/init-checkout-features#callback-object) for callback configuration details.

</TabItem>

<TabItem value="res">

```http
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](/docs/checkout/renderiframe)
- **`privateId`** - Use to [get checkout information](/docs/checkout/getcheckoutinformation)
- **`expiresAt`** - When the session expires. A session is valid for 7 days from creation

See [Response](#response) for the full property list.

</TabItem>

<TabItem value="fault">

```http
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](/docs/checkout/error-codes) for troubleshooting.

</TabItem>
</Tabs>

---

## Request properties

### Request headers

| Header | Required | Description |
|--------|----------|-------------|
| **Authorization** | Yes | Bearer token for authentication. See [Authorization](/docs/checkout/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](/docs/checkout/notificationcallback). Must be `https`. |
| **cart** | Yes | object | Shopping cart with items. See [Cart Object](#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](/docs/checkout/optional/init-checkout-features#selecting-a-store).

:::note Production vs UAT
- **UAT:** `https://api.uat.walleydev.com/checkouts`
- **Production:** `https://api.walleypay.com/checkouts`

See [Endpoints](/docs/checkout/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%) |

:::note 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

```json
{
  "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](/docs/checkout/renderiframe). Valid for 168 hours (7 days). |
| **privateId** | Identifies the session in every backend call. Use it to [acquire information](/docs/checkout/getcheckoutinformation) 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](/docs/checkout/paylink/overview). |
| **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](/docs/checkout/optional/init-checkout-features).