---
title: "Validate PayTo Agreement"
method: POST
path: "/agreements/validate"
tags: ["PayTo Agreements"]
---

# Validate PayTo Agreement

`POST /agreements/validate`

Validate PayTo agreement details before creation. This operation must be invoked first, followed by the “Create PayTo Agreement” operation.

 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.

 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.

 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.

 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.

## Request body

- ValidateAgreementRequest — Definition of the agreement validation request data. **Property descriptions**: - **user_external_id** - Unique id of the user (created via [Create User](https://developer.hellozai.com/reference/createuser) API) with whom the agreement should be associated with. - **priority** - Priority of the agreement creation/amendment authorisation notification to be sent to the user for approval. Supported values: - Attended - If the marketplace wants the debtor user to be notified about the agreement creation/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 creation/amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended. - **response_requested_by** - 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 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. - **agreement_info** - Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor.
  - `user_external_id` string, required — Specifies a character string Unique id of the user (created via Create User API) with whom the agreement should be associated with.
  - `priority` 'ATTENDED' | 'UNATTENDED', required — <p>Priority of the agreement creation/amendment authorisation notification to be sent to the user for approval.</p> <table><tr><td>Code</td><td>Description</td></tr><tr><td>ATTENDED</td><td>If the marketplace wants the debtor user to be notified about the agreement creation/amendment authorisation action immediately, the priority should be set as Attended.</td></tr><tr><td>UNATTENDED</td><td>If the marketplace wants the debtor user to be notified about the agreement creation/amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended.</td></tr></table>
  - `response_requested_by` string, yyyy-MM-dd'T'HH:mm:ss[.SSS][.SS][.S]'Z' — 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 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.
  - `agreement_info` AgreementInformation, required — Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor. **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. - **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. - **purpose_code** - Most appropriate code that represents the purpose for which this agreement is being established. Supported values: - MORT - Mortgage payments, including payments for a home/business loan - UTIL - Utility payments such as gas, electricity, water etc - LOAN - Loan payments, other than mortgage payments - DEPD - Dependant support payments (e.g. child support) - RETL - Retail payments, including e-commerce and online shopping (payments are for provision of goods or services) - SALA - Salary payments - PERS - Personal payments (payments to an individual which excludes any payments for salary and superannuation purposes) - GOVT - Government payments - PENS - Pension payments (superannuation payments) - TAXS - Tax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body) - OTHR - Other service related payments (when there is no other appropriate purpose code) - **agreement_type** - Agreement type to be created. Supported values: - AUPM (Authorised Payment Mandate) - This type of agreement must be authorised by the payer/debtor i.e. agreement will be Active only post debtor/payer authorisation. Payment requests can be initiated immediately once the agreement is "Active". - MGCR (Migrated by Creditor/Migrated DDR) - This type of agreement is created in order to migrate existing Direct Debit arrangement to be processed via the NPP using the PayTo rails. The agreement will be Active immediately (does not need debtor/payer authorisation as it was already pre-authorised in the existing BECS systems) post migration however payment requests can be initiated after 5 calendar days of creating the agreement. - **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. - **validity_start_date** - Validity start date of the agreement. The agreement is valid as of 00:00:00.000 Australia Sydney time on this date. - **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. - **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. - **debtor_info** - Debtor and Debtor Account Details. - **creditor_info** - Creditor Details. - **payment_initiator_info** - Initiating party details. - **payment_terms** - Set of characteristics detailing agreement payment information. The following rules apply to this structure: - **DescriptionAndShortDescriptionRule:** Either 'description' or 'short_description' must be present. - **AgreementTypeRule:** If 'agreement_type' is equal to 'MGCR' then payid details must be absent. - **ValidityStartDateRule:** validity_start_date should be either current date OR future date. - **ValidityStartAndEndDateRule:** validity_end_date should be either current date OR future date. - **AutomaticExtensionRule:** validity_end_date must be present only if 'automatic_renewal' is false.
    - `description` string — Specifies a character string with a maximum length of 140 characters. 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.
    - `short_description` string — Specifies a character string with a maximum length of 35 characters. 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.
    - `purpose_code` 'MORT' | 'UTIL' | 'LOAN' | 'DEPD' | 'RETL' | 'SALA' | 'PERS' | 'GOVT' | 'PENS' | 'TAXS' | 'OTHR', required — <p>Specifies the high-level purpose of the mandate based on a set of pre-defined categories. Most appropriate code that represents the purpose for which this agreement is being established.</p> <table> <tr><td>Code</td><td>Description</td></tr> <tr><td>MORT</td><td>Mortgage payments, including payments for a home/business loan</td></tr> <tr><td>UTIL</td><td>Utility payments such as gas, electricity, water etc</td></tr> <tr><td>LOAN</td><td>Loan payments, other than mortgage payments</td></tr> <tr><td>DEPD</td><td>Dependant support payments (e.g. child support)</td></tr> <tr><td>RETL</td><td>Retail payments, including e-commerce and online shopping (payments are for provision of goods or services)</td></tr> <tr><td>SALA</td><td>Salary payments</td></tr> <tr><td>PERS</td><td>Personal payments (payments to an individual which excludes any payments for salary and superannuation purposes)</td></tr> <tr><td>GOVT</td><td>Government payments</td></tr> <tr><td>PENS</td><td>Pension payments (superannuation payments)</td></tr> <tr><td>TAXS</td><td>Tax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)</td></tr> <tr><td>OTHR</td><td>Other service related payments (when there is no other appropriate purpose code)</td></tr> </table>
    - `agreement_type` 'AUPM' | 'MGCR', required — <p>Agreement type to be created.</p> <table><tr><td>Code</td><td>Name</td><td>Description</td></tr><tr><td>AUPM</td><td>AuthorisedPaymentMandate</td><td>Established bilaterally as Authorised Payment Mandate.</td><td>This type of agreement must be authorised by the payer/debtor i.e. agreement will be Active only post debtor/payer authorisation. Payment requests can be initiated immediately once the agreement is "Active".</td></tr><tr><td>MGCR</td><td>MigratedByCreditor</td><td>Established by migration from legacy service by Creditor.</td><td>This type of agreement is created in order to migrate existing Direct Debit arrangement to be processed via the NPP using the PayTo rails. The agreement will be Active immediately (does not need debtor/payer authorisation as it was already pre-authorised in the existing BECS systems) post migration however payment requests can be initiated after 5 calendar days of creating the agreement.</td></tr></table>
    - `automatic_renewal` boolean — Indicates a "Yes" or "No" type of answer for an element. 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.
    - `validity_start_date` string, yyyy-MM-dd, required — A date expressed in the YYYY-MM-DD format. Validity start date of the agreement. The agreement is valid as of 00:00:00.000 Australia Sydney time on this date.
    - `validity_end_date` string, yyyy-MM-dd — A date expressed in the YYYY-MM-DD format. Validity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date.
    - `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.
    - `debtor_info` DebtorInformation, required — Debtor and Debtor Account Details. **Property descriptions**: - **debtor_account_details** - Debtor Account Details. - **debtor_details** - Debtor Details.
      - `debtor_account_details` DebtorAccountInformation, required — Debtor Account Details. **Property descriptions**: - **account_id_type** - Debtor's bank account type. Supported values: - BBAN (bsb/account) - PAYID (PayID) - **account_id** - Debtor's actual bank account number (BSB + Account Number). - **debtor_account_payid_details** - Debtor account PayID Details. The following rules apply to this structure: - <strong>AccountIdentificationRule1:</strong> If account_id_type is not equal to value 'PAYID' then account_id must be present, and payid_type and payid must be absent. - <strong>AccountIdentificationRule2:</strong> If account_id_type is equal to value 'PAYID' then payid_type and payid must be present, and account_id must be absent. - <strong>AccountIdentificationRule3:</strong> When account_id_type is 'BBAN', the account_id field should contain BSB in the first 6 positions followed by the account number. String with minimum length of 13 characters should be provided.
        - `account_id_type` 'BBAN' | 'PAYID', required — <p>Specifies the type of account identification. Debtor's bank account type</p><table><tr><td>Code</td><td>Description</td></tr><tr><td>BBAN</td><td>Basic Bank Account Number</td></tr><tr><td>PAYID</td><td>Pay Id</td></tr>
        - `account_id` string — Specifies a character string with a maximum length of 34 ASCII printable characters. Debtor's actual bank account number (BSB + Account Number).
        - `payid_details` DebtorAccountPayidInformation — Debtor account PayID Details. **Property descriptions**: - **payid_type** - PayID type associated with Debtor's bank account. Supported values: - EMAL - Email Address - TELE - Telephone Number - AUBN - Australian Business Number - ORGN - Organisational Identifier - **payid** - PayID as provided by the debtor.
          - `payid_type` 'TELI' | 'EMAL' | 'AUBN' | 'ORGN' — <p>PayID type associated with Debtor's bank account:</p><table><tr><td>Code</td><td>Description</td></tr><tr><td>TELI</td><td>Telephone Number (Note that the ISO Code is TELE, but in AU-NPP context, TELI is used)</td></tr><tr><td>EMAL</td><td>Email Address</td></tr><tr><td>AUBN</td><td>Australian Business Number</td></tr><tr><td>ORGN</td><td>Organisation Identifier</td></tr></table>
          - `payid` string — Specifies a character string with a maximum length of 2048 characters. PayID as provided by the debtor. Telephone (TELI): Consists of a "+" followed by the country code (from 1 to 3 characters) then a "-" then a number between 1-9 and then any combination of numbers between 0-9. Total of up to 35 characters. Format pattern: ^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$ Email (EMAL): Consists of a character string with a maximum length of 256 characters in lower case. This must include the "@" symbol with leading and trailing characters and no white spaces. Format pattern: (MAX256 text): ^(?:\[a-z0-9!#$%&'\*+/=?^\_\`{|}~-]+(?:\\.\[a-z0-9!#$%&'\*+/=?^_\`{|}~-]+)\*@(?:\[a-z0-9](?:\[a-z0-9-]\*\[a-z0-9])?\\.)+\[a-z0-9](?:\[a-z0-9-]*\[a-z0-9])?)$ **ABN (AUBN):** Consists of a nine to eleven digit number where the first two digits are a checksum. This is assigned by the Australian Taxation Office to identify an individual Australian Business. Format pattern: (MIN9 - MAX11 digit): ^((\d{9})|(\d{11}))$ **Organisation (ORGN):** The Identifier must include the company/organisation name and both/either the description of the business/ trade / product / campaign and/or geographic location. Format pattern: Maximum of 256 characters in lower case, to be drawn from the NPP Character Set and without leading or trailing whitespace. ^[!-@[-~][ -@[-~]{0,254}[!-@[-~]$
      - `debtor_details` DebtorInformationDetails, required — Debtor Details. **Property descriptions**: - **debtor_name** - Specifies the name by which the debtor is known and which is usually used to identify that debtor. - **debtor_type** - Identifies debtor type. Supported values: - ORGN = an organisation - PERS = a private individual - **ultimate_debtor_name** - This field should be populated with the trading name of an organisation as would be identifiable to the creditor, or with the name of the receiver of goods or services as specified in the agreement for which this agreement is being established. - **debtor_id** - Unique and unambiguous ID of the debtor. - **debtor_id_type** - Indicates Debtor Id types. - **debtor_reference** - Reference relevant to the Payer/Debtor user. This reference could indicate information that may be useful to the creditor. Example - a purchase order. 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. The following rules apply to this structure: - <strong>DebtorIdentificationAndTypeRule1:</strong> If debtor_id is present then debtor_id_type must be present. - <strong>DebtorIdentificationAndTypeRule2:</strong> If debtor_id is absent then debtor_id_type must be absent.
        - `debtor_name` string, required — Specifies a character string with a maximum length of 140 ASCII printable characters. Specifies the name by which the debtor is known and which is usually used to identify that debtor.
        - `debtor_type` 'ORGN' | 'PERS', required — Specifies the type of debtor involved in the transaction. Identifies debtor type. <table><tr><td>Code</td><td>Name</td><td>Description</td></tr><tr><td>ORGN</td><td>Organisation</td><td>Debtor is an organisation.</td></tr><tr><td>PERS</td><td>Person</td><td>Debtor is a private individual.</td></tr></table>
        - `ultimate_debtor_name` string, required — Specifies a character string with a maximum length of 140 ASCII printable characters. This field should be populated with the trading name of an organisation as would be identifiable to the creditor, or with the name of the receiver of goods or services as specified in the agreement for which this agreement is being established.
        - `debtor_id` string — Specifies a character string with a maximum length of 35 ASCII printable characters. Unique and unambiguous ID of the debtor.
        - `debtor_id_type` 'ARNU' | 'CCPT' | 'CUST' | 'DRLC' | 'EMPL' | 'NIDN' | 'SOSE' | 'TXID' | 'BANK' | 'CBID' | 'CHID' | 'CINC' | 'COID' | 'DUNS' | 'GS1G' | 'SREN' | 'SRET' | 'AUBN' | 'AUCN' | 'LEIN' — <p>Specifies an alphanumeric string with a length of 4 characters. Specifies the code indicating the identification type of the debtor </p><table><tr><td>Code</td><td>Description</td></tr><tr><td>ARNU</td><td>Alien Registration Number</td></tr><tr><td>CCPT</td><td>Passport Number</td></tr><tr><td>CUST</td><td>Customer Identification Number</td></tr><tr><td>DRLC</td><td>Drivers License Number</td></tr><tr><td>EMPL</td><td>Employee Identification Number</td></tr><tr><td>NIDN</td><td>National Identity Number</td></tr><tr><td>SOSE</td><td>Social Security Number</td></tr><tr><td>TXID</td><td>Tax Identification Number</td></tr><tr><td>BANK</td><td>Bank Party Identification</td></tr><tr><td>CBID</td><td>Central Bank Identification Number</td></tr><tr><td>CHID</td><td>Clearing Identification Number</td></tr><tr><td>CINC</td><td>Certificate Of Incorporation Number</td></tr><tr><td>COID</td><td>Country Identification Code</td></tr><tr><td>DUNS</td><td>Data Universal Numbering System</td></tr><tr><td>GS1G</td><td>GS1GLN Identifier</td></tr><tr><td>SREN</td><td>SIREN</td></tr><tr><td>SRET</td><td>SRET</td></tr><tr><td>AUBN</td><td>Australian Business Number (ABN)</td></tr><tr><td>AUCN</td><td>Australian Company Number (ACN)</td></tr><tr><td>LEIN</td><td>Legal Entity Identification (LEI)</td></tr></table>
        - `debtor_reference` string — Specifies a character string with a maximum length of 35 ASCII printable characters. Reference relevant to the Payer/Debtor user. This reference could indicate information that may be useful to the creditor. Example - a purchase order. 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.
    - `creditor_info` CreditorInformation, required — Creditor Details. **Property descriptions**: - **ultimate_creditor_name** - This field can indicate trading the name or common name of the marketplace/platform which is receives the funds via Zai OR could be the actual seller user's name to which the funds will be transferred eventually. - **creditor_reference** - Reference relevant to the Creditor. Example - Invoice number.
      - `ultimate_creditor_name` string, required — Specifies a character string with a maximum length of 140 ASCII printable characters. This field can indicate trading the name or common name of the marketplace/platform which is receives the funds via Zai OR could be the actual seller user's name to which the funds will be transferred eventually.
      - `creditor_reference` string — Specifies a character string with a maximum length of 35 ASCII printable characters. Reference relevant to the Creditor. Example - Invoice number.
    - `payment_initiator_info` PaymentInitiatorInformation, required — Initiating party details. Your platform name or any third party name that you prefer to be shown to the debtor as initiator of the payments. Example - If it’s a proptech platform, either your platform’s details should be provided or the property management agency details to convey that the platform or the agency is collecting the rent from the tenant/debtor’s bank account via PayTo payment option. Please Note - It is essential to provide correct and appropriate details in these fields as they would be visible to the debtor in their banking portal. Please refrain from providing “Zai” or any random text as initiator. This can lead to claims being raised by the debtor if they do not recognise the party provided as initiator. **Property descriptions:** - **initiator_id** - Unique and unambiguous identification of the initiator of the PayTo payment i.e. either platform or any third party details. - **initiator_id_type_code** - 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 - **initiator_legal_name** - Name by which the initiator is known and which is usually used to identify them i.e. either platform’s name or any third party details. - **initiator_name** - Name by which the initiator is known and which is usually used to identify them i.e. either platform’s name or any third party details. - Please Note - The debtor will be able to see this information in the agreement. Hence it is essential to provide appropriate information in this field which is easily identifiable by the debtor to avoid claims.
      - `initiator_id` string, required — Specifies a character string with a maximum length of 35 ASCII printable characters. Unique and unambiguous identification of the initiator of the PayTo payment i.e. either platform or any third party details.
      - `initiator_id_type_code` 'AUBN' | 'CCPT' | 'CUST' | 'DRLC' | 'EMPL' | 'NIDN' | 'SOSE' | 'TXID' | 'BANK' | 'CBID' | 'CHID' | 'CINC' | 'COID' | 'DUNS' | 'GS1G' | 'SREN' | 'SRET' | 'AUBN' | 'AUCN' | 'LEIN', required — <p>Specifies an alphanumeric string with a length of 4 characters.</p> 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<table><tr><td>Code</td><td>Description</td></tr><tr><td>ARNU</td><td>Alien Registration Number</td></tr><tr><td>CCPT</td><td>Passport Number</td></tr><tr><td>CUST</td><td>Customer Identification Number</td></tr><tr><td>DRLC</td><td>Drivers License Number</td></tr><tr><td>EMPL</td><td>Employee Identification Number</td></tr><tr><td>NIDN</td><td>National Identity Number</td></tr><tr><td>SOSE</td><td>Social Security Number</td></tr><tr><td>TXID</td><td>Tax Identification Number</td></tr><tr><td>BANK</td><td>Bank Party Identification</td></tr><tr><td>CBID</td><td>Central Bank Identification Number</td></tr><tr><td>CHID</td><td>Clearing Identification Number</td></tr><tr><td>CINC</td><td>Certificate Of Incorporation Number</td></tr><tr><td>COID</td><td>Country Identification Code</td></tr><tr><td>DUNS</td><td>Data Universal Numbering System</td></tr><tr><td>GS1G</td><td>GS1GLN Identifier</td></tr><tr><td>SREN</td><td>SIREN</td></tr><tr><td>SRET</td><td>SIRET</td></tr><tr><td>AUBN</td><td>Australian Business Number (ABN)</td></tr><tr><td>AUCN</td><td>Australian Company Number (ACN)</td></tr><tr><td>LEIN</td><td>Legal Entity Identification (LEI)</td></tr></table>
      - `initiator_legal_name` string, required — 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 i.e. either platform’s name or any third party details.
      - `initiator_name` string, required — 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 i.e. either platform’s name or any third party details.
    - `payment_terms` PaymentTermsDetails, required — 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.<br><br> *Note - This parameter is currently not supported.* - **point_in_time** - 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.<br><br>Note - Specifying a point_in_time for payments is applicable only for "Monthly" frequency. - Frequency = Adhoc -> point in time is not applicable - Frequency = IntraDay -> Point In Time = hour within day (1-24) - Frequency = Daily -> Point In Time = hour within day (1-24)) - Frequency = Weekly -> Point In Time = day of week (1-7) - Frequency = Fortnightly -> Point In Time = day within fortnight (1-14) - Frequency = Monthly -> Point In Time = day of month (1-28) - Frequency = Quarterly -> Point In Time = which month within the quarter of year (1-4) - Frequency = HalfYearly -> Point In Time = which month within the half of the year (1-6) - Frequency = Yearly -> Point In Time = month within the year (1-12) - **count_per_period** - 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. - **frequency** - Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement. <br><br>*Note - Intraday, Quarterly, Half Yearly and Yearly payment frequencies are currently not supported.* Must be one of following: - Adhoc (Event takes place on request or as necessary) - Intraday (Event takes place several times a day) - Daily (Event takes place every day) - Weekly (Event takes place once a week) - Fortnightly (Event takes place every two weeks) - Monthly (Event takes place every month) - Quarterly (Event takes place every three months) - Half Yearly (Event takes place every six months or two times a year) - Yearly (Event takes place every year or once a year) The following rules apply to this structure: - **AgreementFirstPaymentRule1:** first_payment_date should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date. - **AgreementLastPaymentRule2:** last_payment_date should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date. - **CurrencyAUD:** All currencies must be in AUD only. - **AmountRule:** All amounts should be less than or equal to Maximum amount. - **LastAndFirstPaymentDate:** last_payment_date cannot be less than first_payment_date. - **PaymentAmountTypeRule:** If payment_amount_type code is equal to value 'FIXE' then amount must be present. - **FrequencyCombinationRule:** The frequency, point_in_time and count_per_period combination must be valid. Refer frequency rules table below for valid combinations. - **PaymentAmountTypeCombinationRule:** The payment_amount_type, amount and maximum_amount combination must be valid. Refer payment amount type rules table below for valid combination. **Rules for frequency:** Valid values for frequency, point_in_time and count_per_period are given below. <table><tr><td><b>frequency</b></td><td><b>point_in_time</b></td><td><b>count_per_period</b></td></tr><tr><td>ADHOC</td><td>N/A</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>INTRDY</td><td>01 to 24</td><td>Not present</td></tr><tr><td>INTRDY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>DAILY</td><td>01 to 24</td><td>Not present</td></tr><tr><td>DAILY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>DAILY</td><td>N/A</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>WEEKLY</td><td>01 to 07</td><td>Not present</td></tr><tr><td>WEEKLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>WEEKLY</td><td>N/A</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>FRTNLY</td><td>01 to 14</td><td>Not present</td></tr><tr><td>FRTNLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>FRTNLY</td><td>N/A</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>MNTHLY</td><td>01 to 28</td><td>Not present</td></tr><tr><td>MNTHLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>QURTLY</td><td>01 to 03</td><td>Not present</td></tr><tr><td>QURTLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>HFYRLY</td><td>01 to 06</td><td>Not present</td></tr><tr><td>HFYRLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr><tr><td>YEARLY</td><td>01 to 12</td><td>Not present</td></tr><tr><td>YEARLY</td><td>Not present</td><td>Valid non decimal numeric value, greater than zero</td></tr></table> **Payment amount types rules:** <table><tr><td><b>Payment_amount_type</b></td><td><b>amount</b></td><td><b>max_ Amount</b></td><td><b>Remarks</b></td></tr><tr><td>BALN</td><td>Valid numeric value</td><td>NA</td><td>If Balloon, only amount should have values. Max amount should not be present</td></tr><tr><td>FIXE</td><td>Valid numeric value</td><td>NA</td><td>If Fixed, only amount should have values. Max amount should not be present</td></tr><tr><td>USGB</td><td>Valid numeric value</td><td>Valid numeric value</td><td>If Usage based, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount</td></tr><tr><td>VARI</td><td>Valid numeric value</td><td>Valid numeric value</td><td>If Variable, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount</td></tr></table>
      - `payment_amount_info` PaymentAmountInformation, required — 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. **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. - **type** - 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. Supported values: - FIXE - Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement. - BALN - 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).<br>*Note - This type is currently not supported.* - USGB - 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 - 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.
        - `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.
        - `type` 'BALN' | 'FIXE' | 'USGB' | 'VARI' — <p>Specific type of payment amount.</p><p>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.</p> <table><tr><td>Code</td><td>Name</td><td>Description</td></tr><tr><td>FIXE</td><td>Fixed</td><td>Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.</td></tr><tr><td>BALN</td><td>Balloon</td><td>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).<br><i>Note - This type is currently not supported.</i></td></tr><tr><td>USGB</td><td>UsageBased</td><td>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.</td></tr><tr><td>VARI</td><td>Variable</td><td>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.</td></tr></table>
      - `first_payment_info` FirstPaymentInformation — 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.
        - `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 — 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.
      - `last_payment_info` LastPaymentInformation — 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.
        - `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 — 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.
      - `maximum_amount_info` MaximumAmountInformation — 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. *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. Note - Specifying a point_in_time for payments is applicable only for "Monthly" frequency<table><tr><td>Frequency</td><td>Description</td></tr><tr><td>Adhoc</td><td>Point in time is not applicable</td></tr><tr><td>IntraDay</td><td>Point In Time = hour within day (1-24))</td></tr><tr><td>Daily</td><td>Point In Time = hour within day (1-24)</td></tr><tr><td>Weekly</td><td>Point In Time = day of week (1-7)</td></tr><tr><td>Fortnightly</td><td>Point In Time = day within fortnight (1-14)</td></tr><tr><td>Monthly</td><td>Point In Time = day of month (1-28)</td></tr><tr><td>Quarterly</td><td>Point In Time = day of month within the quarter of year (1-4)</td></tr><tr><td>HalfYearly</td><td>Point In Time = day of month within the half of the year (1-6)</td></tr><tr><td>Yearly</td><td>Point In Time = month within the year (1-12)</td></tr></table>
      - `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.
      - `frequency` 'ADHOC' | 'INTRDY' | 'DAILY' | 'WEEKLY' | 'FRTNLY' | 'MNTHLY' | 'QURTLY' | 'HFYRLY' | 'YEARLY', required — <p>Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement.</p> *Note - Intraday, Quarterly, Half Yearly and Yearly payment frequencies are currently not supported.* <table><tr><td>Code</td><td>Name</td><td>Description</td></tr><tr><td>ADHOC</td><td>Adhoc</td><td>Event takes place on request or as necessary.</td></tr><tr><td>INTRDY</td><td>IntraDay</td><td>Event takes place several times a day.</td></tr><tr><td>DAILY</td><td>Daily</td><td>Event takes place every day.</td></tr><tr><td>WEEKLY</td><td>Weekly</td><td>Event takes place once a week.</td></tr><tr><td>FRTNLY</td><td>Fortnightly</td><td>Event takes place every two weeks.</td></tr><tr><td>MNTHLY</td><td>Monthly</td><td>Event takes place every month or once a month.</td></tr><tr><td>QURTLY</td><td>Quarterly</td><td>Event takes place every three months or four times a year.</td></tr><tr><td>HFYRLY</td><td>HalfYearly</td><td>Event takes place every six months or two times a year.</td></tr><tr><td>YEARLY</td><td>Yearly</td><td>Event takes place every year or once a year.</td></tr></table>

## Response `202`

Accepted

- ValidateAgreementResponse
  - `agreement_uuid` string — Agreement uuid.
  - `status` string — Status of the validate agreement request.
  - `created_at` string — creation date.
  - `updated_at` string — modification date.

## Other responses

- `400` — Bad Request <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 or equal to 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-2031</td><td>Invalid Data: Please provide info for all parameters under agreement_info.payment_terms.maximum_amount_info</td></tr><tr><td>PAYT-ERR-2032</td><td>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.</td></tr><tr><td>PAYT-ERR-2033</td><td>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.</td></tr><tr><td>PAYT-ERR-2034</td><td>Invalid Data: Agreement type [type] is not enabled for your platform. If you require this agreement type to be enabled for your business use-case, kindly get in touch with Zai support.</td></tr><tr><td>PAYT-ERR-2035</td><td>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.</td></tr></table>
- `401` — Unauthorised <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>
- `403` — Forbidden <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>
- `404` — Not Found <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>
- `500` — Internal Server Error <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>

---

[API](https://skmtc.net/hellozai/apis/assembly-api.md) · [All operations](https://skmtc.net/hellozai/apis/assembly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hellozai/assembly-api/revisions/60b528b2e015/schema)