How to process a recurring card payment

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 (Visa, Mastercard, CB, or AMEX), 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_01KHXAHEBRWSZXJY85TPPR56TK",
    "CardId": "card_wt_HodULFWKVRMEecCa",
    "CreditedWalletId": "wlt_m_01KHXAHH2NA3AAMPGE1SJPHJDJ",
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "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   
}

<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $payIn = new \MangoPay\PayInRecurringRegistration();

    $payIn->AuthorId = "user_m_01J2CBKKMQJ95BGHCW0A2F9DE1";
    $payIn->CardId = "card_m_01J2CBM93A3R36V2T2HFC2RRW4";
    $payIn->CreditedUserId = "user_m_01J2CBPBE80P5Z8BTY9GJWQTVM";
    $payIn->CreditedWalletId = "wlt_m_01J2CBPWWRKK4G65X4MTBVNWPS";

    $payIn->FirstTransactionDebitedFunds = new \MangoPay\Money();
    $payIn->FirstTransactionDebitedFunds->Amount = 12;
    $payIn->FirstTransactionDebitedFunds->Currency = 'EUR';
    $payIn->FirstTransactionFees = new \MangoPay\Money();
    $payIn->FirstTransactionFees->Amount = 1;
    $payIn->FirstTransactionFees->Currency = 'EUR';

    $adress = new \MangoPay\Address();
    $adress->AddressLine1 = '4 rue de la Tour des Dames';
    $adress->AddressLine2 = 'Mangopay office';
    $adress->City = 'Paris';
    $adress->Country = 'FR';
    $adress->PostalCode = '75009';
    $adress->Region = 'Île-de-France';

    $billing = new \MangoPay\Billing();
    $billing->FirstName = 'John';
    $billing->LastName = 'Doe';
    $billing->Address = $adress;

    $shipping = new \MangoPay\Shipping();
    $shipping->FirstName = 'John';
    $shipping->LastName = 'Doe';
    $shipping->Address = $adress;

    $payIn->Shipping = $shipping;
    $payIn->Billing = $billing;

    $payIn->FreeCycles = 0;

    $response = $api->PayIns->CreateRecurringRegistration($payIn);

    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}  

const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
})

let myRecurringRegistration = {
  PaymentType: 'CARD',
  ExecutionType: 'DIRECT',
  AuthorId: '146476890',
  CardId: '169687329',
  CreditedUserId: '146476890',
  CreditedWalletId: '148968396',
  FirstTransactionDebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  FirstTransactionFees: {
    Currency: 'EUR',
    Amount: 10,
  },
  Billing: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
  Shipping: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
  EndDate: 1698923634,
  Frequency: 'Monthly',
  FixedNextAmount: false,
  FractionedPayment: false,
  FreeCycles: 0,
  NextTransactionDebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  NextTransactionFees: {
    Currency: 'EUR',
    Amount: 10,
  },
}

const createRecurringRegistration = async (recurringRegistration) => {
  return await mangopay.PayIns.createRecurringPayment(recurringRegistration)
    .then((response) => {
      console.info(response)
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    })
}

createRecurringRegistration(myRecurringRegistration)  

require 'mangopay'

MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
    client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def createRecurringRegistration(recurringRegistrationObject)
    begin
        response = MangoPay::PayIn::RecurringPayments::Recurring.create(recurringRegistrationObject)
        puts response
        return response
    rescue MangoPay::ResponseError => error
        puts "Failed to create recurring registration: #{error.message}"
        puts "Error details: #{error.details}"
        return false
    end
end

my_recurring_registration = {
  AuthorId: '146476890',
  CardId: '169687329',
  CreditedUserId: '146476890',
  CreditedWalletId: '148968396',
  FirstTransactionDebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  FirstTransactionFees: {
    Currency: 'EUR',
    Amount: 10,
  },
  Billing: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
  Shipping: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
  EndDate: 1698923634,
  Frequency: 'Monthly',
  FixedNextAmount: false,
  FractionedPayment: false,
  FreeCycles: 0,
  NextTransactionDebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  NextTransactionFees: {
    Currency: 'EUR',
    Amount: 10,
  },
}

createRecurringRegistration(my_recurring_registration)  

