Mollie Components

Mollie Components is a set of Javascript APIs that allow you to add the fields needed for credit card holder data to your own checkout, in a way that is fully PCI-DSS SAQ-A compliant.

https://assets.docs.mollie.com/_images/mollie-components-preview@2x.jpg

At a high level, it works by using a Javascript API to add fields to your checkout that your customer will use to enter their credit card details, such as their card number.

Mollie Components does not give you access to the card holder data. Instead, when the checkout is submitted, you use Mollie Components to exchange the card holder data for a cardToken which you can use with the Create Payment API or Create Order API.

Depending on various factors, the payment will either be completed immediately or you will get a _links.checkout URL where your customer can perform the 3-D Secure authentication. If the customer authenticates successfully, the payment is completed.

Implementation steps

Follow these steps to implement Mollie Components in your checkout:

https://assets.docs.mollie.com/_images/mollie-components-flow@2x.png
  1. Add the Mollie Components Javascript library to your checkout.
  2. Initialize the Mollie object.
  3. Create and mount the four Components for the four credit card fields (card holder, card number, expiry date and CVC). This will add the fields to your checkout.
  4. Add a submit event listener to your form to retrieve the cardToken when your customer has completed the checkout form.
  5. Send the cardToken to your back end, by adding it to your form.
  6. From your back end, create a credit card Payment or Order with the cardToken using the Create Payment API or Create Order API respectively.
  7. If required, redirect the shopper to the URL returned by our API for 3-D Secure authentication.

Mollie has created example implementations you can use to get started.

Add the Mollie Components Javascript library to your checkout

Start by including mollie.js in to your project. It should be added just before the </body> tag.

The Javascript file is located at https://js.mollie.com/v1/mollie.js.

1
2
3
4
5
6
7
8
 <html>
   <head>
     <title>My Checkout</title>
   </head>
   <body>
     <script src="https://js.mollie.com/v1/mollie.js"></script>
   </body>
 </html>

Note

If you are using Content Security Policy, you should whitelist the js.mollie.com domain. We recommend using a strict CSP on your checkout.

Initialize the Mollie object

First, you need the Profile Id of the profile that you want to use. This can be found on the Developers - API-keys page in the Dashboard or retrieved programmatically using the Get Current Profile API.

After the script has loaded you can use the Mollie(profileId[, options]) function. This will return an object that you can use for creating the four Components your customer will use to enter their card holder data.

1
var mollie = Mollie('pfl_3RkSN1zuPE', { locale: 'nl_NL', testmode: false });

Note

Be aware the Profile Id is not your API key. Your API key is private and should never be used in a browser context. The Profile Id starts with pfl_, where as API keys start with live_ or test_.

Create and mount the card holder data Components

After initializing the Mollie object, you should create the four card holder data Components using the mollie.createComponent(type[, options]) function and mount them in your checkout using the component.mount(targetElement) function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<form>
  <div id="card-holder"></div>
  <div id="card-holder-error"></div>

  <div id="card-number"></div>
  <div id="card-number-error"></div>

  <div id="expiry-date"></div>
  <div id="expiry-date-error"></div>

  <div id="verification-code"></div>
  <div id="verification-code-error"></div>

  <button type="button">Pay</button>
</form>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var cardHolder = mollie.createComponent('cardHolder');
cardHolder.mount('#card-holder');

var cardNumber = mollie.createComponent('cardNumber');
cardNumber.mount('#card-number');

var expiryDate = mollie.createComponent('expiryDate');
expiryDate.mount('#expiry-date');

var verificationCode = mollie.createComponent('verificationCode');
verificationCode.mount('#verification-code');

This will add the input fields to your checkout and make them visible for your customer. To add styling to the Components, see Styling Mollie Components.

Handling errors

Add a change event listener to each component to listen for errors. Displaying the error is up to you. The example below assumes an empty element in which the error can be rendered.

Errors will be localized according to the locale defined when initializing Mollie Components.

1
2
3
4
5
6
7
8
9
var cardNumberError = document.querySelector('#card-number-error');

cardNumber.addEventListener('change', event => {
  if (event.error && event.touched) {
    cardNumberError.textContent = event.error;
  } else {
    cardNumberError.textContent = '';
  }
});

Add a submit event listener to your form

Add a submit event listener to your form and use the mollie.createToken() function to get the token. You can then place the cardToken in a hidden input to submit it to your back end, for example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
form.addEventListener('submit', async e => {
  e.preventDefault();

  const { token, error } = await mollie.createToken();

  if (error) {
    // Something wrong happened while creating the token. Handle this situation gracefully.
    return;
  }

  // Add token to the form
  const tokenInput = document.createElement('input');
  tokenInput.setAttribute('type', 'hidden');
  tokenInput.setAttribute('name', 'cardToken');
  tokenInput.setAttribute('value', token);

  form.appendChild(tokenInput);

  // Submit form to the server
  form.submit();
});

