Sign in
Checkout Sessions API

Create Checkout Session

🚧 Beta feature

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

Create a Checkout 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 Checkout Session. Use the client access token to initialize Mollie Components.

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

The Checkout Session's status.

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.

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 Checkout 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 Checkout 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 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

{
  "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 Checkout Session object.

Changes

Changed in 4 of the 79 revisions of this API.7

  • 916a533bff952See the full diff
    • ○

      api tag Checkout Sessions API added

      api-tag-added

    • ○

      api tag Sessions API removed

      api-tag-removed

  • e2ec10eb23632See the full diff
    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

      added the optional property //// to the response with the status

      response-optional-property-added

  • 7cab62b218301See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • ef4b5a97b56a2See the full diff
    • ○

      the endpoint scheme security advancedAccessToken was added to the API

      api-security-added

    • ○

      the endpoint scheme security organizationAccessToken was removed from the API

      api-security-removed

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 79 revisions, 9 have no diff computed.