---
title: "Create session"
method: POST
path: "/sessions"
tags: ["Sessions API"]
---

# Create session

`POST /sessions`

> 🚧 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](/reference/authentication)
>
> [Advanced access token with **sessions.write**](/reference/authentication)
>
> [OAuth access with **sessions.write**](/reference/authentication)

## Request body

- object
  - `resource` string — The resource type of the object.
  - `id` string — 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`.
  - `mode` string — Whether this entity was created in live mode or in test mode. Possible values: `live` `test`
  - `clientAccessToken` string — The client access token for the session. Use the client access token to initialize Mollie Components.
  - `status` string — The session's status. Possible values: `open` `completed` `expired`
  - `amount` object, required — In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.
    - `currency` string, required — A three-character ISO 4217 currency code.
    - `value` string, required — A string containing an exact monetary amount in the given currency.
  - `description` string, 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.
  - `lines` object[], required — List of items the customer will pay for in this session. The sum of all line items must equal the session's amount. All lines must have the same currency as the session.
    - `type` string — The type of product purchased. For example, a physical or a digital product. The `tip` payment line type is not available when creating a payment. Possible values: `physical` `digital` `shipping_fee` `discount` `store_credit` `gift_card` `surcharge` `tip` (default: `physical`)
    - `description` string, required — A description of the line item. For example *LEGO 4440 Forest Police Station*.
    - `quantity` integer, required — The number of items.
    - `quantityUnit` string — The unit for the quantity. For example *pcs*, *kg*, or *cm*.
    - `unitPrice` object, required — The price of a single item including VAT. For example: `{"currency":"EUR", "value":"89.00"}` if the box of LEGO costs €89.00 each. For types `discount`, `store_credit`, and `gift_card`, the unit price must be negative. The unit price can be zero in case of free items.
      - `currency` string, required — A three-character ISO 4217 currency code.
      - `value` string, required — A string containing an exact monetary amount in the given currency.
    - `discountAmount` object — Any line-specific discounts, as a positive amount. Not relevant if the line itself is already a discount type.
      - `currency` string, required — A three-character ISO 4217 currency code.
      - `value` string, required — A string containing an exact monetary amount in the given currency.
    - `totalAmount` object, required — The total amount of the line, including VAT and discounts. Should match the following formula: `(unitPrice × quantity) - discountAmount`. The sum of all `totalAmount` values of all order lines should be equal to the full payment amount.
      - `currency` string, required — A three-character ISO 4217 currency code.
      - `value` string, required — A string containing an exact monetary amount in the given currency.
    - `vatRate` string — The VAT rate applied to the line, for example `21.00` for 21%. The vatRate should be passed as a string and not as a float, to ensure the correct number of decimals are passed.
    - `vatAmount` object — The amount of value-added tax on the line. The `totalAmount` field includes VAT, so the `vatAmount` can be calculated with the formula `totalAmount × (vatRate / (100 + vatRate))`. Any deviations from this will result in an error. For example, for a `totalAmount` of SEK 100.00 with a 25.00% VAT rate, we expect a VAT amount of `SEK 100.00 × (25 / 125) = SEK 20.00`.
      - `currency` string, required — A three-character ISO 4217 currency code.
      - `value` string, required — A string containing an exact monetary amount in the given currency.
    - `sku` string — The SKU, EAN, ISBN or UPC of the product sold.
    - `imageUrl` string — A link pointing to an image of the product sold.
    - `productUrl` string — A link pointing to the product page in your web shop of the product sold.
  - `redirectUrl` string, 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.
  - `requiredCustomerDetails` string[] — > 🚧 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`.
  - `billingAddress` object — The customer's billing address details. We advise to provide these details to improve fraud protection and conversion.
    - `title` string — The title of the person, for example *Mr.* or *Mrs.*.
    - `givenName` string — The given name (first name) of the person should be at least two characters and cannot contain only numbers. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `familyName` string — The given family name (surname) of the person should be at least two characters and cannot contain only numbers. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `organizationName` string — The name of the organization, in case the addressee is an organization.
    - `streetAndNumber` string — A street and street number. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `streetAdditional` string — Any additional addressing details, for example an apartment number.
    - `postalCode` string — A postal code. This field may be required if the provided country has a postal code system. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `email` string — A valid e-mail address. If you provide the email address for a `banktransfer` payment, we will automatically send the instructions email upon payment creation. The language of the email will follow the locale parameter of the payment. Required for payment methods `billie`, `in3`, `klarna` and `riverty`. If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    - `phone` string — If provided, it must be in the [E.164](https://en.wikipedia.org/wiki/E.164) format. For example: +31208202070.
    - `city` string — A city name. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `region` string — The top-level administrative subdivision of the country. For example: Noord-Holland.
    - `country` string — A country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
  - `shippingAddress` object — The customer's shipping address details. We advise to provide these details to improve fraud protection and conversion.
    - `title` string — The title of the person, for example *Mr.* or *Mrs.*.
    - `givenName` string — The given name (first name) of the person should be at least two characters and cannot contain only numbers. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `familyName` string — The given family name (surname) of the person should be at least two characters and cannot contain only numbers. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `organizationName` string — The name of the organization, in case the addressee is an organization.
    - `streetAndNumber` string — A street and street number. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `streetAdditional` string — Any additional addressing details, for example an apartment number.
    - `postalCode` string — A postal code. This field may be required if the provided country has a postal code system. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `email` string — A valid e-mail address. If you provide the email address for a `banktransfer` payment, we will automatically send the instructions email upon payment creation. The language of the email will follow the locale parameter of the payment. Required for payment methods `billie`, `in3`, `klarna` and `riverty`. If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    - `phone` string — If provided, it must be in the [E.164](https://en.wikipedia.org/wiki/E.164) format. For example: +31208202070.
    - `city` string — A city name. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
    - `region` string — The top-level administrative subdivision of the country. For example: Noord-Holland.
    - `country` string — A country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
  - `customerId` string, nullable — The ID of the [customer](get-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.
  - `sequenceType` string — **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`
  - `metadata` object — 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.
  - `payment` object
    - `webhookUrl` string — The webhook URL where we will send payment status updates to. This URL will be automatically set as the webhook URL for all payments created for this session.
  - `profileId` string — The identifier referring to the [profile](get-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](authentication).
  - `testmode` boolean, 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`.
  - `createdAt` string — The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `expiredAt` string, nullable — The date and time the session expired, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Omitted if the session has not expired.
  - `completedAt` string, nullable — The date and time the session was completed, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Omitted if the session has not been completed.
  - `_links` object — An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
    - `self` object, required — In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required — The actual URL string.
      - `type` string, required — The content type of the page or endpoint the URL points to.

## Response `201`

The newly created session object.

## Other responses

- `422` — The request contains issues.
- `429` — Rate Limit has been reached.

---

[API](https://skmtc.net/mollie/apis/accepting-payments.md) · [All operations](https://skmtc.net/mollie/apis/accepting-payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mollie/accepting-payments/revisions/4b45df3039ef/schema)