This how-to guide will show you how to successfully process recurring payments with a registered card.
Prerequisites
  • A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard
  • A User object created for your end user, and their associated Wallet
  • A registered card (CB, Visa, or Mastercard), which is VALID or registered less than 24 hours ago, to make the payments
Setting up a recurring card payment is necessary when the platform repeatedly charges the end user at regular intervals, such as in subscription models or payments in installments. A recurring card payment has two phases:
  • Customer-initiated transaction (CIT) - An initial transaction in the presence of the cardholder, for which is required.
  • Merchant-initiated transactions (MIT) - Subsequent transactions made in the absence of the cardholder, initiated by the platform (and not subject to SCA unless required by the )
Learn more about recurring card payments

​
1. Create the Recurring PayIn Registration

The Recurring PayIn Registration object will define key information about the recurring payments such as:
  • The start and end date, as well as the frequency
  • Whether the amount is the same for each payment
  • Whether you want to offer zero-amount payments to your end user at the start of the recurrence (for example, during trial subscription offers)
For this guide, we’ll define a fixed monthly amount but not provide an end date.
POST /v2.01/{ClientId}/recurringpayinregistrations 
{
    "AuthorId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CardId": "card_m_UsklnOoXBWyyqhsN",
    "CreditedWalletId": "wlt_m_01JJ70WZ9JRAZ9GE0DA36Q84NQ",
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "Billing": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-France",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "Shipping": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-France",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "Frequency": "Monthly",
    "FixedNextAmount": true,
    "FractionedPayment": false   
}
In the response, you will need the Id of the Recurring PayIn Registration for the next steps.

​
2. Process the first recurring payment (CIT)

​
Make the request

Request the first payment, linking it to the registration object by using the Id returned in the previous step as the RecurringPayinRegistrationId. In our example, the first transaction amounts have been defined at the registration level. Because of this, we don’t need to define the DebitedFunds or Fees at the pay-in level.
POST /v2.01/{ClientId}/payins/recurring/card/direct 
{
    "RecurringPayinRegistrationId": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "IpAddress": "3a55:f45c:d44e:ff6a:c63b:f2ec:3a31:eb3e",
    "BrowserInfo": {
        "AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
        "JavaEnabled": true,
        "Language": "FR-FR",
        "ColorDepth": 4,
        "ScreenHeight": 1800,
        "ScreenWidth": 400,
        "TimeZoneOffset": 60,
        "UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
        "JavascriptEnabled": true
    },
    "SecureModeReturnURL": "https://example.com",
    "StatementDescriptor": "Example123",
    "Tag": "Created using Mangopay API Postman Collection",
    "PreferredCardNetwork": "MASTERCARD"
}

​
Redirect the user to 3DS protocol

The CIT transaction always requires 3DS (the SecureModeNeeded value is set to true), so you need to redirect the end user to the SecureModeRedirectURL value to complete the authentication. For more information on how to handle 3DS redirection, see Steps 6 and 7 of the How to process a card payment guide.

​
3. Process the subsequent recurring payments (MIT) at the defined intervals

Once the first pay-in has been successfully authorized, the platform can initiate payments without the end user being present to authenticate (but note that, at any time, the issuer may request SCA - see Step 5). Create the recurring pay-in at the set interval with the dedicated endpoint. Note that in our example, we didn’t define the next transaction amounts at the registration level. As a consequence, we need to pass the DebitedFunds and Fees parameters at the pay-in level.
POST /v2.01/{ClientId}/payins/recurring/card/direct 
{
    "RecurringPayinRegistrationId": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "Tag": "Created using Mangopay API Postman Collection",
     "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "StatementDescriptor": "Example123"
}

​
4. Update the registration (if required)

Some information regarding the recurring registration may be modified during the recurrence:
  • CardId - Changing this will require a new CIT for SCA
  • Billing and Shipping
Use the PUT Update a Recurring PayIn Registration endpoint to modify these details.

​
5. Handle re-authentication (when required)

At any moment during the recurrence, the issuer may request that the end user authenticates again. This also occurs when changing the CardId in the Recurring PayIn Registration (see Step 4). The need for re-authentication is indicated by the registration object’s Status changing to AUTHENTICATION_NEEDED. You can be notified of this by setting up webhook notifications for the following event type:
  • RECURRING_REGISTRATION_AUTH_NEEDED
In this case, you need to guide the end user through authentication during a new CIT in the same way as Step 2.

​
6. Check the recurring payments’ current state

The CurrentState of the Recurring PayIn Registration provides key information about the recurring payments:
  • Number of pay-ins made against the registration
  • Cumulated amounts of debited funds and fees
  • Last pay-in made against the registration
Use the GET View a Recurring PayIn Registration endpoint to get this information.
GET /v2.01/{ClientId}/recurringpayinregistrations/{RecurringPayinRegistrationId} 
// GET has no body parameters

​
7. End the recurring payments

Recurring payments may come to an end either automatically (when an EndDate was defined) or because the end user requests it. To end the recurring payments manually, use the Update a Recurring Registration endpoint to change the Status to ENDED.
PUT /v2.01/{ClientId}/recurringpayinregistrations/{RecurringPayinRegistrationId} 
{
    "Status": "ENDED"
}
When you do this, no more recurring pay-ins can be created based on the registration. Set up webhook notifications for the following event type to be notified when a registration is ended (for example, by the end user):
  • RECURRING_REGISTRATION_ENDED

Guide

Learn more about recurring card payments

Endpoints

The Recurring PayIn Registration object

How to

Learn how to process a card payment