Mollie Components

Warning

Mollie Components is currently in a closed beta. If you are interested in participating, reach out to your account manager.

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.

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@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.

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
9
 <html>
   <head>
     <title>My Checkout</title>
   </head>
   <body>
     <!-- Your HTML  --->
     <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' });

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

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
form.addEventListener('submit', async e => {
  e.preventDefault();

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

  // Add token to the form
  const tokenInput = document.getElementById("cardToken");
  tokenInput.value = token;

  // Re-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.

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
43
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",
    "details": null,
    "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/processing/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.

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.

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