menu

Payment API

What's on this page

Online Payments / Payment Features / Mandates

Introduction

This page is intended as an introduction to mandates and as such offers a general overview on their purpose and on how to create and use them.

More payment method specific documentation, instructions and examples on how to create and use mandates, can be found in the documentation of each respective payment method that supports mandates.

Additionally, this page includes hyperlinks to the corresponding sections in the API Reference where applicable.

Mandates?

A mandate serves as an agreement between the merchant and the customer, wherein the customer authorises the merchant to charge them by initiating transactions on the customer’s behalf.

This allows for uses cases where, for example, a merchant periodically charges a customer for a subscription, using the earlier agreed upon mandate, without requiring any further interaction from the customer.

Payment methods offers an overview on which payment methods support mandates. Note that for the card method, mandates are currently not supported. Nonetheless, it is possible to perform card merchant initiated transactions without using mandates.

Creating mandates

We support two APIs for creating mandates:

Depending on the payment method, none, one or both of the APIs are supported for mandate creation.

Mandate API Payment API
Apple Pay ✓ ✓
iDEAL ✓
Google Pay ✓ ✓
PayPal ✓ ✓

The difference and the different use cases for each API will be described in more detail in the following sections. Furthermore, more details can be found in the documentation of each respective payment method.

In both cases, the outcome of creating a mandate will be a mandateId, which must be stored by the merchant as it identifies the mandate the customer agreed to. A future payment can be performed using an active mandate, by including the mandateId in the corresponding payment request.

Sequence info

Some payment methods require sequence info to be provided in the request when creating a mandate.

Required sequence info properties per payment method:

type source
Apple Pay ✓ * ✓
iDEAL N/A N/A
Google Pay ✓ * ✓
PayPal N/A N/A

* Depending on type, other properties may also be required.

Note that source indicates the source (i.e. MIT or CIT) that will be applicable when performing payments using the mandate. As a general guideline:

  • MIT covers use cases where the mandate is used to perform payments without an explicit action from the customer or without the customer being present.
  • CIT covers use cases where the mandate is used to perform payments following an explicit action from the customer or with the customer being present and potentially requiring SCA.

All initial transactions used to create or obtain a mandate are implicitly CIT transactions.

Mandate API

One approach to create a mandate is using our Mandate API. This approach is particularly useful for scenarios like recurring payment subscriptions where an initial payment is not required to set up the subscription contract.

The mandate request creates a mandate and an underlying method-specific child transaction for a card check or zero-amount sale that acts as a digital signature for the newly created mandate. Once the method-specific child transaction is successfully completed, the mandate becomes active.

In practice, this means that if for example our “hosted payment page” is being used, the mandate will be pending until the payment has been successfully completed using the signUrl from the create mandate request’s response.

The response to the mandate create request will contain a mandateId which - as mentioned previously - should be stored by the merchant for future use.

Note

  • If the validation does not complete successfully, the mandate becomes inactive.
  • Inactive mandates can no longer become active, meaning they cannot be used to perform any payments and a new mandate has to be created if desired.
  • Receiving a mandateId does not mean the mandate is active.

Payment API

An alternative approach, is to combine an initial payment with the creation of a mandate, using the obtainMandate request body parameter when creating a regular payment. This is particularly useful for scenarios like recurring payment subscriptions where an initial payment is required to set up the subscription contract.

As a result, a mandate will be created and the payment serves as its verification, meaning no further signing is required to activate the mandate as it becomes active when the payment is successfully completed.

In practice, this means that if for example our “hosted payment page” is being used, the mandate will be pending until the payment has been successfully completed using the payUrl from the payment request’s response.

Similar to using the Mandate API, be sure to store the mandateId returned in the response as it is required for future use.

Note

  • If the payment does not complete successfully, the mandate becomes inactive.
  • Inactive mandates can no longer become active, meaning they cannot be used to perform any payments and a new mandate has to be created if desired.
  • Receiving a mandateId does not mean the mandate is active.

Performing payments using mandates

Active mandates can be used with the Payment API to perform payments. This applies for mandates created using the Mandate API as well as for those created using the Payment API.

To perform a payment using an active mandate, include the mandate’s mandateId in the Payment API’s payment request. If applicable for the used payment method, the sequence info which was provided during mandate creation, will be used to process the payment.

Note

An active mandate is required. A pending or inactive mandate cannot be used to successfully complete a payment.

Example request (Apple Pay)

{
  "amount" : 10,
  "currency" : "EUR",
  "method" : "applepay",
  "language" : "NLD",
  "returnUrl": "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "mandateId": "MAN240705143106592CB87E193.0"
}

Example response (Apple Pay)

{
  "reference": "A240710131515045CB87E195.I",
  "method": "applepay",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1720610115051,
  "created": 1720610115051,
  "details": {
    "maskedPan": "5204XXXXXXXX6937",
    "mandateId": "MAN240705143106592CB87E193.0"
  },
  "returnUrl": "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "brand": "mastercard",
  "payUrl": "http://onlinepayments.ccv.eu/vpos/applepay/payment.html?reference=A240710131515045CB87E195.I",
  "paidout": "no",
  "status": "success",
  "amount": 10
}