Integration
The Recurring PayIn Registration object allows you to transmit all information relating to a recurring payment, such as the frequency, the registered card, the start date, the end date and the amounts.
Once created, the Recurring PayIn endpoint enables you to request payIns linked to this registration object. The first payment (CIT) will necessarily be authenticated by the cardholder via the 3DS protocol. A successfully authenticated translation is necessary to enable subsequent payments (MIT) executed in the absence of the cardholder.
You can use the Recurring PayIn endpoint to request both CIT and MIT payments, with a difference in the information supplied.
Endpoints
- 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
FixedNextAmount
– a boolean determining if the amount of subsequent payments is likely to changeFractionedPayment
– a boolean determining if this is a payment in installmentsFrequency
– the frequency at which the subsequent pay-ins will be made
The frequency is an estimate of the intervals at which each recurring pay-in will occur until the end date. The value sent does not oblige you to follow this schedule, but allows you to. If at any point an issuing bank is not satisfied with the information presented they can request SCA. If this happens, you will be obliged to recall the end user to authenticate.
For Frequency
, the following values are available:
Value | Description |
---|---|
Daily | One transaction per day |
Weekly | One transaction every seven days |
TwiceAMonth | Two transactions per month |
Monthly | One transaction per month |
Bimonthly | One transaction every two months |
Quarterly | One transaction every three months |
Semiannual | One transaction every six months |
Annual | One transaction per year |
Biannual | One transaction every two years |
- PUT /recurringpayinregistrations/{RecurringPayinRegistrationId}
This endpoint allows you to modify the information in the registration object. You are able to modify: the card, the billing address, and the shipping address.
- Modifying the card will entail reauthentication of the end user, which must be done via a CIT
- Modifying the billing or shipping address will not require reauthentication
This endpoint can also be used to set the status to ENDED to prevent further use of the object.
- GET /recurringpayinregistrations/{RecurringPayinRegistrationId}
This endpoint allows you to obtain information on the registration object and the recurring payments (number of payments made with and for what amount).
- POST /payins/recurring/card/direct
This endpoint allows you to execute a recurring payIn, either a CIT or MIT. Calls to this endpoint contain a RecurringPayinRegistrationId, allowing it to be linked to the information contained in the registration endpoint.
The same endpoint is used to request both CIT and MIT payIns. The difference is in the information supplied in the body of the call.
For both CIT and MIT requests, you are also able to send the optional parameters Tag and StatementDescriptor.
Initial 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.
Mid-recurrence CIT
There are two cases where you may need to request a CIT after the initial CIT.
- Card modification
- Request for SCA from an issuing bank
You must send the same information as for an initial CIT. However, you need to add the parameter DebitedFunds if:
- No “NextTransactionDebitedFunds” was entered in the Recurring PayIn Registration
- You wish to debit an amount different to the NextTransactionDebitedFunds entered
Subsequent 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.
FreeCycles (€0 CIT)
Platforms have the possibility to define deadlines with an amount equal to €0. This can be useful to automate free trials or “first month free” subscriptions for instance.
To do so, platforms can use the FreeCycles
parameter to define the number of free consecutive deadlines in their registration objects.
When the EndDate
, FixedNextAmount
, and Frequency
values are defined in the recurring object, MANGOPAY automatically calculates the corresponding TotalAmount
and CycleNumber
. As a consequence, in such cases, attempting to define a number of FreeCycles
exceeding the cycleNumber
value will return an error.
Example: the first deadline is free (CIT) – the FreeCycles
parameter value is set to 1
{
"AuthorId" : {{USER_ID_BUYER}},
"CardID" : {{cardID}},
"CreditedUserId" : {{USER_ID_BUYER}},
"CreditedWalletId" : {{BUYER_WALLET_ID}},
"FreeCycles" : 1,
"Migration": false,
"FirstTransactionDebitedFunds" : {
"Currency" : "EUR",
"Amount" : 0
},
"FirstTransactionFees" : {
"Currency" : "EUR",
"Amount" : 0
},
"Billing" : {
"FirstName": "Jane",
"LastName": "Doe",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "01100",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Shipping" : {
"FirstName": "Jane",
"LastName": "Doe",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"NextTransactionDebitedFunds" : {
"Currency" : "EUR",
"Amount" : 4500
},
"NextTransactionFees" : {
"Currency" : "EUR",
"Amount" : 0
}
}
Example: The first deadline is free (CIT) and the next deadline too (MIT) – the FreeCycles
parameter value is set to 2.
{
"AuthorId" : {{USER_ID_BUYER}},
"CardID" : {{cardID}},
"CreditedUserId" : {{USER_ID_BUYER}},
"CreditedWalletId" : {{BUYER_WALLET_ID}},
"FreeCycles" : 2,
"Migration": false,
"FirstTransactionDebitedFunds" : {
"Currency" : "EUR",
"Amount" : 0
},
"FirstTransactionFees" : {
"Currency" : "EUR",
"Amount" : 0
},
"Billing" : {
"FirstName": "Jane",
"LastName": "Doe",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "01100",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
},
"Shipping" : {
"FirstName": "Jane",
"LastName": "Doe",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
}
}
}
Please note that when using the Create a Recurring PayIn MIT endpoint (POST …/payins/recurring/card/direct) for a payin subject to a free cycle, the DebitedFunds
and Fees
parameters should be ignored. Otherwise, the payin will fail with the corresponding error returned.
Status
During the recurrence, the Recurring PayIn Registration object can take one of four statuses:
- CREATED – the object has been created but not yet used for a recurring pay-in
- AUTHENTICATION_NEEDED – an attempted pay-in was unsuccessfully authorised, and the end user must reauthenticate. If the object has this status, you are obliged to notify the end user and execute a CIT which they authenticate.
- IN_PROGRESS – the recurring payment is in progress
- ENDED – the recurrence is ended. The object can no longer be modified or re-used.
We recommend that you check the ResultCode returned in the case of a failed pay-in. It is possible for a payment to fail without a request for re-authentication. You can find the full list of error codes here.
Workflows
Initiate a new recurring payment flow
- The end user requests a recurring payment
- You create the registration object (POST /recurringpayinregistrations)
- Our API returns a
RecurringPayinRegistrationId
- 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)
Re-authenticate a recurring payment
You may need to reauthenticate the cardholder in two cases:
- You modify the card (PUT /recurringpayinregistrations)
- A recurring pay-in fails because SCA is requested by the issuing bank. The failed recurring pay-in will show the ResultCode 101305, Soft decline
In both cases the Status of the registration object will change to AUTHENTICATION_NEEDED.
You will be required to:
- Notify the cardholder that they must re-authenticate
- Execute a CIT mid-recurrence
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
Migration
parameter to TRUE. - Our API returns a
RecurringPayinRegistrationId
- 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,
Migration
remains TRUE and the registration object status changes to IN PROGRESS. You can continue requesting MITs using theRecurringPayinRegistrationId
. - The issuing bank refuses the transaction request. In this case, the registration object status changes to ENDED . You will be obliged to create a new RecurringPayinRegistrationId and 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 as if you are starting a new recurrence. A refused migration will not deactivate your card object.