CIWEMB-214: Create API to generate the payment plan schedule based on payment scheme

[omarabuhussein]

Overview

Creating new API v4 action PaymentScheme.GetPaymentSchemeSchedule, that generates the instalments schedule for a recurring contribution (payment plan) that is linked to a payment scheme, using the payment scheme instalments configurations.

This API will be used by payment processor extensions like GoCardless and Stripe to help creating Payment Schedule on such payment processors.

Before

~

After

• New API v4 action PaymentScheme.GetPaymentSchemeSchedule is now avaiable.
• That takes contributionRecurId as an input.
• And expect such recurring contribution to have a payment scheme to be linked to it (it throws an error if no payment scheme is linked to the input recurring contribution), where the payment scheme parameters field is expected to be configured by the admin in the following JSON format:

{
    "instalments_count": 12,
    "instalments": [
      {"charge_date": "base_time, time_to_add"},
      {"charge_date": "base_time, time_to_add"},
      //..rest of instalments
    ]
}

where the charge_date has two variables separated by a comma, these two variables are:

1- base_time: Which can be either:

A- a token in case it is surrounded by {}, for now we only support 1 token which is {next_period_start_date} , which is the max membership end date among all the payment plan memberships + 1 day. B- Or a specific hardcoded date (such as 2022-05-11). C- Or a relative date that is accepted by PHP DateTime constructor, see PHP: Supported Date and Time Formats - Manual. (such as: 10 January, which will be translated to 10 Of Januaryof the current year`).

2- time_to_add: Which can anything that is accepted by DateTime::modify() function, see PHP: Supported Date and Time Formats - Manual. (such as '+2 months).

The time_to_add variable as well as comma can be both ignored if there is no extra time to be added.

Example:

{
    "instalments_count": 12,
    "instalments": [
      {"charge_date": "{next_period_start_date}, + 7 days"},
      {"charge_date": "{next_period_start_date}, + 1 month"},
          {"charge_date": "2022-01-11, + 1 month"},
          {"charge_date": "15 March"},
      //..rest of instalments
    ]
}

• And then API will return will generate an instalments schedule based on the recurring contribution data, as well as the linked payment scheme configuration, the format of the response looks as the following:

{
    "name" => "PP-contact_id-recur_contribution_id", // e.g PP-115-20
    "currency" => "The recurring contribution currency", // e.g "GBP"
    "total_amount" => "the sum of all instalments amounts in the instalments list below", // e.g "120"
    "instalments" => {
      {
        "charge_date" => "2019-08-20", // which is calculated for each instalment according to the format mentioned above, and based on the linked payment scheme configuration.
        "amount" => "10", // the total amount divided by number of instalments,  which is taken from the recurring contribution amount field directly
      },
          {
        "charge_date" => "2019-09-03",
        "amount" => "10",
      },
      //..rest of instalments
    }
}