from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import NaturalUser, RecurringPayInRegistration
from mangopay.utils import Money

natural_user = NaturalUser.get('210513027')

recurring_payin_registration = RecurringPayInRegistration(
    author_id = natural_user.id,
    card_id = '213857548',
    credited_wallet_id = '210514820',
    first_transaction_debited_funds = Money(amount=1000, currency='EUR'),
    first_transaction_fees = Money(amount=10, currency='EUR'),
    tag = 'Created using Mangopay Python SDK'
)

create_recurring_payin_registration = recurring_payin_registration.save()

pprint(create_recurring_payin_registration)  

In the response, you will need the Id of the Recurring PayIn Registration for the next steps.

API response

{
    "Id": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "Status": "CREATED",
    "ResultCode": null,
    "ResultMessage": null,
    "CurrentState": {
        "PayinsLinked": 0,
        "CumulatedDebitedAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "CumulatedFeesAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "LastPayinId": null
    },
    "RecurringType": "CUSTOM",
    "TotalAmount": null,
    "CycleNumber": null,
    "AuthorId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CardId": "card_m_UsklnOoXBWyyqhsN",
    "CreditedUserId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CreditedWalletId": "wlt_m_01JJ70WZ9JRAZ9GE0DA36Q84NQ",
    "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"
        }
    },
    "EndDate": null,
    "Frequency": "Monthly",
    "FixedNextAmount": true,
    "FractionedPayment": false,
    "FreeCycles": 0,
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "NextTransactionDebitedFunds": null,
    "NextTransactionFees": null,
    "Migration": false,
    "PaymentType": "CARD_DIRECT"
}

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

<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $cit = new \MangoPay\RecurringPayInCIT();

    $cit->RecurringPayinRegistrationId = 'recpayinreg_m_01J2EA0TAVQPNY4JGGF1J7RD97';
    $cit->SecureModeReturnURL = "http://example.com";
    $cit->StatementDescriptor = "MGP TEST";
    $cit->Tag = "Generated using Mangopay documentation";
    $cit->IpAddress = "2001:0620:0000:0000:0211:24FF:FE80:C12C";

    $browserInfo = new \MangoPay\BrowserInfo();
    $browserInfo->AcceptHeader = "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8";
    $browserInfo->JavaEnabled = true;
    $browserInfo->Language = "FR-FR";
    $browserInfo->ColorDepth = 4;
    $browserInfo->ScreenHeight = 1800;
    $browserInfo->ScreenWidth = 400;
    $browserInfo->TimeZoneOffset = 60;
    $browserInfo->UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148";
    $browserInfo->JavascriptEnabled = true;

    $cit->BrowserInfo = $browserInfo;

    // Required if the registration’s NextTransactionDebitedFunds is empty.
    $cit->DebitedFunds = new \MangoPay\Money();
    $cit->DebitedFunds->Amount = 10;
    $cit->DebitedFunds->Currency = 'EUR';
    $cit->Fees = new \MangoPay\Money();
    $cit->Fees->Amount = 1;
    $cit->Fees->Currency = 'EUR';

    $response = $api->PayIns->CreateRecurringPayInRegistrationCIT($cit);

    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}  

const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
})

let myRecurringPayinCIT = {
  Tag: 'Created with Mangopay Nodejs SDK',
  DebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  Fees: {
    Currency: 'EUR',
    Amount: 10,
  },
  SecureModeReturnURL: 'http://example.com',
  StatementDescriptor: 'Mangopay',
  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,
  },
  IpAddress: '2d1b:f91a:075a:7fc8:0cb7:b471:cd55:017e',
  RecurringPayiNRegistrationId: '192912686',
}

const createRecurringPayIn = async (recurringPayin) => {
  return await mangopay.PayIns.createRecurringPayInRegistrationCIT(recurringPayin)
    .then((response) => {
      console.info(response)
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    })
}

createRecurringPayIn(myRecurringPayinCIT)  

require 'mangopay'

