Recurring Data Model

Overview

The "Recurring Data Model" is a Data model type used in your webhook endpoint. This model provides information about any RecurringStatusChanged event.

Your webhook endpoint will receive a POST request from MyFatooah that contains an EventType parameter with a value of "5". It is used to notify your system that a recurring payment has occurred. It also notifies your system with each retry count (When MyFatoorah retries to withdraw the recurring value again after payment failure. You can check the details in the Recurring Model). It contains the transaction status (SUCCESS or FAILED) as well as the recurring status (ACTIVE, UNCOMPLETED or COMPLETED).

Detailed functionality of how to implement your webhook endpoint is explained in the Webhook section.

Now, we are going to declare the Recurring Data Model properties of your endpoint and its models along with each accepted parameter and possible value.

Request Model

Input Parameter	Type	Description
RecurringId	string	A unique number for each recurring payment. It's recommended to save this ID 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.
RecurringStatus	string	ACTIVE: The recurring payment is being processed normally but its iterations have not been completed yet. UNCOMPLETED: MyFatoorah tried to withdraw the recurring value but the payment has failed and also Retry Counts have been executed and produced failed payments. COMPLETED: The recurring payment has been executed successfully with all its iterations and will not be executed again.
NextPayDate	string	The next date recurring payment will be executed.
InvoiceId	number	The unique ID of the invoice for this payment.
InvoiceReference	string	The unique reference for this invoice.
CreatedDate	string
TransactionStatus	string	The status of this particular transaction of the recurring payment. it can be whether SUCCESS or FAILED.
ReferenceId	string
TrackId	string
PaymentId	string
AuthorizationId	string
InvoiceValueInBaseCurrency	string	Recurring Value in your account base currency.
BaseCurrency	string	Your account base currency.

Sample Message

The below sample JSON message is sent by MyFatoorah to your endpoint.

{
	"EventType": 5,
	"Event": "RecurringStatusChanged",
	"DateTime": "14092024040707",
	"CountryIsoCode": "SAU",
	"Data": {
		"RecurringId": "RECUR31144164",
		"RecurringStatus": "ACTIVE",
		"NextPayDate": "11092024000000",
		"InvoiceId": 36170506,
		"InvoiceReference": "2024000730",
		"CreatedDate": "14092024040707",
		"TransactionStatus": "INPROGRESS",
		"ReferenceId": "0808361705063528110582",
		"TrackId": "14-09-2024_35281105",
		"PaymentId": "0808361705063528110582",
		"AuthorizationId": "0808361705063528110582",
		"InvoiceValueInBaseCurrency": "0.1",
		"BaseCurrency": "SAR"
	}
}

👍
Signature
To generate the signature of this model, you should order only the above parameters alphabetic with its values then encrypt it by the secret key.

The following will be a sample string used in generating the signature.

AuthorizationId=B68413,BaseCurrency=KWD,CreatedDate=04032021211555,InvoiceId=586170,InvoiceReference=2021000184,InvoiceValueInBaseCurrency=456.75,NextPayDate=2021-04-07T00:00:00,PaymentId=100202106359084366,RecurringId=RECUR287,RecurringStatus=Completed,ReferenceId=106310001097,TrackId=04-03-2021_477336,TransactionStatus=SUCCESS

Overview

Request Model

Sample Message

👍Signature

👍
Signature