create_payment_plan_m
Summary
| API Name | create_payment_plan_m |
|---|---|
| Class | transaction_services_m |
| Update Version | 66 |
Description
Creates a payment plan to pay off an account's outstanding balance over multiple billing periods. Payment plans allow customers to spread large balances across scheduled installments instead of requiring a single lump-sum payment. The plan scope can include all master plan instances under a billing group (all_master_plan_instance=Y), specific MPIs (master_plan_instance_list), specific invoices (invoice_list), and/or specific transactions (transaction_id_list). When you specify a list of master plan instances, invoice number, and transaction id, the payment plan will be created based on the combined open charges of all three. Two plan types are supported: Independent (type=0) with its own schedule and due dates, or Aligned (type=1) which adds installments to an existing MPI's anniversary statement. Configure the installment frequency with payment_plan_length, payment_plan_period_type, and payment_plan_interval. Optionally include a lump-sum down payment at the start.
Inputs
| Name | Type | Length | Required | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| client_no | long | 22 | Yes |
Aria-assigned unique identifier indicating the Aria client providing service to this account. |
||||||||
| auth_key | string | 32 | No |
Aria-assigned unique key for authenticating the validity of the requestor. This key is passed with each method call. |
||||||||
| acct_no | long | 22 | Yes |
Aria-assigned account identifier. Alternative required field: client_acct_id |
||||||||
| client_acct_id | string | 50 | Yes |
Client defined account identifier Alternative required field: acct_no |
||||||||
| client_billing_group_id | string | 100 | Yes |
Client-defined unique identifier for billing group associated with the payment plan. |
||||||||
| client_payment_plan_id | string | 100 | No |
Specifies unique client payment plan id |
||||||||
| payment_plan_name | string | 100 | No |
Payment plan name |
||||||||
| payment_plan_description | string | 1000 | No |
Payment plan description |
||||||||
| invoice_list | object | No |
A list of invoices |
|||||||||
| transaction_id_list | object | No |
A list of other transaction ID. |
|||||||||
| payment_plan_type | long | No |
Specifies the payment plan type for the account. Allowable values are: 0 - Independent, its own payment plan schedule and due dates or 1 - Aligned with an existing master plan instance anniversary statement. Optional when payment_plan_term_no or client_payment_plan_term_id is provided; inherited from the term if not specified. Allowed values:
|
|||||||||
| aligned_payment_plan_client_master_plan_instance_id | string | 100 | No |
The client-defined unique identifier for the master plan instance whose anniversary statement includes upcoming payment plan due. Mandatory when payment_plan_type = 1. |
||||||||
| payment_plan_length | long | No |
of MPI statements that the payment plan will be part of. Specifies the length of payment plan. For payment_plan_type = 0, the input will be used jointly with payment_plan_period_type. For payment_plan_type = 1, it is the number of MPI statements that the payment plan will be part of. Optional when payment_plan_term_no or client_payment_plan_term_id is provided; inherited from the term if not specified. |
|||||||||
| payment_plan_period_type | string | 1 | No |
Specifies the payment plan period type. Allowable values are: M (Months), W (weeks), D (Days). Mandatory if payment_plan_type = 0. Allowed values:
|
||||||||
| payment_plan_interval | long | No |
Specifies the payment plan interval, applicable when payment_plan_type = 0, and works jointly with payment_plan_period_type. If defined, must be less than payment_plan_length. If null, the system defaults to 1. |
|||||||||
| independent_payment_plan_date | string | No |
Defines the start date of the independent payment plan, needs to be the same or greater than the current date. |
|||||||||
| independent_payment_plan_days_until_due | long | No |
Specifies the number of days until due for independent payment plan. If Null, the system will look at days until due configured for a payment term or a specific payment method. |
|||||||||
| client_payment_method_id | string | No |
Note: This field is deprecated. Aria no longer supports client_payment_method_id. |
|||||||||
| all_master_plan_instance | string | No |
Include all master plan instances associated with the billing group. Allowable values are: Y - Yes, include all master plan instances. N - No, don't include all master plan instances. If null, it's treated as N (No). |
|||||||||
| master_plan_instance_list | object | No |
Specify a list of master plan instance |
|||||||||
| master_plan_instance_balance_ind | long | No |
Indicates the master plan instance balance to be paid off with the payment plan. Allowable values are: 0 - master plan instance past due balance; 1 - master plan instance full balance, including amount not due yet. If null, it will be treated as 0 (past due balance). Applicable only if all_master_plan_instance = Y, or master_plan_instance_list (array) is specified. |
|||||||||
| payment_plan_lump_sum_type | string | No |
Specifies the installment lump sum type for the assigned installment. Allowable values are: P - for proportionately split charge/tax; T - for purchase tax only. |
|||||||||
| payment_plan_lump_sum_amount | double | No |
Specifies the lump sum amount, mandatory when lump sump type is proportionately split (lump_sum_type = P). |
|||||||||
| payment_plan_lump_sum_amount_type | string | No |
Specifies the lump sum amount type. Allowable values are: P - Percentage of balance to be paid; F - Flat amount |
|||||||||
| payment_plan_lump_sum_date | string | No |
Specifies the date of when payment lump sum will be notified. If it's null, then lump sum will be notified along with the 1st payment plan due amount. Applicable only for independent. |
|||||||||
| payment_plan_lump_sum_days_until_due | long | No |
Specifies how many days after notified that a lump sum is due. If it's NULL, then the system will look at days until due configured for a payment term or a specific payment method. Applicable only for independent. |
|||||||||
| payment_plan_start_with_sequence | long | No |
Custom start with sequence for the payment plan. If Null, payment plan sequence will start with 1 (excluding lump sum). |
|||||||||
| do_write | string | 5 | No |
Boolean indicator that specifies whether to perform the requested operation or not. If 'false' is passed in the field, Aria calculates any potential effects from the call such as payment plan schedule, start date and end date etc. and return all relevant data without actually performing the requested operation or making any changes to the account. Do_write defaults to 'true'. Allowed values:
|
||||||||
| primary_payment_method_no | long | 22 | No |
Primary payment method no |
||||||||
| client_primary_payment_method_id | string | 100 | No |
Client-defined unique identifier of the primary payment method |
||||||||
| backup_payment_method_no | long | 22 | No |
Backup payment method no |
||||||||
| client_backup_payment_method_id | string | 100 | No |
Client-defined unique identifier of the backup payment method |
||||||||
| do_collect | string | 5 | No |
Indicates whether the system should collect any amount due today during payment plan creation. Allowable values: true - collect immediately, false - do not collect immediately. If set to true and the collection fails, the payment plan will not be created. If null, the default is false. Allowed values:
|
||||||||
| client_sku | string | 100 | No |
Client-defined SKU for the fee-type inventory item. Applicable only if the inventory item is a fee type (item_type = 3). Mutually exclusive with item_no. |
||||||||
| payment_plan_term_no | long | No |
Aria-assigned unique identifier for the payment plan term. Alternative field: client_payment_plan_term_id |
|||||||||
| client_payment_plan_term_id | string | 100 | No |
Client-defined identifier for the payment plan term. Alternative field: payment_plan_term_no |
invoice_list fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| invoice_no | long | No |
The Aria-assigned unique identifier for invoices |
transaction_id_list fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| transaction_id | long | No |
Unique transaction ID |
master_plan_instance_list fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| master_plan_instance_no | long | 22 | No |
Aria-assigned master plan instance number Alternative field: client_master_plan_instance_id |
| client_master_plan_instance_id | string | 100 | No |
The client-defined unique identifier for master plan instances Alternative field: master_plan_instance_no |
Outputs
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| error_code | long | No |
Aria-assigned error identifier. 0 indicates no error. |
|
| error_msg | string | No |
Description of any error that occurred. "OK" if there was no error. |
|
| payment_plan_no | long | No |
Aria-assigned payment plan no |
|
| client_payment_plan_id | string | No |
Client unique payment plan id |
|
| initial_balance | double | No |
Principal portion of the payment plan balance (charge amount + charge tax). Excludes fee and fee tax. |
|
| fee_balance | double | No |
Payment plan fee balance (fee principal + fee tax). |
|
| total_balance | double | No |
Sum of initial_balance and fee_balance (charge + charge tax + fee + fee tax). |
|
| recurring_amount | double | No |
Specifies the recurring amount of a payment plan. |
|
| first_payment_plan_due_date | string | No |
The date of the first payment plan will be due |
|
| last_payment_plan_due_date | string | No |
The date of the last payment plan will be due |
|
| payment_plan_period_type | string | No |
Specifies the payment plan interval type. Allowable values are: M (Months), W (weeks), D (Days). Applicable if payment_plan_type = 1. |
|
| payment_plan_interval | long | No |
Specifies the payment plan interval, applicable when payment_plan_type = 0, it works jointly with payment_plan_period_type. If defined, must be less than payment_plan_length. If null, the system defaults to 1. |
|
| payment_plan_length | long | No |
Specifies the length of payment plan. For payment_plan_type = 0, the input will be used jointly with payment_plan_interval. For payment_plan_type = 1, it is the number of MPI statements that the payment plan will be part of. |
|
| lump_sum_amount | double | No |
Specifies the lump sum amount. |
|
| payment_plan_details | object | No |
Payment plan details |
|
| lump_sum_due_date | string | No |
The date of lump sum will be due |
|
| payment_transaction_id | long | No |
The unique identifier for a payment transaction |
|
| collected_amount | double | No |
The amount of due successfully collected for the created payment plan. |
|
| proc_cvv_response | string | No |
The processor return code from CVV validation |
|
| proc_avs_response | string | No |
Processor return code from address validation |
|
| proc_cavv_response | string | No |
The processors return code for security validation |
|
| proc_status_code | string | No |
The processor status code |
|
| proc_status_text | string | No |
The processors status description |
|
| proc_payment_id | string | No |
The processor payment ID |
|
| proc_auth_code | string | No |
Authorization code provided by the issuing bank |
|
| proc_merch_comments | string | No |
Additional information passed to payment processor |
|
| collection_error_code | long | No |
If a collection is attempted, returns the error code associated with the collection |
|
| collection_error_msg | string | No |
The error message associated with collection_error_code |
|
| collection_payment_method_no | long | No |
The payment method sequence no for the payment attempted during collection. |
payment_plan_details fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| seq_no | long | No |
Aria assigned sequence number of a payment plan |
|
| notify_date | string | No |
Dates when customer will be notified of a payment plan due. |
|
| due_date | string | No |
Due dates of when a payment plan sequence is due. |
|
| due_amount | double | No |
Principal portion due for this payment plan sequence (charge amount + charge tax). Excludes fee and fee tax. |
|
| fee_amount | double | No |
Fee amount due for this payment plan sequence (fee principal + fee tax). |
|
| total_due_amount | double | No |
Sum of due_amount and fee_amount for this payment plan sequence (charge + charge tax + fee + fee tax). |