Zai PayTo Agreements API

openapi: 3.2.0
info:
  title: PayTo Agreements API
  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
paths:
  /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:

        - ACTIVE -> SUSPENDED

        - ACTIVE -> CANCELLED

        - SUSPENDED -> ACTIVE (only if suspended via Zai)

        - SUSPENDED -> CANCELLED


        Only 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.


        Resuming a suspended agreement can only be performed by the party that suspended the agreement.


        Hence, 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_uuid}/recall:
    patch:
      tags:
      - PayTo Agreements
      summary: Recall PayTo Agreement
      description: "This operation is to recall a pending agreement creation/bilateral amendment authorisation request before it is approved by debtor. By default, all debtor authorization requests expire after 5 days post creation. If a custom expiry duration (anything less than 5 days) has been specified in the request via “response_requested_by” field, then this Recall API should be invoke to expire the authorisation request post the custom duration has elapsed.\n\n Example - For a use-case, if the debtor should approve/reject the agreement within 15 mins post creation, and if the debtor does not respond within 15 mins, this API should be invoked to recall the agreement creation action post 15 mins.\n\nRecall Agreement Creation - If a custom expiry duration is specified during agreement validation step, this API should be used to recall the pending agreement creation authorisation request.\n- Allows recalling agreement authorisation request only for AUPM agreement type.\n- After the recall operation is successful, the current agreement would be considered as CANCELLED and a new agreement should be created to seek the debtor’s approval again.\n\nRecall Bilateral Amendment Request - If a custom expiry duration is specified during bilateral agreement amendment, this API should be used to recall the pending amendment authorisation request.\n- Allows recalling amendment authorisation requests for both AUPM and MGCR agreement types.\n- After the recall operation is successful, the bilateral amendments are discarded and the agreement is not updated. If the changes are still needed, a new amendment request should be created to seek the debtor’s approval again.\n"
      operationId: recallAgreementAction
      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.
        '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></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.
        '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-2502</td><td>Recall request rejected: Recall action is applicable only for agreements in CREATED/ACTIVE/SUSPENDED statuses.</td></tr><tr><td>PAYT-ERR-2503</td><td>Request to recall agreement creation is already in progress. Please try again later.</td></tr><tr><td>PAYT-ERR-2504</td><td>Recall request rejected: Any bilateral amendment is not in progress for the agreement.</td></tr><tr><td>PAYT-ERR-2505</td><td>Recall request rejected: Request to recall bilateral amendment is already in progress for the agreement. Please try again later.<tr><td>PAYT-ERR-2506</td><td>Recall request rejected: Existing bilateral amendment request cannot be recalled at the moment. Please try again later.</td></tr><tr><td>PAYT-ERR-2508</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-2502
                  error_message: 'Recall request rejected: Recall action is applicable only for agreements in CREATED/ACTIVE/SUSPENDED statuses.'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallAgreementActionResponse'
        '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/{agreement_uuid}/amend:
    patch:
      tags:
      - PayTo Agreements
      summary: Amend PayTo Agreement Details
      description: '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 wil

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