Recurring Payment Management

Recurring payment management allows you to enable recurring customer chargebacks (including software subscriptions, etc.) via APIs.

The entire SOLUTION contains:

OpenAPIs: Connect to wonder gateway manage customer subscriptions & sale products.
Payment Link: A website for customer save their card and complete payment.
Wallet Link: A website for customer manage the payment method(change card to another one).

Models

Recurring Item: The recurring products that are included in the recurring cycle and will determine the billing amount.
Recurring Billing Config: Set up billing logic for a recurring cycle, including billing intervals, interval counts, and proration logic. These are to be assigned to newly created billing cycles to instruct the billing and start dates of the cycle. Furthermore, the Wonder system allows additional customization of billing dates for monthly/annual recurring cycles.
Recurring Plan: This record will contain specific customer profile to collect recurring/ instalment payments. The plan can be set up with default information, such as the default collection method and the default payment method. The recurring cycle billing orders will obtain the configured data from the recurring plan and do the invoicing, respectively.
Recurring Cycle: A recurring cycle consists of recurring billing configurations and items. It determines the recurring billing date and amount. A recurring plan can have either one or multiple recurring cycles, depending on whether it will have different billing amounts within a plan at different billing durations/intervals. For example, a recurring plan can have a free period for a month (cycle 1), followed by an annual payment (cycle 2).
Recurring Order: The system will generate a new recurring order once a billing cycle’s set date/time has been reached (set in Recurring Billing Configs). The individual recurring billing invoice can be fulfilled by automatically charging the assigned customer payment tokens or other forms of payments depending on the cycles' configurations.

Recurring Item

Reference ID: This is the external unique reference id for the sales item. It should to mapping your inventory system.
Label: This is name of the recurring product.
Price: This is to set the price of the item. The price will be the billing amount for the recurring order.
Currency: Which currency charged to customer.
Description: A description text.

Recurring Billing Config

Interval Count: The number of intervals between recurring billings.
Billing Interval: The frequency at which a recurring invoice is billed to the customer.
Billing Type: This is to determine if the system will apply automated billing date/time based on the current date/time of when the user subscribes to the recurring plan.
Billing Month: Which month generate order. Only for billing_interval = yearly
Billing Day Of Month: Which day of month generate order.
Billing Proration Enabled: - This data field is let the system knows if needs to calculate prorated amount.
Description: A description text.

Billing Interval

Value	Comment
daily	The invoice will be billed on daily basis
weekly	The invoice will be billed on weekly basis
monthly	The invoice will be billed on monthly basis
yearly	The invoice will be billed on yearly basis

Billing Count

The number of intervals between recurring billings.

Ifbilling_interval=monthly and billing_interval_counts=3, then system bills every 3 months.
If billing_interval=monthly and billing_interval_counts=1 , then system bills every 1 month.
If billing_interval=yearly and billing_interval_counts=1, then system bills every 1 year.

Billing Month

This data field is for yearly subscription to determine which month of the year should the system issue the recurring billing invoice to the customer. This field is only applicable for billing_interval = yearly. The billing time will always be set at 00:00:00 (local time to the business account) of the given defined billing date.

