Recurring Payment

Execute Payments automatically

Introduction

MyFatoorah platform provides a simple and secured way for your business to handle recurring payments on your behalf. We provide simple endpoints that allow you to make or cancel a recurring payment as well as to get a list of all existing recurring payments. The recurring payment is very useful to many business cases like the subscription-based payment models.

❗️

Approval is needed!

Kindly, contact your account manager or sales representative to activate the Recurring feature. Please, note that not all Payment Methods are supporting the Recurring feature, this feature is only available for credit card gateways.


How it works

Here, you should adjust the RecurringModel parameter of the ExecutePayment endpoint to ask the API to make a recurring payment and get the RecurringId value back to your system.

The Iteration parameter determines how many times you will charge the customer for your services. If the Iteration parameter is set to "0", it will be an unlimited time of charging the customer until you cancel the recurring.

The RecurringType parameter defines the interval time of charging the customer again with the same amount sent in the ExecutePayment endpoint request. The value of the RecurringType parameter is as follows

  • Custom
  • Daily
  • Weekly
  • Monthly

If you choose any value of the previous choices except the "custom" value, the interval days parameter will be ignored. In the case of choosing the "Custom" as the RecurringType, then you should set the value of the IntervalDays between 1 and 180 days based on your business needs.

The RetryCount parameter is used to set the number of times that the system should retry a failed recurring payment before stopping the subscription cycle. It is an optional parameter, and it is between 0 to 5. The retry process is done every day until the counter becomes zero or the invoice gets paid. The counter is reset with each iteration.

📘

Manual Retry

You can manually retry any failed recurring payment by using the ResumeRecurringPayment endpoint.

Once you have initiated a Recurring Payment, the status of the recurring will be "Draft" until the user pays the invoice. After that, the recurring status becomes "Active".

You have to save the RecurringId in your system with your customer profile so that, you can keep track of all payments done against that customer. Moreover, you will be able to cancel it when needed later on.

We strongly recommend implementing the Webhook feature to be able to track every execution of the recurring payment based on the interval, so that can update your system accordingly.

👍

Testing Recurring

For the test purpose, you should use the PaymentMethodId parameter with value "20" in the request body of ExecutePayment endpoint.

🚧

Recurring Amount

Please note that the recurring transaction amount can not be changed after it's initiated. If your recurring payment-due amount is changed, you will have to cancel the old recurring payment and make a new recurring payment with the updated amount.


Sample Messages

{
  "PaymentMethodId": 20,
  "CustomerName": "username",
  "DisplayCurrencyIso": "kwd",
  "MobileCountryCode": "965",
  "CustomerMobile": "12345678",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 232.5,
  "CallBackUrl": "https://google.com",
  "ErrorUrl": "https://youtube.com",
  "Language": "EN",
  "RecurringModel": {
    "RecurringType": "Custom",
    "IntervalDays": 1,
    "Iteration": 3,
    "RetryCount": 5
  }
}
{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 660830,
        "IsDirectPayment": false,
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/Checkout?invoiceKey=030631666083046&paymentGatewayId=48",
        "CustomerReference": null,
        "UserDefinedField": null,
        "RecurringId": "RECUR316280"
    }
}

📘

Info

You can cancel any recurring payment by using the CancelRecurringPayment endpoint. Also, you can use the GetRecurringPayment endpoint to fetch all information about all recurring payments at your portal.



Did this page help you?