MangoPay.configure do |client|
   client.preproduction = true
   client.client_id = 'your-client-id'
   client.client_apiKey = 'your-api-key'
   client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def CreateRecurringPayInCIT(recurringPayinCITObject)
   begin
       response = MangoPay::PayIn::RecurringPayments::CIT.create(recurringPayinCITObject)
       puts response
       return response
   rescue MangoPay::ResponseError => error
       puts "Failed : #{error.message}"
       puts "Error details: #{error.details}"
       return false
   end
end

my_cit_object = {
   "Tag":"custom meta",
   # "DebitedFunds":{
   #     "Currency":"EUR",
   #     "Amount":900
   # },
   # "Fees":{
   #     "Currency":"EUR",
   #     "Amount":10
   # },
   "SecureModeReturnURL":"http://example.com",
   "StatementDescriptor":"POSTMAN",
   "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
   },
   "IpAddress":"2001:0620:0000:0000:0211:24FF:FE80:C12C",
   "RecurringPayinRegistrationId":"recpayinreg_m_01J2EG8FD7TD6R3HGPZ8ZM917Y",
   "PreferredCardNetwork": "MASTERCARD"
}

CreateRecurringPayInCIT(my_cit_object)

import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import NaturalUser, RecurringPayInCIT
from mangopay.utils import Money, BrowserInfo

natural_user = NaturalUser.get('210513027')

recurring_payin_cit = RecurringPayInCIT(
    debited_funds = Money(amount=1000, currency='EUR'),
    fees = Money(amount=0, currency='EUR'),
    secure_mode_return_url = 'http://example.com',
    browser_info = BrowserInfo(
        user_agent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148',
        screen_width = 375,
        screen_height = 667,
        color_depth = 32,
        language = 'EN',
        accept_header = 'application/json,text/javascript,*/*;q=0.01<',
        timezone_offset = '-120',
        java_enabled = True,
        javascript_enabled = True
    ),
    ip_address = '159.180.248.187',
    recurring_payin_registration_id = '213879771',
    tag = 'Created using Mangopay Python SDK'
)

create_recurring_payin_cit = recurring_payin_cit.save()

pprint(create_recurring_payin_cit)
  

API response

{
    "Id": "payin_m_01JJP2PDQWD7S2W42RR6S21VZE",
    "Tag": "Created using Mangopay API Postman Collection",
    "CreationDate": 1738055301,
    "AuthorId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CreditedUserId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "CreditedFunds": {
        "Currency": "EUR",
        "Amount": 9500
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "Status": "CREATED",
    "ResultCode": null,
    "ResultMessage": null,
    "ExecutionDate": null,
    "Type": "PAYIN",
    "Nature": "REGULAR",
    "CreditedWalletId": "wlt_m_01JJ70WZ9JRAZ9GE0DA36Q84NQ",
    "DebitedWalletId": null,
    "PaymentType": "CARD",
    "ExecutionType": "DIRECT",
    "SecureMode": null,
    "CardId": "card_m_UsklnOoXBWyyqhsN",
    "SecureModeReturnURL": "https://example.com/?transactionId=payin_m_01JJP2PDQWD7S2W42RR6S21VZE",
    "SecureModeRedirectURL": "https://api.sandbox.whenthen.co/payment-gateway/whenthen/threeDS/54b0c206-0a67-43d4-ace6-14a25697cf85/challenge?id=d7a9a1dd-80aa-4252-b2b4-221e1898d67f&url=aHR0cHM6Ly9hcGkuc2FuZGJveC53aGVudGhlbi5jby9wYXltZW50cy8zRFNlY3VyZS81NGIwYzIwNi0wYTY3LTQzZDQtYWNlNi0xNGEyNTY5N2NmODUvYzA1YTBhYzktNjBmZC00NDQyLWEzYzAtYjlmOTVlN2I1ODk5&amount=MzMzNDE&currency=RVVS",
    "SecureModeNeeded": true,
    "Culture": "EN",
    "SecurityInfo": {
        "AVSResult": "NO_CHECK"
    },
    "StatementDescriptor": "Example123",
    "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
    },
    "IpAddress": "3a55:f45c:d44e:ff6a:c63b:f2ec:3a31:eb3e",
    "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"
        }
    },
    "Requested3DSVersion": null,
    "Applied3DSVersion": "V2_1",
    "RecurringPayinRegistrationId": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "PreferredCardNetwork": "MASTERCARD",
    "CardInfo": {
        "BIN": "497010",
        "IssuingBank": "LA BANQUE POSTALE",
        "IssuerCountryCode": "MA",
        "Type": "CREDIT",
        "Brand": "MASTERCARD",
        "SubType": null
    }
}  

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

