Recurring Payment Management

Wonder Recurring solution allows you to enable recurring payment acceptance from customers (including services subscriptions, and instalments etc.) via APIs.

Our entire solution contains:

OpenAPI: Connect to Wonder gateway to manage customer subscriptions & sale products.
Payment Link: Web-base platform for customer initiate and complete payment.
Wallet Link: Web-base platform for customer manage the payment methods and invocies (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 items. It can be used to map with 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: The supported currency base on your business configuration.
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 based on the current day of when the date the recurring plan is created.
Billing Month: This is 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 AND billing_type = customized.
Billing Day Of Month: This is to determine which day of the month should the system issue the monthly/yearly recurring billing invoice to the customer. This field is only applicable for billing_type = customized.
Billing Proration Enabled: - This data field is let the system knows if needs to calculate prorated amount, if the customer is entering a recurring cycle that is not a full cycle period.
Description: A internal description text to identify to set of rules.

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

Interval Count

The number of intervals between recurring billings.

Ifbilling_interval=monthly and interval_count=3, then system bills every 3 months.
If billing_interval=monthly and interval_count=1 , then system bills every 1 month.
If billing_interval=yearly and interval_count=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 interval_count =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.billing_count
If billing_interval= yearly and interval_count =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.billing_count
If billing_interval= yearly and interval_count = 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.billing_count

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 interval_count =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.billing_count.
If billing_interval= yearly and interval_count =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.billing_count.
If billing_interval= monthly and interval_count = 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.billing_count
If billing_interval= monthly and interval_count = 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.billing_count
If billing_interval= monthly and interval_count = 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 30th May 2024, and billing_proration_enabled= TRUE, then the system will calculate the payment to be paid from 30th 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) * 182 (days between 30th 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.billing_count.

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 date the recurring plan is created.

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 interval_count =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 interval_count =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 interval_count = 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 recurring plan name.
Description: Any description to remark about this record.
Customer UUID: The customer to be assigned with this recurring plan.
Default Collection Method: Single option choice - charge_automatically:When the recurring cycle has reached its due date, the system will automatically charge the tokenised card data from default_payment_method.
Payment Retry Day Period: Once the initial payment request attempt is unsuccessful, the system will wait until the next given period data specified in payment_retry_day_period. Once the specified day period has reached, then the system will pose another charge attempt to the recurring order.
Payment Retry Count: This is to set the limit how many attempts to be executed. Once the count limit has reached, then the system will change the status to recurring_cycles.state = uncollectible.
Grace Period: This field is to count the day period that after the final attempt of payment charge is unsuccessful, then how many more days until the system will void the recurring_order record. Then change the status to recurring_cycles.state = uncollectible. If grace_period = NULL , then the system will never void the recurring_orders record

Recurring Cycle

Billing Count: This is to count how long will the recurring cycle run for.
Recurring Billing Config: This is for the system to know the billing date of a cycle, once the cycle has started
Recurring Items: For the system to know how much it should be charging for the particular recurring invoice based on the defined items.
Discount Type: The discount type can be fixed or percentage, a combined configuration with discount_amount.
Discount Amount: A combined configuration with discount_amount. If discount_type = fixed, discount_amount unit is in: dollars; If discount_type = percentage, discount_amount can only be over 0 and not over 100.

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.interval_count = 1 , and billing_count = 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.interval_count = 6 , and billing_count = 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.interval_count = 1 , and billing_count = NULL, then it means this recurring_cycles record will run with no ending (with each invoice to be billed every 1 year).

Recurring Order

Please refer to Order Management Order Model.

API List

API Workflow for creating 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 Billing Config

GET

Get Recurring Billing Configs