Custom checkout with Components (Beta)

Mollie Components is a suite of pre-built UI components you can embed in your own checkout to accept payments. The components are designed to remove friction for your customer and improving conversion. More complex interactions are supported out of the box making it easy to build a custom checkout page.

How it works

Mollie Components is a Javascript SDK that mounts UI elements to your checkout page. It is powered by the Sessions API that facilitates the checkout process of your customer and handles payment creation.

---
config:
  theme: 'neutral'
  themeVariables:
    darkMode: true
    fontFamily: 'Inter'
    fontSize: '10px'
    primaryColor: '#aaa'
    primaryTextColor: '#000'
    primaryBorderColor: '#aaa'
    noteBkgColor: '#ddd'
    noteTextColor: '#333'
    signalColor: '#aaa'
    signalTextColor: '#888'
---

sequenceDiagram
    participant Client
    participant Server
    participant Mollie

    Client->>+Server: Request new Session
    Server->>+Mollie: POST v2/sessions
    Server->>+Client: Return Client Access Token

    Note over Client: Initialize Mollie.JS
    Note over Client: Create Checkout object
    Note over Client: Create and mount Component
		Note over Client: Customer completes the payment

    Note over Client: Redirects to result page

    Client->>+Server: Request Sessions status
    Server->>+Mollie: GET v2/sessions/{id}
    Server->>+Client: Return Session Status

    Note over Client: Show result

    Mollie-->>Server: Payment Webhook

1. When your customer is ready to checkout, you request a new Session from your server.
2. Your server calls the Sessions API to create a new Session providing information such as amount, line items and a redirect URL.
3. You send the Client Access Token from the Session to your front-end.
4. In your front-end you initialize Mollie JS and mount a component.
5. Your customer interacts with the component and completes the payment.
6. The shopper is redirected upon completion.
7. From your result page you request the status of the Session from your server.
8. Your server calls the Sessions API to retrieve the Session.
9. You return the status of the Session and show the outcome to your customer.
10. Mollie will send a webhook for the Payment which can trigger fulfillment.

Create a Checkout Session from your Server

The Session represents your customer's flow through the checkout process. It communicates with Mollie Components to facilitate a smooth and secure checkout process. It is recommended to create a new Session for every checkout attempt of your customer.

To create a Session make a request to the Sessions API. Include the following required fields in your request. See the Create Session reference for all properties.

🚧

Always make sure to calculate and set the amount from your server to prevent tampering from the client side.

curl -X POST https://api.mollie.com/v2/sessions \
    -H "Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
    -d "amount[currency]=EUR" \
    -d "amount[value]=10.00" \
    -d "description=Order #12345" \
    -d "lines[0][description]=T-Shirt" \
    -d "lines[0][quantity]=1" \
    -d "lines[0][unitPrice][value]=10.00" \
    -d "lines[0][unitPrice][currency]=EUR" \
    -d "lines[0][totalAmount][value]=10.00" \
    -d "lines[0][totalAmount][currency]=EUR"\
    -d "redirectUrl=https://webshop.example.org/order/12345/" \
    -d "metadata={\"order_id\": \"12345\"}"

The created Session will include a clientAccessToken that is needed to initialize Mollie Components. Make sure to send this token to your front-end.

👍

You may need to trigger fulfilment based on the status of the payment. Set the payment.webhookUrl property to ensure you receive status updates via a webhook.

Add a Component to your checkout page

Mollie Components is a Javascript SDK that allows you to embed UI elements into your checkout page. There are several components available that can be initialized using the same Session. Mollie Components will handle all the interactions with your shopper like collecting card details or showing interfaces for express payment methods. Depending on the payment method it may redirect the customer to complete the payment.

Prepare your front-end

Start by including Mollie.js on your checkout page.

<script src="https://js.mollie.com/v2/mollie.js"></script>

📘

If you need both v1 and v2 of Mollie.JS you can load v2 in compatibility mode to prevent namespace conflicts: https://js.mollie.com/v2/mollie.js?compatible.

On your checkout page add an DOM element where the component will be mounted.

<div id="mollie-component"></div>

Create a Checkout object

The Checkout object is the client side representation of your customer's checkout session. It can be used to create new components or setup event listeners.

To create a Checkout object you will need the clientAccessToken from the Session. This ensures the client side component can communicate with Mollie. Additional options like locale can be passed as well.

const checkout = Mollie.Checkout(clientAccessToken, { locale: 'en-US' })

📘

Compatibility mode

If you have loaded Mollie.js in compatibility mode, you can initialize by calling Mollie2.Checkout(clientToken, options?)

checkout.on('submit', (event) => {
  event.defer()
  try {
    await reserveStock()
    event.resolve()
  } catch(err) {
    event.reject()
  }
})

Create and mount a Component

Mollie offers several components for different use cases. With the Checkout object a component can be created and mounted to your DOM. It is possible to create multiple components with a single Checkout object.

A component that renders a list of available payment methods the customer can choose from. For payment methods that require additional information, such as cards, the component will automatically show the correct input fields.

The Methods Component currently supports the following payment methods: bancomatpay, bancontact, belfius, blik, creditcard, eps, ideal, mbway, multibanco, mybank, paypal, paysafecard, satispay, swish, twint.

JavaScript

const methodsComponent = checkout.create('methods-component')
methodsComponent.mount(document.getElementById('mollie-component'))

Handle the result

Mollie Components will facilitate the entire payment process. Once all information is available to process the payment, a new Payment will be created automatically from the Session. When the process is completed you show the outcome to the customer and trigger any fulfilment logic.

Show the result to your customer

When your customer has completed the payment they will be redirected to the redirectUrl you provided on the Session. From your server you can call the Sessions API to retrieve it's status which you can use to inform your customer of the outcome.

The Session can have one of the following states:

Triggering fulfilment

Fulfilment can be triggered asynchronously based on the webhook of the Payment. You will receive this webhook if you provided a payment.webhookUrl on the Session. Use this webhook to determine the status of the Payment and execute your fulfilment process.

📘

Any provided metadata on the Session will also be available on the Payment. You can use this to link the Payment to the order in your system.

Limitations

Mollie Components is still being developed and new features are added constantly. Currently known limitations include:

• Limited payment method support, see the Create and mount a Component section.
• The appearance of the components cannot be customized.
• The Express Component does not support collection of shipping details.
• Test-mode support is limited.