Recurring payments (MIT)
PSD2 applies strong customer authentication (SCA) to all customer-initiated transactions (CIT). For these transactions, the cardholder is on session on the website or app to authenticate the transaction via the 3DS2 protocol. This protocol is handled by the
SecureMode parameter on the MANGOPAY API.
Merchant-initiated transactions (MIT) are out of scope of PSD2. For these transactions, the merchant makes the payment request in the absence of the cardholder (the user is off session). These MITs are not authenticated individually, but must be linked by MANGOPAY to a previously authorised CIT.
Please note, the first version of this feature will be available in the sandbox in June. Further details of the feature will follow in May.
This feature concerns recurring card payments made with a registered card, similar to a Card Direct PayIn. Recurring payments with an unregistered card (similar to a Card Web PayIn) are not possible. For Direct Debits, see the Mandate object.
The recurring payment feature is designed to address, in full compliance with PSD2, all your needs for subscriptions, payments in installments, and other flexible MIT payments.
The first version of this feature will not include pre-authorized card payments, but these will be included in a future version.
This feature allows you to create recurring card payments which are comprised of:
- an initial transaction in the presence of the cardholder, which will be authenticated (CIT)
- subsequent transactions made in the absence of the cardholder, initiated by you (MIT)
The Recurring PayIn Registration object allows you to transmit all information relating to a recurring payment.
Once created, the Recurring PayIn endpoint enables you to request pay-ins linked to this registration object. The first payment (CIT) will be authenticated by the cardholder. This authorisation is necessary to request subsequent payments made in the absence of the cardholder (MIT).
Register a recurring payment
- POST /recurringpayinregistrations
This endpoint allows you to create the Recurring PayIn Registration object which contains all the information relevant to the recurrence.
This object contains the amount of the first transaction. You can replicate this amount on subsequent transactions, such as for fixed subscriptions or installments, or update it using the pay-in endpoint. The same is true for the amount of fees on each transaction.
You are also able to specify aspects of the recurrence:
Frequency- daily, weekly, twice a month, once a month, once every two months etc.
FixedNextAmount- a boolean determining if the amount of subsequent payments are likely to change
FractionedPayment- a boolean determining if this is a payment in installments
We recommend that you provide as much information as possible regarding the recurrence. All transactional data provided is taken into account by the issuing bank (the cardholder’s bank) to determine whether or not to accept a payment request.
- PUT /recurringpayinregistrations
This endpoint allows you to modify the information in the registration object. In the first version, you will be able to modify: the card, the billing address, and the shipping address. Any modification entails a CIT (the cardholder must authenticate). This endpoint can also be used to set the status to ENDED to prevent further use of the object.
- GET /recurringpayinregistrations
This endpoint allows you to obtain information on the registration object and the recurring payments (number of payments made with and for what amount).
Request a recurring pay-in
- POST /payins/recurring/card/direct
This endpoint allows you to request a recurring payment which contains a
RecurringPayinRegistrationId, linking it to the information contained in the registration endpoint.
The same endpoint is used to request both CIT or MIT payments. The difference is in the information supplied in the recurring pay-in request.
Requesting a CIT
As the user is on session during a CIT, the following parameters are necessary for authentication via the 3DS2 protocol:
These parameters are the same as for a single-charge payment under 3DS2.
Requesting an MIT
As the user is off session during an MIT, there is no authentication phase. The
RecurringPayinRegistrationId links an MIT to a previously authorised CIT.
For both CIT and MIT requests, you are also able to send the optional parameters
Initiate a new recurring payment flow
- The end user requests a recurring payment
- You create the registration object (POST /recurringpayinregistrations)
- Our API returns a
- You request a CIT (POST /payins/recurring/card/direct)
- The end user authenticates via the 3DS protocol
- The issuing bank (the cardholder’s bank) authorises the transaction
- The recurring payment is in progress
- The time period indicated in the frequency passes
- You request an MIT (POST /payins/recurring/card/direct)
Migrate an existing recurring payment
This feature may be used to register and continue existing recurring payments. The success of these migrations depends on the issuing bank accepting the information presented during the first MIT. Once an initial MIT has been authorised, subsequent payments will be accepted in the same way as following a CIT.
- You create the registration object (POST /recurringpayinregistrations) using payment details from an existing recurring payment (user, wallet, card, etc). You set the
Migrationparameter to TRUE.
- Our API returns a
- You request an MIT (POST /payins/recurring/card/direct) in the absence of the cardholder
At this point, it is up to the issuing bank to decide whether it accepts the MIT request based on all the information presented. There are two possibilities:
- The issuing bank accepts the transaction request. In this case,
Migrationremains TRUE and the registration object status changes to IN PROGRESS. You can continue requesting MITs using the
- The issuing bank refuses the transaction request. In this case,
Migrationchanges to FALSE and the registration object status changes to AUTHENTICATION NEEDED. You will be obliged to notify the end user that they need to authenticate a CIT. With the end user on session, you can request a CIT with the
RecurringPayinRegistrationIdto restart the recurrence.