<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $mit = new \MangoPay\RecurringPayInMIT();

    $mit->RecurringPayinRegistrationId = 'recpayinreg_m_01J2EG8FD7TD6R3HGPZ8ZM917Y';
    $mit->StatementDescriptor = "MGP TEST";
    $mit->Tag = "Generated using Mangopay documentation";

    // Required if the registration’s NextTransactionDebitedFunds is empty.
    $mit->DebitedFunds = new \MangoPay\Money();
    $mit->DebitedFunds->Amount = 10;
    $mit->DebitedFunds->Currency = 'EUR';
    $mit->Fees = new \MangoPay\Money();
    $mit->Fees->Amount = 1;
    $mit->Fees->Currency = 'EUR';

    $response = $api->PayIns->CreateRecurringPayInRegistrationMIT($mit);

    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}  

const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
})

let myRecurringPayinMIT = {
  Tag: 'Created with Mangopay Nodejs SDK',
  DebitedFunds: {
    Currency: 'EUR',
    Amount: 1000,
  },
  Fees: {
    Currency: 'EUR',
    Amount: 10,
  },
  StatementDescriptor: 'Mangopay',
  RecurringPayiNRegistrationId: '192912686',
}

const createRecurringPayIn = async (recurringPayin) => {
  return await mangopay.PayIns.createRecurringPayInRegistrationMIT(recurringPayin)
    .then((response) => {
      console.info(response)
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    })
}

createRecurringPayIn(myRecurringPayinMIT)  

require 'mangopay'

MangoPay.configure do |client|
   client.preproduction = true
   client.client_id = 'your-client-id'
   client.client_apiKey = 'your-api-key'
   client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def CreateRecurringPayInMIT(recurringPayinMITObject)
   begin
       response = MangoPay::PayIn::RecurringPayments::MIT.create(recurringPayinMITObject)
       puts response
       return response
   rescue MangoPay::ResponseError => error
       puts "Failed : #{error.message}"
       puts "Error details: #{error.details}"
       return false
   end
end

my_mit_object = {
   "Tag":"custom meta",
   # "DebitedFunds":{
   #     "Currency":"EUR",
   #     "Amount":900
   # },
   # "Fees":{
   #     "Currency":"EUR",
   #     "Amount":10
   # },
   "StatementDescriptor":"POSTMAN",
   "RecurringPayinRegistrationId":"recpayinreg_m_01J2EG8FD7TD6R3HGPZ8ZM917Y",
}

CreateRecurringPayInMIT(my_mit_object)

from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import NaturalUser, Money, RecurringPayInMIT
from mangopay.utils import BrowserInfo

natural_user = NaturalUser.get('210513027')

recurring_payin_mit = RecurringPayInMIT(
    debited_funds = Money(amount=1000, currency='EUR'),
    secure_mode_return_url = 'http://example.com', 
    browser_info = BrowserInfo( # Missing from doc, but needed here
        user_agent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_6 _1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148',
        screen_width = 375,
        screen_height = 667,
        color_depth = 32,
        language = 'EN',
        accept_header = 'application/json,text/javascript,*/*;q=0.01<',
        timezone_offset = '-120',
        java_enabled = True,
        javascript_enabled = True
    ),
    fees = Money(amount=0, currency='EUR'),
    ip_address = '159.180.248.187',
    recurring_payin_registration_id = '213879771',
    statement_descriptor = 'Jan2024',
    tag = 'Created using Mangopay Python SDK'
)

create_recurring_payin_mit = recurring_payin_mit.save()

pprint(create_recurring_payin_mit)
  

API response

200

