Identifies the arrangement (attended or unattended).
Priority of the agreement amendment authorisation notification to be sent to the user for approval.Specifies an alphanumeric string with a length of 4 characters.
Code indicating the identification type of the initiator.For example in the case of a private individual; passport, driver licence, or 100 point check, or in the case of an organisation; LEI, ACN, ABN| Code | Description |
| ARNU | Alien Registration Number |
| CCPT | Passport Number |
| CUST | Customer Identification Number |
| DRLC | Drivers License Number |
| EMPL | Employee Identification Number |
| NIDN | National Identity Number |
| SOSE | Social Security Number |
| TXID | Tax Identification Number |
| BANK | Bank Party Identification |
| CBID | Central Bank Identification Number |
| CHID | Clearing Identification Number |
| CINC | Certificate Of Incorporation Number |
| COID | Country Identification Code |
| DUNS | Data Universal Numbering System |
| GS1G | GS1GLN Identifier |
| SREN | SIREN |
| SRET | SIRET |
| AUBN | Australian Business Number (ABN) |
| AUCN | Australian Company Number (ACN) |
| LEIN | Legal Entity Identification (LEI) |
- `initiator_legal_name` string — Specifies a character string with a maximum length of 140 ASCII printable characters. Name by which the initiator is legally known.
- `initiator_name` string — Specifies a character string with a maximum length of 140 ASCII printable characters. Name by which the initiator is known and which is usually used to identify them.
- `bilateral_amendments` BilateralAmendments — Specific characteristics about the bilateral fields. Specifies fields for which amendments are effective only post debtor authorisation. **Property descriptions**: - **automatic_renewal** - Automatic renewal of an agreement at the end of the defined period. An example of an automatically renewing agreement might be a gym membership that automatically rolls over, or a phone contract. If this property is omitted then the automatic renewal will not be modified as part of the amendment. - **validity_end_date** - Validity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date. If this property is omitted then the validity end date will not be modified as part of the amendment. Set this property to "-" to indicate that the validity end date is to be cleared on the agreement. Note - Clearing validity end date requires to provide the auto-renewal property (automatic_renewal=true) - **transfer_arrangement** - Additional details about the agreement terms with consideration to the transfer of items/goods/services. Examples might include payment of shares, transfer of property, or fulfilment of a purchase order. If this property is omitted then the transfer arrangement will not be modified as part of the amendment. Set this property to "-" to indicate that the transfer arrangement is to be cleared on the agreement. - **payment_terms** - Set of characteristics detailing agreement payment information. Payment terms like payment_amount_info, first_payment_info, last_payment_info, maximum_amount_info and point_in_time can be amended at any point; however, frequency and count_per_period can be amended only if no payments have been requested for the agreement yet. If this property is omitted then the payment information will not be modified as part of the amendment. The following rules apply to this structure: - **ValidityEndDateRule:** validity_end_date should be greater than OR same as validity_start_date. - **AutomaticExtensionRule:** validity_end_date should not be provided if agreement should be auto-renewed.
- `automatic_renewal` boolean — Indicates a "Yes" or "No" type of automatic renewal. Automatic renewal of an agreement at the end of the defined period. An example of an automatically renewing agreement might be a gym membership that automatically rolls over, or a phone contract. If this property is omitted then the automatic renewal will not be modified as part of the amendment.
- `validity_end_date` string, yyyy-MM-dd — A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.This representation is defined in "XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October 2004" which is aligned with ISO 8601. Validity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date. If this property is omitted then the validity end date will not be modified as part of the amendment. Set this property to "-" to indicate that the validity end date is to be cleared on the agreement. Note - Clearing validity end date requires to provide the auto-renewal property (automatic_renewal=true)
- `transfer_arrangement` string — Specifies a character string with a maximum length of 140 characters. Additional details about the agreement terms with consideration to the transfer of items/goods/services. Examples might include payment of shares, transfer of property, or fulfilment of a purchase order. If this property is omitted then the transfer arrangement will not be modified as part of the amendment. Set this property to "-" to indicate that the transfer arrangement is to be cleared on the agreement.
- `payment_terms` AmendPaymentTermsDetails — Specifies payment terms for the agreement i.e. amount that can be debited per payment, min/max amounts, first and last payment terms etc. All the payments initiated should be as per agreement terms. It is very important to ensure the payments initiated **DO NOT BREACH** the agreement terms and conditions - this could lead to: Agreement claims by debtor/payer for an amount greater than the actual payment amount **Property descriptions**: - **payment_amount_info** - Specifies info around the amount type for the agreement (example: Fixed or Usage based amounts etc), amount that can be debited from the account depending on the type, and the currency in which the payments can be initiated. - **first_payment_info** - If the payment arrangement is such that the initial payment amount differs from the expected "regular" or "recurring" payment, then the first payment info can be specified in this field. Examples: Establishment fees are part of the first payment only. - **last_payment_info** - If the payment arrangement is such that there is a known final payment amount that differs from the expected "regular" or "recurring" payment, then the last payment info can be specified in this field. - **maximum_amount** - Represents the maximum amount that may be debited in any single payment initiation. - **payment_executed_not_before_time** - Specifies the Australia Sydney time after which payments may be initiated on the execution day (according to the frequency and other payment terms). Example - Payroll scenario, where the employer requests to not initiate payrolls until a particular time to ensure funds are available for the payment to occur. Setting this property to "-" indicates that the time is to be cleared on the agreement.| frequency | point_in_time | count_per_period |
| ADHOC | N/A | Valid non decimal numeric value, greater than zero |
| INTRDY | 01 to 24 | Not present |
| INTRDY | Not present | Valid non decimal numeric value, greater than zero |
| DAILY | 01 to 24 | Not present |
| DAILY | Not present | Valid non decimal numeric value, greater than zero |
| DAILY | N/A | Valid non decimal numeric value, greater than zero |
| WEEKLY | 01 to 07 | Not present |
| WEEKLY | Not present | Valid non decimal numeric value, greater than zero |
| WEEKLY | N/A | Valid non decimal numeric value, greater than zero |
| FRTNLY | 01 to 14 | Not present |
| FRTNLY | Not present | Valid non decimal numeric value, greater than zero |
| FRTNLY | N/A | Valid non decimal numeric value, greater than zero |
| MNTHLY | 01 to 28 | Not present |
| MNTHLY | Not present | Valid non decimal numeric value, greater than zero |
| QURTLY | 01 to 03 | Not present |
| QURTLY | Not present | Valid non decimal numeric value, greater than zero |
| HFYRLY | 01 to 06 | Not present |
| HFYRLY | Not present | Valid non decimal numeric value, greater than zero |
| YEARLY | 01 to 12 | Not present |
| YEARLY | Not present | Valid non decimal numeric value, greater than zero |
**Payment amount types rules:** Specific type of payment amount.
Depending on the use-case for which the payment arrangement is being made, an appropriate amount type should be selected for the agreement as this defines the payments that can be initiated via the agreement.
| Code | Name | Description |
| FIXE | Fixed | Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement. |
| BALN | Balloon | Payments should be initiated for fixed amounts with large final payment amount i.e. for all the payments except the last, amount specified in the payment instruction must match the “amount” stated in the agreement. The last payment can be different and as per terms mentioned in the last payment amount fields (if specified).
Note - This type is currently not supported. |
| USGB | UsageBased | If the amount for the payment varies with usage (example - electricity bill), it is recommended to specify a max amount. If a value is specified in the “amount” field, this would be considered as base/min amount to be paid for each payment. Payments should be initiated as per agreement terms i.e. the amount specified in the payment instruction should be within the “amount” (min) and “maximum amount” stated in the agreement. |
| VARI | Variable | If the amount for the payment varies each time (example - grocery purchase billing), it is recommended to specify a max amount. If a value is specified in the “amount” field, this would be considered as base/min amount to be paid for each payment. Payments should be initiated as per agreement terms i.e. the amount specified in the payment instruction should be within the “amount” (min) and “maximum amount” stated in the agreement. |
- `first_payment_info` AmendFirstPaymentInformation — If the payment arrangement is such that the initial payment amount differs from the expected "regular" or "recurring" payment, then the first payment info can be specified in this field. Examples: Establishment fees are part of the first payment only. **Property descriptions**: - **amount** - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment. - **currency** - Currency of the payment to debit the account. - **date** - If the payment arrangement being established specifies the first date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to "-" indicates that the date is to be cleared on the agreement.
- `amount` string — Specifies an amount in cents. - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.
- `currency` '{AUD}' — A code allocated to a currency by a Maintenance Agency under an international identification scheme as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Currency of the payment to debit the account.
- `date` string, yyyy-MM-dd — A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. If the payment arrangement being established specifies the first date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to "-" indicates that the date is to be cleared on the agreement.
- `last_payment_info` AmendLastPaymentInformation — If the payment arrangement is such that there is a known final payment amount that differs from the expected "regular" or "recurring" payment, then the last payment info can be specified in this field. **Property descriptions**: - **amount** - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment. - **currency** - Currency of the payment to debit the account. - **date** - If the payment arrangement being established specifies the date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to "-" indicates that the date is to be cleared on the agreement.
- `amount` string — Specifies an amount in cents. - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.
- `currency` '{AUD}' — A code allocated to a currency by a Maintenance Agency under an international identification scheme as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Currency of the payment to debit the account.
- `date` string, yyyy-MM-dd — A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. If the payment arrangement being established specifies the date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to "-" indicates that the date is to be cleared on the agreement.
- `maximum_amount_info` AmendMaximumAmountInformation — Represents the maximum amount that may be debited in any single payment initiation. **Property descriptions**: - **amount** - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment. - **currency** - Currency of the payment to debit the account.
- `amount` string — Specifies an amount in cents. - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment. - For BALN type of agreements, as the amount to be debited is fixed for all payments (except the last/final payment which can be for a larger amount), this field indicates the amount to be debited for all payments except the final/last. - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.
- `currency` '{AUD}' — A code allocated to a currency by a Maintenance Agency under an international identification scheme as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". Currency of the payment to debit the account.
- `payment_executed_not_before_time` string — Specifies a time in the format HH:mm:ssZ. Specifies the Australia Sydney time after which payments may be initiated on the execution day (according to the frequency and other payment terms). Example - Payroll scenario, where the employer requests to not initiate payrolls until a particular time to ensure funds are available for the payment to occur. Setting this property to "-" indicates that the time is to be cleared on the agreement. *Note - This parameter is currently not supported.*
- `point_in_time` string — Specifies a number in string format up to two digit. Qualifies the frequency in terms of an exact point in time or moment within the specified period. The granularity of point in time is a subdivision of frequency. Setting this property to "-" indicates that the point in time is to be cleared on the agreement. Note - Specifying a point_in_time for payments is applicable only for "Monthly" frequency.| Frequency | Description |
| Adhoc | Point in time is not applicable |
| IntraDay | Point In Time = hour within day (1-24)) |
| Daily | Point In Time = hour within day (1-24) |
| Weekly | Point In Time = day of week (1-7) |
| Fortnightly | Point In Time = day within fortnight (1-14) |
| Monthly | Point In Time = day of month (1-28) |
| Quarterly | Point In Time = day of month within the quarter of year (1-4) |
| HalfYearly | Point In Time = day of month within the half of the year (1-6) |
| Yearly | Point In Time = month within the year (1-12) |
- `count_per_period` string — Specifies a valid non decimal numeric value. Defines the number of authorised expected payments that are to be initiated according to the frequency. Example - With Frequency = Adhoc, Count Per Period can be used to specify a total number of allowed initiations. Setting this property to "-" indicates that the count per period is to be cleared on the agreement.
- `frequency` 'ADHOC' | 'INTRDY' | 'DAILY' | 'WEEKLY' | 'FRTNLY' | 'MNTHLY' | 'QURTLY' | 'HFYRLY' | 'YEARLY' — Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement.
*Note - Intraday, Quarterly, Half Yearly and Yearly payment frequencies are currently not supported.* | Code | Name | Description |
| ADHOC | Adhoc | Event takes place on request or as necessary. |
| INTRDY | IntraDay | Event takes place several times a day. |
| DAILY | Daily | Event takes place every day. |
| WEEKLY | Weekly | Event takes place once a week. |
| FRTNLY | Fortnightly | Event takes place every two weeks. |
| MNTHLY | Monthly | Event takes place every month or once a month. |
| QURTLY | Quarterly | Event takes place every three months or four times a year. |
| HFYRLY | HalfYearly | Event takes place every six months or two times a year. |
| YEARLY | Yearly | Event takes place every year or once a year. |
## Response `202`
Accepted
- AmendAgreementDetailsResponse — Specific characteristics of an agreement details amendment response.
- `agreement_uuid` string — Unique agreement identifier.
- `agreement_id` string — Unique agreement identifier generated by NPPA.
- `status` 'SUSPENDED' | 'ACTIVE' — Current status of the agreement before amendment.
| Error Code | Error Message |
| PAYT-ERR-1050 | Mandatory info missing: [FieldName] cannot be null or empty. |
| PAYT-ERR-1051 | Invalid Data: [FieldName] provided is invalid. |
| PAYT-ERR-1052 | Invalid Data: [FieldName] provided should contain any of the values [Acceptable values]. |
| PAYT-ERR-1053 | Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat]. |
| PAYT-ERR-1054 | Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength]. |
| PAYT-ERR-1057 | Unrecognized Field: [FieldName] is not a valid field. |
| PAYT-ERR-1058 | Invalid Request: request provided is not well-formatted. |
| PAYT-ERR-2002 | Response_Requested_By date must be a future date and less than 5 days. |
| PAYT-ERR-2019 | Amount provided in last_payment_info should be less than or equal to maximum amount. |
| PAYT-ERR-2020 | Amount provided in first_payment_info should be less than or equal to maximum amount. |
| PAYT-ERR-2302 | Either unilateral or bilateral amendments can be requested. |
| PAYT-ERR-2303 | Details can be amended for 'ACTIVE' or 'SUSPENDED' agreements only. |
| PAYT-ERR-2304 | Either description or short_description is mandatory for an agreement. |
| PAYT-ERR-2305 | validity_end_date should not be provided if agreement should be auto-renewed. |
| PAYT-ERR-2306 | validity_end_date should be greater than OR same as validity_start_date. |
| PAYT-ERR-2307 | Date provided in last_payment_info should be same OR after the date provided in first_payment_info. |
| PAYT-ERR-2308 | Date provided in first_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date. |
| PAYT-ERR-2309 | Date provided in last_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date. |
| PAYT-ERR-2311 | Incorrect value provided for either of these fields - frequency, point_in_time, count_per_period. The combination provided should be valid. |
| PAYT-ERR-2313 | Amount provided in last_payment_info should be less than or equal to maximum amount. |
| PAYT-ERR-2314 | Amount provided in first_payment_info should be less than or equal to maximum amount. |
| PAYT-ERR-2315 | payment_amount should be less than or equal to maximum amount. |
| PAYT-ERR-2316 | Invalid Request: At least one field should be provided for amendment. |
| PAYT-ERR-2318 | Invalid Request: Values provided for few fields is same as existing. Please provide correct info for amendment. |
| PAYT-ERR-2319 | A unilateral amendment for this agreement is already in progress. Please try again later. |
| PAYT-ERR-2320 | Response_Requested_By is applicable only for bilateral amendment requests with 'ATTENDED' priority type. |
| PAYT-ERR-2321 | For FIXE/BALN type of agreements, specifying payment amount is mandatory. |
| PAYT-ERR-2323 | Invalid Data: Payment frequency [frequency] is not enabled for your platform. If you require this payment frequency to be enabled for your business use-case, kindly get in touch with Zai support. |
| PAYT-ERR-2324 | Invalid Data: Payment parameter '[payment_parameter]' provided is not enabled for your platform. If you require this parameter to be enabled for your business use-case, kindly get in touch with Zai support. |
| PAYT-ERR-2325 | Invalid Data: Payment amount type [amount_type] is not enabled for your platform. If you require this payment amount type to be enabled for your business use-case, kindly get in touch with Zai support. |
| PAYT-ERR-2328 | Payment frequency cannot be modified if payments have already been requested as per current frequency. Please create a new agreement with the required frequency and cancel the existing agreement. |
| PAYT-ERR-2329 | Payment parameter - count_per_period cannot be modified if payments have already been requested as per current frequency. Please create a new agreement with the required parameters and cancel the existing agreement. |
| PAYT-ERR-2330 | Cannot amend payment parameter types (count_per_period v/s point_in_time) once payments have already been requested as per current frequency. Please create a new agreement with the required parameters and cancel the existing agreement. |
- `401` — Unauthorised