Amend PayTo Agreement Details

patch

https://au-0000.api.assemblypay.com/payto/agreements/{agreement_uuid}/amend

Amend details of a particular agreement via its UUID. There are two types of amendments possible via this operation:

Unilateral amendments - which does not need debtor approval and will be effective immediately
Bilateral amendments - which does require debtor approval and will be effective post debtor authorisation

Optional fields can also be cleared via an amend request if needed. Passing an hyphen(-) character for any optional field would indicate its value needs to be cleared.

Either unilateral or bilateral amendments will be accepted in an amendment request. Both types of amendments cannot be provided in a single request.

At any given point of time, only a single unilateral or a single bilateral amendment will be allowed. Example - If a bilateral amendment is already in progress, another bilateral amendment request will not be accepted until the first completes.

Unilateral details that can be amended:

description
short_description
creditor_info
payment_initiator_info

Bilateral details that can be amended:

validity_end_date
transfer_arrangement
automatic_renewal
payment_terms - 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.

Note - Bilateral amendments will be effective only post debtor authorization. Debtor should authorize the amendments within 5 days (default duration) or within the custom expiry duration (response_requested_by) specified in the amendment request.

Path Params

agreement_uuid

string

required

Body Params

priority

string

enum

required

Identifies the arrangement (attended or unattended).

Priority of the agreement amendment authorisation notification to be sent to the user for approval.

Code	Description
ATTENDED	If the marketplace wants the debtor user to be notified about the agreement amendment authorisation action immediately, the priority should be set as Attended.
UNATTENDED	If the marketplace wants the debtor user to be notified about the agreement amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended.

Allowed:

response_requested_by

string

A date expressed in the YYYY-MM-DD'T'HH:mm:ss[.SSS][.SS][.S]'Z' format and in Australia timezone.

This field can be used to specify a custom expiry duration for the authorisation request pending debtor’s approval. Any duration which is less than the default & max duration of 5 days will be accepted. Example - If you want the debtor to approve the changes proposed on the agreement within 15 mins post creation, mention the duration in this field accordingly. However, post the duration (after 15 mins), you would need to invoke the Recall API to expire this authorisation request.

unilateral_amendments

object

Specific characteristics about the unilateral fields. Specifies fields for which amendments are effective immediately and do not require debtor authorisation.

Property descriptions:

description - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the description will not be modified as part of the amendment. Set this property to "-" to indicate that the description is to be cleared on the agreement.
short_description - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the short description will not be modified as part of the amendment. Set this property to "-" to indicate that the short description is to be cleared on the agreement.
creditor_info - Creditor Details. If this property is omitted then the creditor information will not be modified as part of the amendment.
payment_initiator_info - Initiating party details. If this property is omitted then the payment initiator information will not be modified as part of the amendment.

bilateral_amendments

object

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.

Responses

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.

Error Code	Error Message
PAYT-ERR-1000	Invalid or missing authorisation token.

Error Code	Error Message
PAYT-ERR-1001	PayTo feature not available.
PAYT-ERR-1002	Request rejected: User associated with the agreement is not active.

Error Code	Error Message
PAYT-ERR-2300	Agreement with provided uuid does not exist.

Error Code	Error Message
PAYT-ERR-2301	A bilateral amendment for this agreement is already in progress. Please try again later.
PAYT-ERR-2319	A unilateral amendment for this agreement is already in progress. Please try again later.

202Accepted

401Unauthorised Error CodeError MessagePAYT-ERR-1000Invalid or missing authorisation token.

403Forbidden Error CodeError MessagePAYT-ERR-1001PayTo feature not available.PAYT-ERR-1002Request rejected: User associated with the agreement is not active.

404Not Found Error CodeError MessagePAYT-ERR-2300Agreement with provided uuid does not exist.

409Conflict Error CodeError MessagePAYT-ERR-2301A bilateral amendment for this agreement is already in progress. Please try again later.PAYT-ERR-2319A unilateral amendment for this agreement is already in progress. Please try again later.

500Internal Server Error Error CodeError MessagePAYT-ERR-1003An error occurred processing your request. Please try again.