Recurring payments (MIT)

Introduction

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.

Scope

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.

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)
  
  

Endpoints

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:

• EndDate
• 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:

• IpAddress
• BrowserInfo
• SecureModeReturnURL

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 Tag and StatementDescriptor.

Workflows

Initiate a new recurring payment flow

1. The end user requests a recurring payment
2. You create the registration object (POST /recurringpayinregistrations)
3. Our API returns a RecurringPayinRegistrationId
4. You request a CIT (POST /payins/recurring/card/direct)
5. The end user authenticates via the 3DS protocol
6. The issuing bank (the cardholder’s bank) authorises the transaction
7. The recurring payment is in progress
8. The time period indicated in the frequency passes
9. 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.

1. You create the registration object (POST /recurringpayinregistrations) using payment details from an existing recurring payment (user, wallet, card, etc). You set the Migration parameter to TRUE.
2. Our API returns a RecurringPayinRegistrationId
3. 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:

1. The issuing bank accepts the transaction request. In this case, Migration remains TRUE and the registration object status changes to IN PROGRESS. You can continue requesting MITs using the RecurringPayinRegistrationId.
2. The issuing bank refuses the transaction request. In this case, Migration changes 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 RecurringPayinRegistrationId to restart the recurrence.