Save a card for faster checkout

Overview

Saved Cards (also known as card-on-file) allow your returning customers to pay with a previously stored credit/debit card, streamlining the checkout process and increasing checkout conversion. This guide explains how to implement this feature using Mollie Components and our Payments API. For users of the Mollie Hosted Checkout, more informations on one-click cards can be found here.

🚧

This guide is for one-off purchase, customer-present support. For guidance on storing cards for subscriptions and customer-not-present merchant initiated transactions refer to our recurring payments guide.

The process involves four main steps:

1. Recording consent: securely asking your customer for permission to save their card details.
2. Saving the card: creating the first payment while flagging the card to be saved against a Mollie Customer profile.
3. Displaying saved cards: showing the stored cards to a returning customer for selection.
4. Paying with a saved card: Processing a new payment using the selected card.

Additional steps:

• Deleting/removing a saved card

Prerequisites

Before you begin, ensure you have:

• A working Mollie account
• A server-side integration that can communicate with the Mollie API
• A customer account system on your website or application
• Mollie Components implemented for new card entry

Step 1: Record customer consent

To comply with payment regulations (like PSD2) and build trust, you must get explicit consent from your customer before saving their card details.

1.1 Implement Mollie Components

First, ensure you have a standard Mollie Components implementation. Your HTML should contain the mount points for the card form.

1.2 Add a consent option

Below the card form, add a customer choice option, such as a checkbox. The accompanying text must clearly state that you will save their card details for future payments.

You are only allowed to save the card if the customer actively selects this option. It is recommended you keep a record of the timestamp of this consent on the order.

Recommended text to display to the customer (table of translations available below):

• Main text - Save your card for faster checkout.
• Sub text - By ticking this box, you authorise [Doing Business As Name] to securely store your payment card details to speed up future checkouts. Your details will be held by Mollie B.V. on our behalf. Your saved card will only be charged when you actively successfully complete a purchase at checkout - we will never charge your card without your direct involvement. You can remove your saved card at any time via your account settings or by contacting us at [support contact]. For further information, please see our [Privacy Policy].

Disclaimer: This text is provided as guidance only and does not constitute legal advice.

When your form is submitted, check if this box was selected. You will pass this choice to your server along with the card token.

Step 2: Save the card details

Saving card details happens when you create the first payment using the new card - only upon payment success.

Preliminary: Create a Mollie Customer

A saved card must be linked to a Customer object in Mollie. If the shopper is new or does not have a Mollie Customer ID associated with their account in your system, you must first create one. Else use the one which already exists.

Store the returned Mollie Customer ID (e.g. cst_hfiaeofko) in your database, linking it to the customer's account in your system. You will need this for all future interactions.

Create the first payment

After the customer submits the form, use mollie.createToken() to get a cardToken. Send this token and the customer's choice to save the card.

On your server, create a payment using the v2/payments endpoint. If the customer consented to saving their card, include two crucial parameters in your API call:

• customerId - the ID of the Mollie Customer the card will be saved to.
• storeCredentials - a boolean set to true.

The payload will look like this:

// POST /v2/payments
{
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "description": "Order #12345",
  "method": "creditcard",
  "customerId": "cst_hfiaeofko",
  "storeCredentials": true,
  "cardToken": "tkn_5aGAdtL2aD",
  "redirectUrl": "https://webshop.example.org/order/12345/",
  "webhookUrl": "https://webshop.example.org/payments/webhook/",
  "metadata": {
    "order_id": "12345"
  }
}

Once this payment is successfully processed (i.e. its status becomes paid or authorised), a Mandate object is automatically created and linked to the Customer. This mandate represents the saved card and the customer's permission to use it.

Reminder: Your system must store the mapping between your internal customer ID and the Mollie customerId in a secure way. This is essential for retrieving the saved cards for returning customers.

Step 3: Display saved cards to the returning customer

When a known customer returns to your checkout page, you can offer them the convenience of paying with their saved card.