{
    "Id": "payin_m_01JJP59QGFVTMF9Y6YP0K3DXR0",
    "Tag": "Created using Mangopay API Postman Collection",
    "CreationDate": 1738058031,
    "AuthorId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CreditedUserId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "DebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "CreditedFunds": {
        "Currency": "EUR",
        "Amount": 9500
    },
    "Fees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "Status": "SUCCEEDED",
    "ResultCode": "000000",
    "ResultMessage": "Success",
    "ExecutionDate": 1738058032,
    "Type": "PAYIN",
    "Nature": "REGULAR",
    "CreditedWalletId": "wlt_m_01JJ70WZ9JRAZ9GE0DA36Q84NQ",
    "DebitedWalletId": null,
    "PaymentType": "CARD",
    "ExecutionType": "DIRECT",
    "SecureMode": null,
    "CardId": "card_m_UsklnOoXBWyyqhsN",
    "SecureModeReturnURL": null,
    "SecureModeRedirectURL": null,
    "SecureModeNeeded": false,
    "Culture": "EN",
    "SecurityInfo": {
        "AVSResult": "NO_CHECK"
    },
    "StatementDescriptor": "Example123",
    "BrowserInfo": null,
    "IpAddress": null,
    "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"
        }
    },
    "Requested3DSVersion": null,
    "Applied3DSVersion": "V2_1",
    "RecurringPayinRegistrationId": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "PreferredCardNetwork": "MASTERCARD",
    "CardInfo": {
        "BIN": "497010",
        "IssuingBank": "LA BANQUE POSTALE",
        "IssuerCountryCode": "MA",
        "Type": "CREDIT",
        "Brand": "MASTERCARD",
        "SubType": null
    }
}

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

<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $recurringRegistrationId = "recpayinreg_m_01J2EA0TAVQPNY4JGGF1J7RD97";
    $response = $api->PayIns->GetRecurringRegistration($recurringRegistrationId);
    
    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}  

const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
})

let myRecurringRegistration = {
  Id: '192912686',
}

const viewRecurringRegistration = async (recurringRegistrationId) => {
  return await mangopay.PayIns.getRecurringPayin(recurringRegistrationId)
    .then((response) => {
      console.info(response)
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    })
}

viewRecurringRegistration(myRecurringRegistration.Id)  

require 'mangopay'

MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
    client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def viewRecurringRegistration(recurringRegistrationId)
    begin
        response = MangoPay::PayIn::RecurringPayments::Recurring.fetch(recurringRegistrationId)
        puts response
        return response
    rescue MangoPay::ResponseError => error
        puts "Failed to fetch recurring registration: #{error.message}"
        puts "Error details: #{error.details}"
        return false
    end
end

myRecurringRegistration = {
  Id: '192912686',
}

viewRecurringRegistration(myRecurringRegistration[:Id])  

from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import RecurringPayInRegistration

recurring_payin_registration_id = '213857583'

try:
    view_recurring_payin_registration = RecurringPayInRegistration.get(recurring_payin_registration_id)
    pprint(vars(view_recurring_payin_registration))
except RecurringPayInRegistration.DoesNotExist:
    print('The Recurring PayIn Registration {} does not exist.'.format(recurring_payin_registration_id))
  

API response

{
    "Id": "recpayinreg_m_01JJP2KS2A47A0P7S7CEBQPHT9",
    "Status": "IN_PROGRESS",
    "ResultCode": null,
    "ResultMessage": null,
    "CurrentState": {
        "PayinsLinked": 2,
        "CumulatedDebitedAmount": {
            "Currency": "EUR",
            "Amount": 20000
        },
        "CumulatedFeesAmount": {
            "Currency": "EUR",
            "Amount": 1000
        },
        "LastPayinId": "payin_m_01JJP59QGFVTMF9Y6YP0K3DXR0"
    },
    "RecurringType": "CUSTOM",
    "TotalAmount": null,
    "CycleNumber": null,
    "AuthorId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CardId": "card_m_UsklnOoXBWyyqhsN",
    "CreditedUserId": "user_m_01JHX34N3Y9BCQP7KR9QWWETDQ",
    "CreditedWalletId": "wlt_m_01JJ70WZ9JRAZ9GE0DA36Q84NQ",
    "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"
        }
    },
    "EndDate": null,
    "Frequency": "Monthly",
    "FixedNextAmount": true,
    "FractionedPayment": false,
    "FreeCycles": 0,
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 500
    },
    "NextTransactionDebitedFunds": null,
    "NextTransactionFees": null,
    "Migration": false,
    "PaymentType": "CARD_DIRECT"
}

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

