Payment Plans Phase 7: Financial Fees and Other Use Cases (DEV-12467)
Payment Plans Phase 7 introduces financial fee support, enhanced payment method visibility on payment plan APIs, and independent payment plan information on anniversary statements. This release also resolves several calculation and collection issues. Aria improved the following APIs:
The following inputs are now available for creating fee inventory items:
| Field |
Type |
Description |
| <item_type> |
int |
Set to 3 for Fee. |
| <fee_application_type> |
int |
Defaults to 1 (applied to payment plan). |
| <fee_type> |
string |
Required when <item_type> is 3. Values: P (percentage), F (flat), A (amortized interest). |
| <fee_structure_list> |
array |
List of fee structures, one per currency. Each entry includes <currency_cd> and the fee amount or rate. |
A new input, <client_sku>, references the fee inventory item when the item is a fee type.
| New/Updated Field Name |
Input or Output |
Field Description |
| <client_sku> (New) |
Input |
The client-defined SKU for the fee-type inventory item. Applicable only when the inventory item is a fee type (<item_type> = 3). Mutually exclusive with <item_no>. |
The following outputs are now returned:
| Output |
Description |
| <fee_balance> |
Payment plan fee balance inclusive of tax. |
| <total_balance> |
Sum of principal balance and fee balance. |
| <fee_amount> (in <payment_plan_details>) |
Fee amount allocated to each sequence. |
| <total_due_amount> (in <payment_plan_details>) |
Sum of due amount and fee amount per sequence. |
get_payment_plan_details_m
Release 72 adds fee-aware fields to the payment plan schedule and a new payment method identifier to the top-level response. Several existing sequence fields have updated descriptions to clarify that their values include fees.
The description of get_payment_plan_details_m is now: Returns the full details and schedule for a specific payment plan on an account. Payment plans allow customers to pay outstanding balances in installments over multiple billing periods. This API returns the plan’s configuration (type, total amount, number of installments, and frequency), current status, and the individual installment schedule showing each payment’s amount, due date, and payment status (paid, pending, or missed). Specify the payment plan by the <payment_plan_no> or <client_payment_plan_id> field. To list all payment plans on an account first, use get_payment_plan_list_m.
| New/Updated Field Name |
Input or Output |
Field Description |
| payment_plan_schedule array |
| <seq_due_amount> (Updated) |
Output |
The principal amount due for a payment plan sequence. |
| <seq_fee_due> (New) |
Output |
The fee amount due for a payment plan sequence. |
| <seq_total_due> (New) |
Output |
The total amount due for a payment plan sequence (principal and fee). |
| <seq_remaining_due> (New) |
Output |
The remaining principal amount due for a payment plan sequence. |
| <seq_fee_remaining_due> (New) |
Output |
The remaining fee amount due for a payment plan sequence. |
| <seq_paid_amount> (Updated) |
Output |
The total amount paid for a payment plan sequence, including fees. |
| <seq_remaining_balance> (Updated) |
Output |
The remaining balance for a payment plan sequence, including fees. |
| <payment_method_no> (New) |
Output |
The Aria-assigned payment method number associated with the payment plan. If null, the payment method or payment term associated with the billing group is used. This field removes the ambiguity that occurred when <client_payment_method_id> returned null despite a payment method being explicitly set at the plan level. |
Release 72 adds fee-aware output fields and a new payment method identifier to the get_payment_plan_list_m response. The existing <remaining_balance> field has also been updated to reflect the total remaining balance inclusive of fees.
The description of get_payment_plan_list_m is now: Returns a list of all payment plans configured on an account. Payment plans allow customers to spread an outstanding balance across multiple billing periods rather than paying the full amount at once. Each payment plan has a schedule defining the payment amounts, frequency, and duration. By default, only active payment plans are returned; set <include_all_statuses> to true to also include completed, cancelled, or suspended plans. Use get_payment_plan_details_m to retrieve the full details and payment schedule for a specific plan.
| New/Updated Field Name |
Input or Output |
Field Description |
| payment_plan_list array |
| <payment_method_no> (New) |
Output |
The Aria-assigned payment method number associated with the payment plan. If null, the payment method or payment term associated with the billing group is used. |
| <fee_balance> (New) |
Output |
The payment plan fee balance, inclusive of tax, to be paid. |
| <remaining_balance> (Updated) |
Output |
The remaining balance, including fees, to be paid by the payment plan at the time of the API call. |
Release 72 adds a new allowable value to the <item_type> output field to support fee-type inventory items.
Returns a list of inventory items created for the client.
| New/Updated Field Name |
Input or Output |
Field Description |
| <item_type> (Updated) |
Output |
The item type for the inventory item.
| Values |
Description |
| 0 |
Inventory Item |
| 1 |
Months To Stack (Deprecated) |
| 2 |
Resource Item |
| 3 |
Fee |
|
get_inventory_item_details_m
Release 72 adds a new allowable value to <item_type> and introduces three new output fields that return fee configuration details for fee-type inventory items.
| New/Updated Field Name |
Input or Output |
Field Description |
| <item_type> (Updated) |
Output |
The item type for the inventory item.
Allowable Values
| Value |
Description |
| 0 |
Inventory Item |
| 1 |
Months To Stack (Deprecated) |
| 2 |
Resource Item |
| 3 |
Fee |
|
| <fee_application_type> (New) |
Output |
Specifies how the fee is applied. If <item_type> = 3, defaults to 1. Allowable value: 1 —Applied to payment plan. Null for non-fee items. |
| <fee_type> (New) |
Output |
The type of fee calculation. Required when <item_type> = 3.
| Value |
Description |
| P |
Percentage-based |
| F |
Flat |
| A |
Amortized (declining balance) interest |
Null for non-fee items.
|
| fee_structure_list array —List of fee structure components. Null or empty for non-fee items. |
| <currency_cd> (New) |
Output |
The ISO currency code for the fee. |
| <tax_inclusive_ind> (New) |
Output |
Indicates whether the fee is inclusive of taxes. Allowable values: 1 —Tax inclusive, 0 —Tax exclusive. |
| <fee_amount> (New) |
Output |
The fee amount. Works in conjunction with <fee_type>. |
- Double collection during billing batch: Aria no longer attempts duplicate payment collection on accounts where
COLLECTOR_REVIEWED_IND (a database field referenced during a batch process) via create_acct_complete_m has already triggered a payment attempt, when those accounts have installment dues with dunning completion master plan suites. Previously, a failed collection attempt during account creation would not set the indicator, causing the billing batch to incorrectly attempt collection a second time. Aria now handles failed collections resulting from create_acct_complete_m calls.
- <recurring_amount> rounding: The update_payment_plan_m API now correctly rounds <recurring_amount> to two decimal places in the response, ensuring a more accurate accounting of payment plans.