1. Authenticate the customer: First, ensure the customer is logged into their account on your website.
2. Retrieve their Mollie Customer ID: Look up the customerId you stored in your database for this customer.
3. Fetch the saved cards (mandates): Use the List customer mandates endpoint to get a list of all valid mandates for that customer. To ensure you only show cards that the customer agreed to use while present at checkout, you must include the scopes[]=customer-present query parameter. This parameter ensures that you only retrieve mandate which can be used in the presence of the customer (aka Customer Initiated Transactions (CIT))

GET /v2/customers/{customerId}/mandates?scopes[]=customer-present

The response will contain an array of Mandate objects. Each valid mandate will include non-sensitive card details you can use to display the card to your customer, such as:

• details.cardHolder
• details.cardNumberLast4
• details.cardExpiryDate
• details.cardLabel (e.g., "Visa")
• id (the mandateId, e.g. mdt_hdkofdfh)

You can now render these cards as selectable options in your checkout flow.

Step 4: Process a payment on a saved card

Once the customer selects one of their saved cards, you are ready to create the payment.

On your server, make a call to the v2/payments endpoint with the following parameters:

• customerId: The customer's Mollie ID.
• mandateId: The ID of the mandate corresponding to the card they selected.
• sequenceType: Must be set to "oneoff" to indicate this is a customer-initiated transaction.

// POST /v2/payments
{
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "description": "Order #12345",
  "method": "creditcard",
  "customerId": "cst_diofsdfh",
  "mandateId": "mdt_hdkofdfh",
  "sequenceType": "oneoff",
  "redirectUrl": "https://webshop.example.org/order/12345/",
  "webhookUrl": "https://webshop.example.org/payments/webhook/",
  "metadata": {
    "order_id": "12345"
  }
}

Mollie will process this payment. In most cases, the payment will be required to redirect the customer to the authentication page to collect the necessary data to determine if the Strong Customer Authentication (SCA) should apply. In which case you should handle the redirect to the _links.checkout.href URL as you would with any other card payment with a new card.

The rest of the payment flow, including handling redirects and webhooks, remains the same.

How to remove a card

Giving your customers control over their data is a key part of building trust and complying with regulations like PSD2. You must provide a simple way for customers to remove a card they have previously saved.

A saved card is represented by a Mandate. To "remove" a card, you need to cancel this mandate, which revokes the permission to charge it in the future.

The process involves two main parts: the user interface in your customer's account area and the backend API call to Mollie.

Step 1: Create a card management interface

In your customer's account or profile section, create a page titled "Payment Methods" or "Saved Cards".

On this page, list all the customer's currently active cards. You retrieve this list using the same method described in Step 3: Display saved cards to the returning customer.

For each card listed, provide a clear "Remove" or "Delete" button.

Step 2: Cancel the Mandate via the API

When a customer clicks the "Remove" button, your frontend should send a request to your server, including the mandateId of the card to be removed.

Your server then makes a DELETE request to the Cancel mandate endpoint at Mollie. This call permanently revokes the mandate, making it invalid for any future payments.

Note: The API call requires both the customerId and the mandateId.

DELETE /v2/customers/{customerId}/mandates/{mandateId}

Step 3: Handle the response

If the cancellation is successful, Mollie will respond with an HTTP 204 No Content status and an empty body.

Upon receiving this confirmation, you should:

• Update your user interface to remove the card from the list.
• Optionally, display a success message like "Card ending in 1234 has been removed."
• Once a mandate is canceled, it will no longer be returned when you LIST the customer's mandates, and any attempt to create a payment with it will fail. The card is now effectively removed from the customer's profile. This action is irreversible.

Your compliance check list

Summary checklist for a compliant consent case:

• Display an unchecked checkbox separate from the main "Pay" button and a distinct link to terms of service and privacy policy.
• Use clear, simple language explaining that the card will be saved for future use.
• Only display the saved cards to the same customer that saved the card(s)
• Provide a user account section where the customer can view and delete their saved cards at any time.
• Consent record is logged with timestamp and version at point of customer agreement (GDPR Art. 7)

Translations for consent text

❗️

Disclaimer: This text is provided as guidance. It does not constitute legal advice.

Quick Reference - Variable Fields Per Locale