Checkout Sessions API

Create Checkout Session

Changed on Nov 3, 2026

🚧 Beta feature

This feature is currently in beta.

The shipping and requiredCustomerDetails properties are still in private beta.

Create a Checkout Session to start a checkout process with Mollie Components.

🔑 Access with

API key

Advanced access token with sessions.write

OAuth access with sessions.write

post/sessions

Request

Base URL
https://api.mollie.com/v2
URL
https://api.mollie.com/v2/sessions
Auth
- HTTP bearer
- or HTTP bearer
- or OAuth 2
  Authorization code: https://my.mollie.com/oauth2/authorize
  Token URL: https://api.mollie.com/oauth2/tokens scopes: sessions.write

Request body

resourcestring

The resource type of the object.

idstring

The identifier uniquely referring to this Checkout Session. Mollie assigns this identifier at Checkout Session creation time. Mollie will always refer to the Checkout Session by this ID. Example: sess_5B8cwPMGnU6qLbRvo7qEZo.

modestring

Whether this entity was created in live mode or in test mode.

Possible values: live test

clientAccessTokenstring

The client access token for the Checkout Session. Use the client access token to initialize Mollie Components.

statusstring

The Checkout Session's status.

Possible values: open completed expired

descriptionstring required

A user-friendly description of the Checkout Session that may be shown to the customer during the checkout process.

Any payment created for the Checkout Session will use the same description.

redirectUrlstring required

The URL your customer will be redirected to after the payment process.

It could make sense for the redirectUrl to contain a unique identifier – like your order ID – so you can show the right page referencing the order when your customer returns.

requiredCustomerDetailsstring[]

🚧 Private beta

This property is currently in private beta, and the final specification may still change.

Declare which customer details should be collected during checkout. Mollie can collect these details for you with the Express Component and returns them on the Checkout Session's and payment's billingAddress and shippingAddress.

customerIdstring nullable

The ID of the customer the Checkout Session is being created for. This is used primarily for recurring payments, but can also be used on regular payments to enable single-click payments.

If sequenceType is set to first, this field is required.

sequenceTypestring

Only relevant for recurring payments.

Indicate if this Checkout Session is used for a one-off or a first of a recurring payment.

With a first payment, the customer agrees to automatic recurring charges taking place on their account in the future.

Defaults to oneoff, which is a regular non-recurring payment.

Possible values: oneoff first

metadataobject

Provide any data you like in a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB.

Any payment created for the Checkout Session will use the same metadata.

profileIdstring

The identifier referring to the profile this entity belongs to.

When using an API Key, the profileId must not be sent since it is linked to the key. However, for OAuth and Organization tokens, the profileId is required.

For more information, see Authentication.

testmodeboolean nullable

Whether to create the entity in test mode or live mode.

Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

createdAtstring

The entity's date and time of creation, in ISO 8601 format.

expiredAtstring nullable

The date and time the Checkout Session expired, in ISO 8601 format. Omitted if the Checkout Session has not expired.

completedAtstring nullable

The date and time the Checkout Session was completed, in ISO 8601 format. Omitted if the Checkout Session has not been completed.

Example request

{
  "id": "sess_82jFYDTrLcCQV68NLDvMJ",
  "mode": "live",
  "clientAccessToken": "ewogICJzZXNzaW9uVG9rZW4i...",
  "status": "open",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "description": "Order #12345",
  "lines": [
    {
      "type": "physical",
      "description": "LEGO 4440 Forest Police Station",
      "quantity": 1,
      "quantityUnit": "pcs",
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discountAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "totalAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "vatRate": "21.00",
      "vatAmount": {
        "currency": "EUR",
        "value": "10.00"
      },
      "sku": "9780241661628",
      "imageUrl": "https://...",
      "productUrl": "https://..."
    }
  ],
  "redirectUrl": "https://example.org/redirect",
  "requiredCustomerDetails": [
    "billing-address"
  ],
  "billingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "shippingAddress": {
    "title": "Mr.",
    "givenName": "Piet",
    "familyName": "Mondriaan",
    "organizationName": "Mollie B.V.",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "Apt. 1",
    "postalCode": "1234AB",
    "email": "piet@example.org",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL"
  },
  "shipping": {
    "options": [
      {
        "description": "Next day delivery",
        "reference": "express",
        "amount": {
          "currency": "EUR",
          "value": "10.00"
        }
      }
    ],
    "callbackUrl": "https://example.org/shipping-options"
  },
  "customerId": "cst_5B8cwPMGnU",
  "sequenceType": "oneoff",
  "payment": {
    "webhookUrl": "https://example.org/webhook"
  },
  "profileId": "pfl_5B8cwPMGnU",
  "createdAt": "2024-03-20T09:13:37+00:00",
  "expiredAt": "2024-03-20T10:13:37+00:00",
  "completedAt": "2024-03-20T11:13:37+00:00",
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Response

The newly created Checkout Session object.

resourcestring required