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 change
• FractionedPayment – a boolean determining if this is a payment in installments
• Frequency – 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:

• 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.

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"
    }
}
}

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

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)
   
   

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.

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, 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.