<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $update = new \MangoPay\PayInRecurringRegistrationUpdate();
    $update->Id = "recpayinreg_m_01J2EA0TAVQPNY4JGGF1J7RD97";
    
    // To update user information
    $adress = new \MangoPay\Address();
    $adress->AddressLine1 = '4 rue de la Tour des Dames';
    $adress->AddressLine2 = 'Mangopay office';
    $adress->City = 'Paris';
    $adress->Country = 'FR';
    $adress->PostalCode = '75009';
    $adress->Region = 'Île-de-France';

    $shipping = new \MangoPay\Shipping();
    $shipping->FirstName = 'Arthur';
    $shipping->LastName = 'Doe';
    $shipping->Address = $adress;

    $update->Shipping = $shipping;

    $billing = new \MangoPay\Billing();
    $billing->FirstName = 'Arthur';
    $billing->LastName = 'Doe';
    $billing->Address = $adress;

    $update->Billing = $billing;

    // To end the recurring payin
    $update->Status = "ENDED";

    $response = $api->PayIns->UpdateRecurringRegistration($update);

    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}  

const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
})

let myRecurringRegistration = {
  Id: '192912686',
  CardId: '169687329',
  Status: '',
  Billing: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des grandes plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
  Shipping: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des grandes plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR',
    },
  },
}

const updateRecurringRegistration = async (recurringRegistrationId,recurringRegistration) => {
  return await mangopay.PayIns.updateRecurringPayin(recurringRegistrationId, recurringRegistration)
    .then((response) => {
      console.info(response)
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    })
}

updateRecurringRegistration(myRecurringRegistration.Id, myRecurringRegistration)  

require 'mangopay'

MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
    client.log_file = File.join(Dir.pwd, 'mangopay.log')
end

def updateRecurringRegistration(recurringRegistrationId, recurringRegistrationObject)
    begin
        response = MangoPay::PayIn::RecurringPayments::Recurring.update(recurringRegistrationId, recurringRegistrationObject)
        puts response
        return response
    rescue MangoPay::ResponseError => error
        puts "Failed to create recurring registration: #{error.message}"
        puts "Error details: #{error.details}"
        return false
    end
end

myRecurringRegistration = {
  Id: '195097427',
  CardId: '169687329',
  Status: '',
  Billing: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des très grandes plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR'
    },
  },
  Shipping: {
    FirstName: 'Alex',
    LastName: 'Smith',
    Address: {
      AddressLine1: 'Rue des très grandes plantes',
      AddressLine2: 'The Oasis',
      City: 'Paris',
      Region: 'IDF',
      PostalCode: '75000',
      Country: 'FR'
    }
  }
}

updateRecurringRegistration(myRecurringRegistration[:Id], myRecurringRegistration)  

from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import RecurringPayInRegistration

recurring_payin_registration = RecurringPayInRegistration(
    id = '213857583',
    status = 'ENDED'
)

update_recurring_payin_registration = recurring_payin_registration.save()

pprint(update_recurring_payin_registration)
  

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

Introduction

Users

SCA

User KYC/KYB verification

Payments

VOP

Payouts

FX services

Echo

Fraud prevention

How to process a recurring card payment

1. Create the Recurring PayIn Registration

2. Process the first recurring payment (CIT)

Make the request

Redirect the user to 3DS protocol

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

4. Update the registration (if required)

5. Handle re-authentication (when required)

6. Check the recurring payments’ current state

7. End the recurring payments

Guide

Endpoints

How to

​1. Create the Recurring PayIn Registration

​2. Process the first recurring payment (CIT)

​Make the request

​Redirect the user to 3DS protocol

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

​4. Update the registration (if required)

​5. Handle re-authentication (when required)

​6. Check the recurring payments’ current state

​7. End the recurring payments

​Related resources

Guide

Endpoints

How to

1. Create the Recurring PayIn Registration

2. Process the first recurring payment (CIT)

Make the request

Redirect the user to 3DS protocol

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

4. Update the registration (if required)

5. Handle re-authentication (when required)

6. Check the recurring payments’ current state

7. End the recurring payments

Related resources