Create a Payment or Order with the card token

On your back end, you will receive the cardToken. You need to pass this when creating a Payment. Additionally, you should set the method to creditcard.

Alternatively, you can use the Create Order API. and pass the card token via the payment.cardToken parameter.

The cardToken is valid for 1 hour.

Example

cURLPHPPythonRubyNode.js
1
2
3
4
5
6
7
8
9
curl -X POST https://api.mollie.com/v2/payments \
   -H "Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d "method=creditcard" \
   -d "amount[currency]=EUR" \
   -d "amount[value]=10.00" \
   -d "description=Order #12345" \
   -d "redirectUrl=https://webshop.example.org/order/12345/" \
   -d "webhookUrl=https://webshop.example.org/payments/webhook/" \
   -d "cardToken=tkn_UqAvArS3gw"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");
$payment = $mollie->payments->create([
      "method" => "creditcard",
      "amount" => [
            "currency" => "EUR",
            "value" => "10.00"
      ],
      "description" => "Order #12345",
      "redirectUrl" => "https://webshop.example.org/order/12345/",
      "webhookUrl" => "https://webshop.example.org/payments/webhook/",
      "cardToken" => "tkn_UqAvArS3gw",
]);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_api_key('live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM')
payment = mollie_client.payments.create({
   'method': 'creditcard',
   'amount': {
         'currency': 'EUR',
         'value': '10.00'
   },
   'description': 'Order #12345',
   'webhookUrl': 'https://webshop.example.org/order/12345/',
   'redirectUrl': 'https://webshop.example.org/payments/webhook/',
   'cardToken': 'tkn_UqAvArS3gw'
})
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'
end

payment = Mollie::Payment.create(
  method: 'creditcard',
  amount: {
    currency: 'EUR',
    value: '10.00'
  },
  description: 'Order #12345',
  redirect_url: 'https://webshop.example.org/order/12345/',
  webhook_url: 'https://webshop.example.org/payments/webhook/',
  card_token: 'tkn_UqAvArS3gw'
)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

(async () => {
  const payment = await mollieClient.payments.create({
    method: 'creditcard',
    amount: {
      currency: 'EUR',
      value: '10.00', // We enforce the correct number of decimals through strings
    },
    description: 'Order #12345',
    redirectUrl: 'https://webshop.example.org/order/12345/',
    webhookUrl: 'https://webshop.example.org/payments/webhook/',
    cardToken: 'tkn_UqAvArS3gw'
  });
})();

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "resource": "payment",
    "id": "tr_7UhSN1zuXS",
    "mode": "test",
    "createdAt": "2018-03-20T09:13:37+00:00",
    "amount": {
        "value": "10.00",
        "currency": "EUR"
    },
    "description": "Order #12345",
    "method": null,
    "metadata": {
        "order_id": "12345"
    },
    "status": "open",
    "isCancelable": false,
    "expiresAt": "2018-03-20T09:28:37+00:00",
    "profileId": "pfl_3RkSN1zuPE",
    "sequenceType": "oneoff",
    "details": {
       "cardToken": "tkn_UqAvArS3gw"
    },
    "redirectUrl": "https://webshop.example.org/order/12345/",
    "webhookUrl": "https://webshop.example.org/payments/webhook/",
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/payments/tr_7UhSN1zuXS",
            "type": "application/json"
        },
        "checkout": {
            "href": "https://pay.mollie.com/authenticate/b47ef2ce1d3bea2ddadf3895080d1d4c",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/payments-api/create-payment",
            "type": "text/html"
        }
    }
}

Make sure you use the API key that belongs to the same profile you used when initializing the Mollie object.

It is possible an error occurs when creating the payment. See Handling errors with Mollie Components on what to do in such cases.

Redirect the shopper to the 3-D Secure authentication page

In most cases, your payment will not be completed immediately but will first require a 3-D Secure authentication by your customer. You should redirect your customer to the _links.checkout URL returned by the Create Payment API or Create Order API. Your customer can then authenticate him / herself with the card issuer.

1
2
3
4
HTTP/1.1 303 See Other
Date: Mon, 27 Jul 2019 12:28:53 GMT
Location: https://pay.mollie.com/authenticate/b47ef2ce1d3bea2ddadf3895080d1d4c
Connection: Closed

It is possible an error occurs during or after 3-D Secure authentication. See Handling errors with Mollie Components on how to handle these cases.

Browser support

Mollie Components supports the current and previous major release of the following browsers:

  • Chrome
  • Chrome for Android
  • Safari
  • Safari iOS
  • Opera
  • Firefox
  • Edge

The latest release of Microsoft Internet Explorer 11 is supported as well.

If you need to support older browsers, you cannot use Mollie Components.