If billing_interval= yearly and billing_interval_counts =1 , and also billing_month= 3, then it means that for the yearly recurring plan of this customer, the system should charge the customer once in a year, on 1st March (if billing_day_of_month is not defined, then default to first date of the month). If the current date/time that the user triggers the subscription is 1st May 2024, and billing_proration_enabled=TRUE, then the system will calculate the payment to be paid from 1st May 2024 - 1st March 2025. The calculation will be calculated based on total X amount of recurring_items data / 365 * 304. The system will issue a billing invoice for customer to pay for recurring period of 1st May 2024 - 1st March 2025. The invoice’s billing start date will be 1st May 2024, and this should consider as one count for recurring_cycles.interval_counts
If billing_interval= yearly and billing_interval_counts =1, and also billing_month= 3,then it means that for the yearly recurring plan of this customer, the system should charge the customer once in a year, on 1st March (if billing_day_of_month is not defined, then default to first date of the month). If the current date/time that the user triggers the subscription is 1st February 2024, and billing_proration_enabled=TRUE, then the system will calculate the payment to be paid from 1st February 2024 - 1st March 2024. The calculation will be calculated based on total X amount of recurring_items data / 365 * 29. The system will issue a billing invoice for customer to pay for recurring period of 1st February 2024 - 1st March 2024. The invoice’s billing start date 1st February 2024, and this should consider as one count for recurring_cycles.interval_counts
If billing_interval= yearly and billing_interval_counts = 2, and also billing_month= 3,then it means that for the recurring plan of this customer, the system should charge the customer once in 2 years, on 1st March. (if billing_day_of_month is not defined, then default to first date of the month). If the current date/time that the user triggers the subscription is 1st May 2024, and billing_proration_enabled=TRUE, then the system will calculate the payment to be paid from 1st May 2024 - 1st March 2026. The calculation will be calculated based on total X amount of recurring_items data / (365*2) * 669. The system will issue a billing invoice for customer to pay for recurring period of 1st May 2024 - 1st March 2026. The invoice’s billing start date will be 1st May 2024 00:00:00, and this should consider as one count for recurring_cycles.interval_counts

Billing Day Of Month

This data field is for monthly, or yearly subscription to determine which day of the month should the system issue the recurring billing invoice to the customer. This field is only applicable for billing_interval = monthly/yearly. The billing time will always be set at 00:00:00 (local time to the business account) of the given defined billing date.

If billing_interval= yearly and billing_interval_counts =1, and also billing_month= 3,billing_day_of_month= 20,then it means that for the yearly recurring plan of this customer, the system should charge the customer once in a year, on 20th March. If the current date/time that the user triggers the subscription is 1st May 2024, and billing_proration_enabled=TRUE, then the system will calculate the payment to be paid from 1st May 2024 - 20th March 2025. The calculation will be calculated based on total X amount of recurring_items data / 365 * 323. The system will issue a billing invoice for customer to pay for recurring period of 1st May 2024 - 20th March 2025. The invoice’s billing start date will be 1st May 2024 00:00:00, and this should consider as one recurring_cycles.interval_counts.
If billing_interval= yearly and billing_interval_counts =2, and alsobilling_month= 3,billing_day_of_month= 31,then it means that for the recurring plan of this customer, the system should charge the customer once in 2 year, on 31st March. If the current date/time that the user triggers the subscription is 1st May 2024, and billing_proration_enabled=TRUE, then the system will calculate the payment to be paid from 1st May 2024 - 30st March 2026. The calculation will be calculated based on total X amount of recurring_items data / (365*2) * 699. The system will issue a billing invoice for customer to pay for recurring period of 1st May 2024 - 31st March 2026. The invoice’s billing start date will be 1st May 2024 00:00:00, and this should consider as one count for recurring_cycles.interval_counts.
If billing_interval= monthly and billing_interval_counts = 1, and also billing_day_of_month= 31,then it means that for the monthly recurring plan of this customer, the system should charge the customer once in a month, on 31st of each month. If the current date/time that the user triggers the subscription is 1st May 2024, and billing_proration_enabled= TRUE, then the system will calculate the payment to be paid from 1st May 2024 - 31st May 2024. The system will issue a billing invoice for customer to pay for recurring period of 1st May 2024 - 31st May 2024. The invoice’s billing start date will be 1st May 2024 00:00:00, and this should consider as one recurring_cycles.interval_counts
If billing_interval= monthly and billing_interval_counts = 1, and also billing_day_of_month= 31,then it means that for the monthly recurring plan of this customer, the system should charge the customer once in a month, on 31st of each month. If the current date/time that the user triggers the subscription is 3rd February 2024, and billing_proration_enabled= TRUE, then the system will calculate the payment to be paid from 3rd February 2024 - 29th February 2024. This is because in February 2024, there is only 29 days (leap year). Need to note that for special months that don’t have 31 days: only have 28/29/30 days, then the system will use that last date of the month; if billing_day_of_month= 31. The system will issue a billing invoice for customer to pay for recurring period of 3rd February 2024 - 29th February 2024. The invoice’s billing start date will be 3rd February 2024 00:00:00, and this should consider as one recurring_cycles.interval_counts
If billing_interval= monthly and billing_interval_counts = 6, and also billing_day_of_month= 28,then it means that for the 6-month recurring plan of this customer, the system should charge the customer once in in 6 months, on the 28th. If the current date/time that the user triggers the subscription is 5th May 2024, and billing_proration_enabled= TRUE, then the system will calculate the payment to be paid from 5th May 2024 - 28th November 2024 (6th months from May is November). The calculation will be calculated based on total X amount of recurring_items data / 184 (days between 28th May - 28th Nov 2024) * 207 (days between 5th May - 28th Nov 2024). The system will issue a billing invoice for customer to pay for recurring period of 5th May 2024 - 28th November 2026. The invoice’s billing start date will be 5th May 2024 00:00:00, and this should consider as one recurring_cycles.interval_counts.

