v55

latestOpenAPI 3.1.0CC-BY-NC-SA-4.0raw.githubusercontent.com2026-08-011243791.8 MB

Sessions API

Create session

🚧 Beta feature

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

Create a session to start a checkout process with Mollie Components.

post/v2/sessions

Headers

idempotency-keystring

Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

resourcestring

The resource type of the object.

idstring

mode'live' | 'test'

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

clientAccessTokenstring

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

status'open' | 'completed' | 'expired'

The session's status.

descriptionstring required

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

Any payment created for the 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.

requiredCustomerDetailsSessionRequiredCustomerDetails[]

🚧 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 session's and payment's billingAddress and shippingAddress.

customerIdstring

sequenceType'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 session will use the same metadata.

profileIdstring

The identifier referring to the profile this entity belongs to.

Most API credentials are linked to a single profile. In these cases the profileId can be omitted in the creation request. For organization-level credentials such as OAuth access tokens however, the profileId parameter is required.

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 session expired, in ISO 8601 format. Omitted if the session has not expired.

completedAtstring nullable

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

Example request

{
  "resource": "session",
  "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"
  },
  "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 session object.