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/components-preview@2x.jpg

At a high level, it works by using a Javascript API, dubbed Mollie.js, 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 or Create order endpoints.

Once you have created a payment or order, you should redirect your customer to the URL in the _links.checkout property from the response. This link is 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/components-flow@2x.png
  1. Add Mollie.js 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 endpoint or Create order endpoint respectively.
  7. 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 Mollie.js to your checkout

Start by including Mollie.js into 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 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 endpoint.

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 Mollie Components

After initialising the Mollie object, you can start to consume the shopper’s data. There are two ways to do this:

  1. Use the card component to implement our out-of-the-box solution.
  2. Use Mollie Components to build your own solution that covers your specific use cases.

Option 1: Card component

The card component is a collection of all mandatory fields needed to create an embedded card form. With this component, you can abstract your implementation from the DOM. This makes it easier to implement while covering most use cases. You can create the card component using the mollie.createComponent(type[, options]) and mount it in your checkout using the component.mount(targetElement).

1
2
3
<form>
  <div id="card"></div>
</form>

1
2
var cardComponent = mollie.createComponent('card');
cardComponent.mount('#card');

Translated error messages will be rendered within the DOM automatically.

To customize the card component, see mollie.createComponent(type[, options]).

To add styling to the card component, see Styling.

Option 2: Mollie Components

Mollie Components are individual mandatory components out of which you can create a card form. You can create them using the mollie.createComponent(type[, options]) and mount them in your checkout using the component.mount(targetElement). This will add the input fields to your checkout and make them visible to your customer.

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

  <div id="card-holder"></div>
  <div id="card-holder-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 cardNumber = mollie.createComponent('cardNumber');
cardNumber.mount('#card-number');

var cardHolder = mollie.createComponent('cardHolder');
cardHolder.mount('#card-holder');

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

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

To add styling to the Mollie Components, see Styling.

To handle errors in Mollie Components you have to 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();

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

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

  // Add token to the form
  var 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, when using the Orders API, you can 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',
   '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
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
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

const payment = await mollieClient.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'
});

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 for what to do in such cases.

Redirect the shopper to the 3-D Secure authentication page

You should redirect your customer to the _links.checkout URL returned by the Create payment endpoint or the Create order endpoint. Your customer can then authenticate themselves with the card issuer.

It is possible an error occurs during or after 3-D Secure authentication. See Handling errors for more information 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.