v1

latestOpenAPI 3.1.0CC-BY-NC-SA-4.02026-07-2413803.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.

🔑 Access with

API key

Advanced access token with sessions.write

OAuth access with sessions.write

post/sessions

Request body

resourcestring

The resource type of the object.

idstring

The identifier uniquely referring to this session. Mollie assigns this identifier at session creation time. Mollie will always refer to the 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 session. Use the client access token to initialize Mollie Components.

statusstring

The session's status.

Possible values: open completed expired

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.

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

customerIdstring nullable

The ID of the customer the 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 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 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 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

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