Zai PayTo API

{"openapi":"3.0.1","info":{"title":"PayTo","description":"“PayTo” is a new digital payments service that allows NPP-enabled account holders to digitally pre-authorise one-off or recurring real-time payments from their bank account. This swagger document lists APIs for PayTo agreement creation, management and payment initiation. \n\n<u>**Changes in 1.4 version**</u>\n\n\n\nEnriching timestamp fields to include microseconds information - ”created_at” and ”updated_at” fields returned via our API & web hook notifications (agreement and payto payments payloads) will include microseconds in the timestamp. \n\nRevised timestamp format example - 2023-08-10 09:03:16.045622 \n\nError code updates - \n\n **Validate PayTo Agreement API:** \n- Added new error codes - PAYT-ERR-2029, PAYT-ERR-2030, PAYT-ERR-2031 \n- Removed error codes - PAYT-ERR-2026, PAYT-ERR-2024 \n\n **Amend PayTo Agreement Details API:** \n- Added new error codes - PAYT-ERR-2321, PAYT-ERR-2322 \n- Removed error codes - PAYT-ERR-2310, PAYT-ERR-2312 \n\n **Initiate PayTo Payment API:** \n- Added new error code - PAYT-ERR-2526\n\n\n<u>**Changes in 1.3 version**</u>\n\n\n**Payment Amount Validations:** \n\nZai will perform additional payment request compliance checks. This is to help minimise non-compliant payment requests. It is essential to continue to ensure PayTo payment requests are made according to the specified amounts, day/time, frequency, and with all other terms specified in the PayTo Agreement. \n\nPayment amount-related verifications will be performed for: \n- Usage and Variable Agreements: the payment requested must be within the maximum amount field and the amount field (which acts as the minimum amount field) i.e., if the agreement amount is between $50 and $75, the payment instruction amount must be within this range. \n\n Note - Consider specifying a maximum and minimum value amount, as the payment amount can differ each time. These limits may provide clarity for the end-customer and may minimise the probability of them receiving a warning message from their bank. \n- Fixed Agreements: payments initiated must match the agreed amount; i.e., if the agreement amount is $50, the payment instruction amount must also be $50 \n- Balloon Agreements: the fixed and final payment amounts will be checked. The final amount must be equal to or greater than the fixed amount. If it’s not, the payment request will be rejected. i.e., the agreement amount is $1,200 over 10 payments (9 fixed and 1 final payments) the fixed amount could be $100, and the final amount $300. \n\nRelevant error messages have also been added as part of this release around rejecting payments that are not compliant as per amount specified in the agreement.\n\n\n<u>**Changes in 1.2 version**</u>\n\n\n **New APIs:** \n- Get all PayTo Agreements for a user - This API lists all PayTo agreements associated with a particular user. If needed, the results can be filtered to list agreements for a particular status or for a particular type (AUPM/MGCR). \n- Get all PayTo Payment Initiation Requests for an agreement - This API lists all payment requests initiated for an agreement. If needed, the results can be filtered to list requests for a particular status. \n- Recall PayTo Agreement - If a custom expiry duration (anything less than 5 days) has been specified for an agreement creation/amendment request and if the debtor has not responded within the specified timeframe, this API should be used to recall such pending authorisation requests. Post successful recall, the request is considered cancelled and hence cannot be actioned by the debtor. \n\n Note - Agreement creation or Bilateral agreement amendments trigger authorisation requests waiting approval from debtor, which can be recalled via this API, if needed.\n\n **Validate PayTo Agreement API:** \n- New Optional Field: response_requested_by -> This field should be used to specify a custom expiry duration i.e. if the debtor authorisation request needs to be limited to any short duration which is less than the default duration of 5 days. \n- Updated Field Description: agreement_info.debtor_info.debtor_details.debtor_reference -> If end to end Id is not provided in the payment initiation request, then the debtor reference (if provided) in the agreement will be used as end to end identifier for the payments initiated via the agreement.\n\n **Initiate PayTo Payment API:** \n- Updated Field Description: payment_info.end_to_end_id -> If end to end Id is not provided in the payment initiation request, then the debtor reference (if provided) in the agreement will be used as end to end identifier for the payments initiated via the agreement. If debtor reference is also not available, default value “NOTPROVIDED” will set as end to end id for the payment initiation request.\n\n\n<u>**Changes in 1.1 version**</u>\n\n\n **Validate PayTo Agreement API:** \n- Support open ended agreements - For Adhoc frequency, providing point_in_time or count_per_period info is optional. \n- Reformatting debtor account number - During the agreement validation step, Zai may reformat the debtor account number as per the format expected by the payer institutions. Reformatted debtor account number can be accessed either via GET PayTo Agreement Details API after the validation step or via WAPI notification sent by Zai after successful agreement creation step.\n\n **Amend PayTo Agreement Details API:** \n- Ability to clear optional fields if needed using hyphen (-) character.\n\n **Amend PayTo Agreement Status API:** \n- Allow agreement status amendments even if a bilateral amendment is in progress. Example - If agreement details amendment is in progress, it should be possible to pause/suspend the agreement if needed.\n\n **Get PayTo Agreement Details API:** \n- New fields - Status reason code and Status reason description have been added in response. These fields will provide more details for suspended or cancelled agreements.\n\n **Get PayTo Payment Details API:** \n- New fields - Status reason code and Status reason description have been added in response. These fields will provide more details for rejected payments.\n\n **Misc:** \n- Agreement purpose codes have been elaborated to clarify the usage for each type. \n- Status descriptions returned in the GET APIs have been improved to provide more details about the current agreement status. \n- PAYT-ERR-2201, PAYT-ERR-2301 - error descriptions have been updated. \n- PAYT-ERR-2318 - added new error code along with description.\n","contact":{"name":"Zai","url":"https://developer.hellozai.com/reference/overview","email":"support@hellozai.com"},"version":"1.4-external"},"servers":[{"url":" https://au-0000.api.assemblypay.com/payto/","description":"Production server and API"},{"url":"https://sandbox.au-0000.api.assemblypay.com/payto/","description":"Sandbox (Pre-live) server and API"},{"url":"https://virtserver.swaggerhub.com/AssemblyPlatforms/PayTo/1.4-external","description":"SwaggerHub API Auto Mocking"}],"tags":[{"name":"PayTo Agreements","description":"Agreement Management APIs"},{"name":"PayTo Payments","description":"Payment Initiation APIs"}],"paths":{"/agreements/{agreement_uuid}/payment_requests/initiate":{"post":{"tags":["PayTo Payments"],"summary":"Initiate PayTo Payment","description":"This endpoint is to initiate a payment to collect funds from the debtor's account or to retry if the previous payment collection request was rejected due to valid business reasons.\nThis API should be invoked strictly as per the terms and conditions established in the agreement to avoid payment claims. Even the retries should be attempted as per the agreement terms and conditions.\n\n Payment initiation request statuses -\n- PENDING_PAYMENT_INITIATION - when the payment initiation request has been accepted for processing \n- PAYMENT_INITIATED - when the payment initiation request is being processed \n- PAYMENT_INITIATION_COMPLETED - when the payment initiation request is cleared and settled successfully. Funds can be expected in the user's wallet soon \n- PAYMENT_INITIATION_REJECTED - when the payment initiation request is rejected for processing due to validation, funds not available in the debtor's account or any other \nbusiness reason. A retry can be performed in such scenarios \n\nIf the payment collection request  has been rejected due to valid business reasons (example - insufficient funds), a retry can be attempted for the same.\n\nPayment_request_uuid generated will be the same for the payment collection request and all subsequent retry attempts, however, instruction_id differs for each.\n\nNote - If Payment initiated on the agreement validity end date fails, it will not be possible to retry or initiate again on the following date as the agreement will be marked as CANCELLED automatically after the agreement validity_end_date. Hence, it is recommended to initiate the last payment few days before the agreement validity end date to cater for retries needed if any.","operationId":"initiatePaymentRequest","parameters":[{"name":"agreement_uuid","in":"path","required":true,"schema":{"type":"string","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentRequest"}}},"required":true},"responses":{"401":{"description":"Unauthorised \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1000</td><td>Invalid or missing authorisation token.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"403":{"description":"Forbidden \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1001</td><td>PayTo feature not available.</td></tr><tr><td>PAYT-ERR-1002</td><td>Request rejected: User associated with the agreement is not active.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"400":{"description":"Bad Request \n \n <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1050</td><td>Mandatory info missing: [FieldName] cannot be null or empty.</td></tr><tr><td>PAYT-ERR-1051</td><td>Invalid Data: [FieldName] provided is invalid.</td></tr><tr><td>PAYT-ERR-1052</td><td>Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].</td></tr><tr><td>PAYT-ERR-1053</td><td>Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].</td></tr><tr><td>PAYT-ERR-1054</td><td>Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].</td></tr><tr><td>PAYT-ERR-1057</td><td>Unrecognized Field: [FieldName] is not a valid field.</td></tr><tr><td>PAYT-ERR-1058</td><td>Invalid Request: request provided is not well-formatted.</td></tr><tr><td>PAYT-ERR-2501</td><td>Payments can be initiated for ACTIVE agreements only.</td></tr><tr><td>PAYT-ERR-2502</td><td>Payments can be initiated only within the agreement validity period.</td></tr><tr><td>PAYT-ERR-2510</td><td>unique_superannuation_code is mandatory along with unique_superannuation_identification.</td></tr><tr><td>PAYT-ERR-2512</td><td>Payment requested for this agreement has been cleared and settled already. Please check the latest status before requesting again.</td></tr><tr><td>PAYT-ERR-2513</td><td>Request rejected: Exceeded the maximum retry attempts allowed for the agreement.</td></tr><tr><td>PAYT-ERR-2514</td><td>Request rejected: Please ensure the payment is retried within valid period.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2501","error_message":"Payments can be initiated for ACTIVE agreements only."},{"error_code":"PAYT-ERR-2502","error_message":"Payments can be initiated only within the agreement validity period."}]}}}},"404":{"description":"Not Found \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2500</td><td>Agreement with provided uuid does not exist.</td></tr><tr><td>PAYT-ERR-2511</td><td>Payment request with provided uuid does not exist.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2500","error_message":"Agreement with provided uuid does not exist."}]}}}},"409":{"description":"Conflict \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2516</td><td>A payment is already in progress for the agreement. Please try again if the current payment request is unsuccessful.</td></tr><tr><td>PAYT-ERR-2517</td><td>Invalid request: Payment has been rejected already and cannot be retried. Please check reason code details.</td></tr><tr><td>PAYT-ERR-2518</td><td>For migrated agreements, payment request with value exceeding $5,000 AUD cannot be initiated. Please consider splitting the amount in multiple requests OR create a new agreement if the payment value needs to be beyond $5,000 AUD in a single request.</td></tr><tr><td>PAYT-ERR-2519</td><td>For the last payment, the instructed amount in the payment should match the last payment terms in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2520</td><td>For the first payment, the instructed amount in the payment should match the first payment terms in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2521</td><td>For FIXE agreement type, the instructed amount in the payment should match the payment amount stated in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2522</td><td>For BALN agreement type, the instructed amount in the payment should match the payment amount stated in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2523</td><td>For BALN agreement types, the instructed amount in the payment should be either the same or greater than the payment amount stated in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2524</td><td>For USGB/VARI agreement types, the instructed amount in the payment should be within the payment amount (min) and maximum amount range stated in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2525</td><td>For USGB/VARI agreement types, the instructed amount in the payment should be either the same or greater than the payment amount stated in the agreement. Please initiate payments as per the agreement’s payment terms.</td></tr><tr><td>PAYT-ERR-2526</td><td>For USGB/VARI agreement types, the instructed amount in the payment should be either the same or less than the maximum amount stated in the agreement. Please initiate payments as per the agreement's payment terms.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2516","error_message":"A payment is already in progress for the agreement. Please try again if the current payment request is unsuccessful."}]}}}},"500":{"description":"Internal Server Error \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1003</td><td>An error occurred processing your request. Please try again.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1003","error_message":"An error occurred processing your request. Please try again."}]}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/agreements/{agreement_uuid}/create":{"post":{"tags":["PayTo Agreements"],"summary":"Create PayTo Agreement","description":"This operation creates the agreement with NPPA and hence must be invoked only after validating the agreement via the “Validate PayTo Agreement” operation.\n\n It should be invoked immediately once the agreement has been validated successfully and resolved PayID details are confirmed with the user.\n\n Agreement Creation will be successful only if it is performed within 5 minutes post successful validation.\n\n Post successful creation, agreement id (generated by NPPA) which uniquely identifies the agreement will be notified. \n\n Note - AUPM agreements will be ACTIVE only post debtor authorization. By default (if custom expiry duration is not provided via response_requested_by field), debtor will have 5 days to authorise the agreement, post which the authorization request will expire automatically and the agreement will be marked as CANCELLED.\n MGCR agreements will be ACTIVE immediately post creation however, payments can be initiated only after 5 calendar days.","operationId":"createAgreement","parameters":[{"name":"agreement_uuid","in":"path","required":true,"schema":{"type":"string","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}}],"responses":{"401":{"description":"Unauthorised \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1000</td><td>Invalid or missing authorisation token.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"403":{"description":"Forbidden \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1001</td><td>PayTo feature not available.</td></tr><tr><td>PAYT-ERR-1002</td><td>Request rejected: User associated with the agreement is not active.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"404":{"description":"Not Found \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2100</td><td>Agreement should be in VALIDATED state for creation.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2100","error_message":"Agreement should be in VALIDATED state for creation."}]}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgreementResponse"}}}},"400":{"description":"Bad Request \n \n <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2102</td><td>Invalid format for url param: agreement_uuid.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2102","error_message":"Invalid format for url param: agreement_uuid."}]}}}},"410":{"description":"Resource Unavailable \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2101</td><td>Agreement creation is allowed only within a limited time period post validation. Please validate the agreement details again.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2101","error_message":"Agreement creation is allowed only within a limited time period post validation. Please validate the agreement details again."}]}}}},"500":{"description":"Internal Server Error \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1003</td><td>An error occurred processing your request. Please try again.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1003","error_message":"An error occurred processing your request. Please try again."}]}}}}},"security":[{"bearerAuth":[]}]}},"/agreements/validate":{"post":{"tags":["PayTo Agreements"],"summary":"Validate PayTo Agreement","description":"Validate PayTo agreement details before creation. This operation must be invoked first, followed by the “Create PayTo Agreement” operation.\n\n This operation validates the details of the agreements along with ensuring the debtor and creditor are NPP and PayTo reachable before the actual agreement creation with NPPA.\n\n PayID details provided for the debtor are also resolved as part of this operation. Customers should share the resolved PayID details with their users for confirmation before the actual agreement creation.\n\n Post successful validation, agreement UUID is returned in the response which uniquely identifies the agreement. This UUID should be used in subsequent API calls for that particular agreement.\n\n Note - Zai may reformat the debtor account number if it is not as per the format expected by payer institutions. Reformatted debtor account number can be accessed either via GET PayTo Agreement Details API after the validation step or via WAPI notification sent by Zai after successful agreement creation step.","operationId":"validateAgreement","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAgreementRequest"}}},"required":true},"responses":{"401":{"description":"Unauthorised \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1000</td><td>Invalid or missing authorisation token.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateAgreementResponse"}}}},"500":{"description":"Internal Server Error \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1003</td><td>An error occurred processing your request. Please try again.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1003","error_message":"An error occurred processing your request. Please try again."}]}}}},"400":{"description":"Bad Request \n \n <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1050</td><td>Mandatory info missing: [FieldName] cannot be null or empty.</td></tr><tr><td>PAYT-ERR-1051</td><td>Invalid Data: [FieldName] provided is invalid.</td></tr><tr><td>PAYT-ERR-1052</td><td>Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].</td></tr><tr><td>PAYT-ERR-1053</td><td>Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].</td></tr><tr><td>PAYT-ERR-1054</td><td>Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].</td></tr><tr><td>PAYT-ERR-1057</td><td>Unrecognized Field: [FieldName] is not a valid field.</td></tr><tr><td>PAYT-ERR-1058</td><td>Invalid Request: request provided is not well-formatted.</td></tr><tr><td>PAYT-ERR-2001</td><td>Either description or short_description should be provided.</td></tr><tr><td>PAYT-ERR-2002</td><td>Response_Requested_By date must be a future date and less than 5 days.</td></tr><tr><td>PAYT-ERR-2004</td><td>PayID details are not supported for migrated agreements.</td></tr><tr><td>PAYT-ERR-2005</td><td>validity_start_date should be either current date OR future date.</td></tr><tr><td>PAYT-ERR-2006</td><td>validity_end_date should be greater than OR same as validity_start_date.</td></tr><tr><td>PAYT-ERR-2008</td><td>validity_end_date should not be provided if agreement should be auto-renewed.</td></tr><tr><td>PAYT-ERR-2009</td><td>account_details in the request are invalid as per the account_type provided.</td></tr><tr><td>PAYT-ERR-2010</td><td>Either account (bsb/account number) or PayID details should be provided.</td></tr><tr><td>PAYT-ERR-2011</td><td>Invalid PayID format for the PayID type provided.</td></tr><tr><td>PAYT-ERR-2013</td><td>debtor_id_type is mandatory along with debtor_id.</td></tr><tr><td>PAYT-ERR-2014</td><td>Invalid debtor_id_type for the debtor_type provided.</td></tr><tr><td>PAYT-ERR-2015</td><td>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.</td></tr><tr><td>PAYT-ERR-2016</td><td>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.</td></tr><tr><td>PAYT-ERR-2018</td><td>payment_amount should be less than maximum amount.</td></tr><tr><td>PAYT-ERR-2019</td><td>Amount provided in last_payment_info should be less than or equal to maximum amount.</td></tr><tr><td>PAYT-ERR-2020</td><td>Amount provided in first_payment_info should be less than or equal to maximum amount.</td></tr><tr><td>PAYT-ERR-2021</td><td>Date provided in last_payment_info should be same OR after the date provided in first_payment_info.</td></tr><tr><td>PAYT-ERR-2025</td><td>Incorrect value provided for either of these fields - frequency, point_in_time, count_per_period. The combination provided should be valid.</td></tr><tr><td>PAYT-ERR-2027</td><td>Active direct debit agreement which needs to be migrated does not exist for the user.</td></tr><tr><td>PAYT-ERR-2028</td><td>Response_Requested_By is applicable only for AUPM agreements with 'ATTENDED' priority type.</td></tr><tr><td>PAYT-ERR-2029</td><td>For FIXE/BALN type of agreements, specifying payment amount is mandatory.</td></tr><tr><td>PAYT-ERR-2030</td><td>For FIXE/BALN type of agreements, specifying maximum amount is not applicable.</td></tr><tr><td>PAYT-ERR-2031</td><td>Invalid Data: Please provide info for all parameters under agreement_info.payment_terms.maximum_amount_info</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2001","error_message":"Either 'description' or 'short_description' should be provided."},{"error_code":"PAYT-ERR-2005","error_message":"validity_start_date must be future dated."}]}}}},"403":{"description":"Forbidden \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1001</td><td>PayTo feature not available.</td></tr><tr><td>PAYT-ERR-1004</td><td>User with provided user_external_id does not exist.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"404":{"description":"Not Found \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2000</td><td>Active user with provided user_external_id does not exist.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2000","error_message":"Active user with provided user_external_id does not exist."}]}}}}},"security":[{"bearerAuth":[]}]}},"/agreements/{agreement_uuid}/status":{"patch":{"tags":["PayTo Agreements"],"summary":"Amend PayTo Agreement Status","description":"Amend Status of a particular agreement via its UUID. Below status amends are possible via this API:\n- ACTIVE -> SUSPENDED\n- ACTIVE -> CANCELLED\n- SUSPENDED -> ACTIVE (only if suspended via Zai)\n- SUSPENDED -> CANCELLED\n\nOnly one status amendment is allowed at any given point of time. Example - If a request to suspend the agreement is already in progress, another status change request will not be accepted until the first completes.\n\nResuming a suspended agreement can only be performed by the party that suspended the agreement.\n\nHence, moving the agreement from SUSPENDED to ACTIVE will be accepted only if the Suspension was performed via Zai. CANCELLED is final agreement status and hence is irreversible.","operationId":"amendAgreementStatus","parameters":[{"name":"agreement_uuid","in":"path","required":true,"schema":{"type":"string","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AmendAgreementStatusRequest"}}},"required":true},"responses":{"401":{"description":"Unauthorised \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1000</td><td>Invalid or missing authorisation token.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"409":{"description":"Conflict \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2201</td><td>A status amendment for this agreement is already in progress. Please try again later.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2201","error_message":"An amendment for this agreement is already in progress. Please try again later."}]}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AmendAgreementStatusResponse"}}}},"400":{"description":"Bad Request \n \n <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></r><tr><td>PAYT-ERR-1050</td><td>Mandatory info missing: [FieldName] cannot be null or empty.</td></tr><tr><td>PAYT-ERR-1051</td><td>Invalid Data: [FieldName] provided is invalid.</td></tr><tr><td>PAYT-ERR-1052</td><td>Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].</td></tr><tr><td>PAYT-ERR-1054</td><td>Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].</td></tr><tr><td>PAYT-ERR-1057</td><td>Unrecognized Field: [FieldName] is not a valid field.</td></tr><tr><td>PAYT-ERR-1058</td><td>Invalid Request: request provided is not well-formatted.</td></tr><tr><td>PAYT-ERR-2202</td><td>Amendment request rejected: Invalid status change requested.</td></tr><tr><td>PAYT-ERR-2203</td><td>Reason code is mandatory while suspending or cancelling an agreement.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2202","error_message":"Amendment request rejected: Invalid status change requested."},{"error_code":"PAYT-ERR-2203","error_message":"Reason code is mandatory while suspending or cancelling an agreement."}]}}}},"403":{"description":"Forbidden \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1001</td><td>PayTo feature not available.</td></tr><tr><td>PAYT-ERR-1002</td><td>Request rejected: User associated with the agreement is not active.</td></tr><tr><td>PAYT-ERR-2204</td><td>Agreement can be resumed only by the same party who suspended it.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"500":{"description":"Internal Server Error \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1003</td><td>An error occurred processing your request. Please try again.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1003","error_message":"An error occurred processing your request. Please try again."}]}}}},"404":{"description":"Not Found \n<table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2200</td><td>Agreement with provided uuid does not exist.</td></tr></table>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2200","error_message":"Agreement with provided uuid does not exist."}]}}}}},"security":[{"bearerAuth":[]}]}},"/agreements/{agreement

# --- truncated at 32 KB (227 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zai/refs/heads/main/openapi/zai-payto.json