Billing Type

Value	Comment
automated	-
customized	-

This is to determine if the system will apply automated billing date/time based on the current date/time of when the user subscribes to the recurring plan.

automated: the system will select the current calendar date/time to be the start date of the recurring billing cycle. For example, if user is subscribing on 1st March 2024, and billing_interval= yearlyand billing_interval_counts =1; then, user will be issued with a billing invoice of 1st March 2024 - 1st March 2025.
- If user is subscribing on 1st March 2024, and billing_interval= monthly and billing_interval_counts =2; then, user will be issued with a billing invoice of 1st March 2024 - 1st May 2024.
- If user is subscribing on 1st March 2024, and billing_interval= weekly and billing_interval_counts = 2; then, user will be issued with a billing invoice of 1st March 2024 - 15th March 2024.
customized: if user chooses this option, depending on which data is set in billing_interval, they will need to configure billing_month; billing_day_of_month. This option is only applicable for when billing_interval = monthly/yearly.

Recurring Plan

Name: The plan's name.
Description: A description text.
Customer UUID: Which customer apply this plan.
Default Collection Method:
Default Payment Token:

Recurring Cycle

Name: The cycle name
Billing Count: This is to count how long will the recurring cycle run for.
Default Collection Method:
Payment Retry Day Period:
Payment Retry Count:
Grace Period:
Recurring Billing Config:
Estimated Start Date: The estimated start of this phase of the recurring cycle.
Estimated End Date: The estimated end of this phase of the recurring cycle.
Start Date: The actual start of this phase of the recurring cycle.
End Date: The actual end of this phase of the recurring cycle.
Interval Charged Count:
Status:

Billing Count

This is to count how long will the recurring cycle run for. For example if the recurring_billing_configs.billing_interval = monthly, with recurring_billing_configs.billing_interval_count = 1 , and interval_counts = 3, then it means this recurring_cycles record will run for 3 months (with each invoice to be billed every 1 month).

If the recurring_billing_configs.billing_interval = monthly, with recurring_billing_configs.billing_interval_count = 6 , and interval_counts = 3, then it means this recurring_cycles record will run for 18 months (with each invoice to be billed every 3 months).
If data is null, then consider this recurring_cycles record will run forerver. For example if the recurring_billing_configs.billing_interval = yearly, with recurring_billing_configs.billing_interval_count = 1 , and interval_counts = NULL, then it means this recurring_cycles record will run with no ending (with each invoice to be billed every 1 year).

Recurring Order

Order: Please refer to Order Management Order Model.
Cycle: Please refer to Recurring Cycle

API List

API Workflow for create recurring plan.

Create a customer profile via Create Customer API.
Create recurring items via API Create Recurring Item API.
Create recurring billing configs via API Create Recurring Billing Config API
Create recurring plan Create Recurring Plan API.
Share the recurring plan's first order payment link to customer.
Customer add or choose a exists payment token to complete pay the first order.
After the first order paid, then next orders will be use the same payment token in the future.

POST

Create Recurring Item

DELETE

Delete Recurring Item

GET

Get Recurring Items

POST

Create Recurring Billing Config

DELETE

Delete Recurring Item

GET

Get Recurring Billing Configs