{"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**Changes in 1.4 version**\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**Changes in 1.3 version**\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**Changes in 1.2 version**\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**Changes in 1.1 version**\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
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1002Request rejected: User associated with the agreement is not active.
","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
Error CodeError Message
PAYT-ERR-1050Mandatory info missing: [FieldName] cannot be null or empty.
PAYT-ERR-1051Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-1054Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].
PAYT-ERR-1057Unrecognized Field: [FieldName] is not a valid field.
PAYT-ERR-1058Invalid Request: request provided is not well-formatted.
PAYT-ERR-2501Payments can be initiated for ACTIVE agreements only.
PAYT-ERR-2502Payments can be initiated only within the agreement validity period.
PAYT-ERR-2510unique_superannuation_code is mandatory along with unique_superannuation_identification.
PAYT-ERR-2512Payment requested for this agreement has been cleared and settled already. Please check the latest status before requesting again.
PAYT-ERR-2513Request rejected: Exceeded the maximum retry attempts allowed for the agreement.
PAYT-ERR-2514Request rejected: Please ensure the payment is retried within valid period.
","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
Error CodeError Message
PAYT-ERR-2500Agreement with provided uuid does not exist.
PAYT-ERR-2511Payment request with provided uuid does not exist.
","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
Error CodeError Message
PAYT-ERR-2516A payment is already in progress for the agreement. Please try again if the current payment request is unsuccessful.
PAYT-ERR-2517Invalid request: Payment has been rejected already and cannot be retried. Please check reason code details.
PAYT-ERR-2518For 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.
PAYT-ERR-2519For 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.
PAYT-ERR-2520For 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.
PAYT-ERR-2521For 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.
PAYT-ERR-2522For 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.
PAYT-ERR-2523For 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.
PAYT-ERR-2524For 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.
PAYT-ERR-2525For 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.
PAYT-ERR-2526For 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.
","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
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1002Request rejected: User associated with the agreement is not active.
","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
Error CodeError Message
PAYT-ERR-2100Agreement should be in VALIDATED state for creation.
","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
Error CodeError Message
PAYT-ERR-2102Invalid format for url param: agreement_uuid.
","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
Error CodeError Message
PAYT-ERR-2101Agreement creation is allowed only within a limited time period post validation. Please validate the agreement details again.
","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
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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
Error CodeError Message
PAYT-ERR-1050Mandatory info missing: [FieldName] cannot be null or empty.
PAYT-ERR-1051Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-1054Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].
PAYT-ERR-1057Unrecognized Field: [FieldName] is not a valid field.
PAYT-ERR-1058Invalid Request: request provided is not well-formatted.
PAYT-ERR-2001Either description or short_description should be provided.
PAYT-ERR-2002Response_Requested_By date must be a future date and less than 5 days.
PAYT-ERR-2004PayID details are not supported for migrated agreements.
PAYT-ERR-2005validity_start_date should be either current date OR future date.
PAYT-ERR-2006validity_end_date should be greater than OR same as validity_start_date.
PAYT-ERR-2008validity_end_date should not be provided if agreement should be auto-renewed.
PAYT-ERR-2009account_details in the request are invalid as per the account_type provided.
PAYT-ERR-2010Either account (bsb/account number) or PayID details should be provided.
PAYT-ERR-2011Invalid PayID format for the PayID type provided.
PAYT-ERR-2013debtor_id_type is mandatory along with debtor_id.
PAYT-ERR-2014Invalid debtor_id_type for the debtor_type provided.
PAYT-ERR-2015Date provided in first_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2016Date provided in last_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2018payment_amount should be less than maximum amount.
PAYT-ERR-2019Amount provided in last_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2020Amount provided in first_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2021Date provided in last_payment_info should be same OR after the date provided in first_payment_info.
PAYT-ERR-2025Incorrect value provided for either of these fields - frequency, point_in_time, count_per_period. The combination provided should be valid.
PAYT-ERR-2027Active direct debit agreement which needs to be migrated does not exist for the user.
PAYT-ERR-2028Response_Requested_By is applicable only for AUPM agreements with 'ATTENDED' priority type.
PAYT-ERR-2029For FIXE/BALN type of agreements, specifying payment amount is mandatory.
PAYT-ERR-2030For FIXE/BALN type of agreements, specifying maximum amount is not applicable.
PAYT-ERR-2031Invalid Data: Please provide info for all parameters under agreement_info.payment_terms.maximum_amount_info
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1004User with provided user_external_id does not exist.
","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
Error CodeError Message
PAYT-ERR-2000Active user with provided user_external_id does not exist.
","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
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-2201A status amendment for this agreement is already in progress. Please try again later.
","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
Error CodeError Message
PAYT-ERR-1050Mandatory info missing: [FieldName] cannot be null or empty.
PAYT-ERR-1051Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1054Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].
PAYT-ERR-1057Unrecognized Field: [FieldName] is not a valid field.
PAYT-ERR-1058Invalid Request: request provided is not well-formatted.
PAYT-ERR-2202Amendment request rejected: Invalid status change requested.
PAYT-ERR-2203Reason code is mandatory while suspending or cancelling an agreement.
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1002Request rejected: User associated with the agreement is not active.
PAYT-ERR-2204Agreement can be resumed only by the same party who suspended it.
","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
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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
Error CodeError Message
PAYT-ERR-2200Agreement with provided uuid does not exist.
","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
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-2500Agreement with provided uuid does not exist.
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1002Request rejected: User associated with the agreement is not active.
","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
Error CodeError Message
PAYT-ERR-2502Recall request rejected: Recall action is applicable only for agreements in CREATED/ACTIVE/SUSPENDED statuses.
PAYT-ERR-2503Request to recall agreement creation is already in progress. Please try again later.
PAYT-ERR-2504Recall request rejected: Any bilateral amendment is not in progress for the agreement.
PAYT-ERR-2505Recall request rejected: Request to recall bilateral amendment is already in progress for the agreement. Please try again later.
PAYT-ERR-2506Recall request rejected: Existing bilateral amendment request cannot be recalled at the moment. Please try again later.
PAYT-ERR-2508Invalid format for url param: agreement_uuid.
","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
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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:\n- Unilateral amendments - which does not need debtor approval and will be effective immediately\n- Bilateral amendments - which does require debtor approval and will be effective post debtor authorisation\n\nOptional 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.\n\nEither unilateral or bilateral amendments will be accepted in an amendment request. Both types of amendments cannot be provided in a single request.\n\nAt any given point of time, only a single unilateral or a single bilateral amendment will be allowed. Example - If a bilateral amendment is already in progress, another bilateral amendment request will not be accepted until the first completes.\n\nUnilateral details that can be amended:\n- description\n- short_description\n- creditor_info\n- payment_initiator_info\n\nBilateral details that can be amended:\n- validity_end_date\n- transfer_arrangement\n- automatic_renewal\n- payment_terms - all fields\n\nNote - Bilateral amendments will be effective only post debtor authorization. Debtor should authorize the amendments within 5 days (default duration) or within the custom expiry duration (response_requested_by) specified in the amendment request.","operationId":"amendAgreementDetails","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/AmendAgreementDetailsRequest"}}},"required":true},"responses":{"401":{"description":"Unauthorised \n
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"400":{"description":"Bad Request \n \n
Error CodeError Message
PAYT-ERR-1050Mandatory info missing: [FieldName] cannot be null or empty.
PAYT-ERR-1051Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-1054Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].
PAYT-ERR-1057Unrecognized Field: [FieldName] is not a valid field.
PAYT-ERR-1058Invalid Request: request provided is not well-formatted.
PAYT-ERR-2002Response_Requested_By date must be a future date and less than 5 days.
PAYT-ERR-2019Amount provided in last_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2020Amount provided in first_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2302Either unilateral or bilateral amendments can be requested.
PAYT-ERR-2303Details can be amended for 'ACTIVE' or 'SUSPENDED' agreements only.
PAYT-ERR-2304Either description or short_description is mandatory for an agreement.
PAYT-ERR-2305validity_end_date should not be provided if agreement should be auto-renewed.
PAYT-ERR-2306validity_end_date should be greater than OR same as validity_start_date.
PAYT-ERR-2307Date provided in last_payment_info should be same OR after the date provided in first_payment_info.
PAYT-ERR-2308Date provided in first_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2309Date provided in last_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2311Incorrect value provided for either of these fields - frequency, point_in_time, count_per_period. The combination provided should be valid.
PAYT-ERR-2313Amount provided in last_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2314Amount provided in first_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2315payment_amount should be less than maximum amount.
PAYT-ERR-2316Invalid Request: At least one field should be provided for amendment.
PAYT-ERR-2318Invalid Request: Values provided for few fields is same as existing. Please provide correct info for amendment.
PAYT-ERR-2319A unilateral amendment for this agreement is already in progress. Please try again later.
PAYT-ERR-2320Response_Requested_By is applicable only for bilateral amendment requests with 'ATTENDED' priority type.
PAYT-ERR-2321For FIXE/BALN type of agreements, specifying payment amount is mandatory.
PAYT-ERR-2322For FIXE/BALN type of agreements, specifying maximum amount is not applicable.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2302","error_message":"Either unilateral or bilateral amendments can be requested."},{"error_code":"PAYT-ERR-2303","error_message":"Details can be amended for ACTIVE or SUSPENDED agreements only."}]}}}},"403":{"description":"Forbidden \n
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
PAYT-ERR-1002Request rejected: User associated with the agreement is not active.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"409":{"description":"Conflict \n
Error CodeError Message
PAYT-ERR-2301A bilateral amendment for this agreement is already in progress. Please try again later.
PAYT-ERR-2319A unilateral amendment for this agreement is already in progress. Please try again later.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2301","error_message":"An amendment for this agreement is already in progress. Please try again later."}]}}}},"500":{"description":"Internal Server Error \n
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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/AmendAgreementDetailsResponse"}}}},"404":{"description":"Not Found \n
Error CodeError Message
PAYT-ERR-2300Agreement with provided uuid does not exist.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2300","error_message":"Agreement with provided uuid does not exist."}]}}}}},"security":[{"bearerAuth":[]}]}},"/payment_requests/{payment_request_uuid}":{"get":{"tags":["PayTo Payments"],"summary":"Get PayTo Payment Initiation Request Details","description":"This operation is to retrieve details of an initiated payment request. This API should be invoked to know the latest status of the payment initiation request if needed.\n\n Payment initiation request statuses which will be returned via this endpoint -\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","operationId":"getInitiatePaymentStatus","parameters":[{"name":"payment_request_uuid","in":"path","required":true,"schema":{"type":"string","example":"g0h40f95-95b7-449b-9835-3c97c0394857"}}],"responses":{"401":{"description":"Unauthorised \n
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","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
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1002","error_message":"PayTo Feature not available"}]}}}},"404":{"description":"Not Found \n
Error CodeError Message
PAYT-ERR-2600Payment request with provided uuid does not exist.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2600","error_message":"Payment request with provided uuid does not exist"}]}}}},"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentStatusResponse"}}}},"500":{"description":"Internal Server Error \n
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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}/payment_requests":{"get":{"tags":["PayTo Payments"],"summary":"Get All PayTo Payment Initiation Requests for an Agreement","description":"This operation is to retrieve all payment requests initiated for an agreement in the provided period (date range). Payment requests for a period of maximum one year or less than it can be retrieved at a time.\n\n By default, all payment initiation requests (along with details) irrespective of the status will be listed via this endpoint. However, the results can be filtered based on status(es) if needed.\n\nRequest parameter descriptions:\n\n - status - List of valid agreement statuses. Example - Retrieve active and suspended payments only.\n - Valid values - PENDING_PAYMENT_INITIATION, PAYMENT_INITIATED, PAYMENT_INITIATION_COMPLETED, PAYMENT_INITIATION_REJECTED\n - start_date - Date range start, example - fetch all payments created between June to December 2022.\n - end_date - Date range end, example - fetch all payments created between June to December 2022.\n - size - Number of payments per page. Default value is 20.\n - page - Page number. Default value is 0.","operationId":"getInitiatePaymentStatusList","parameters":[{"name":"agreement_uuid","in":"path","required":true,"schema":{"type":"string","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","example":"2021-11-10"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","example":"2022-11-10"}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PAYMENT_INITIATED","PENDING_PAYMENT_INITIATION","PAYMENT_INITIATION_COMPLETED","PAYMENT_INITIATION_REJECTED"]},"enum":["PAYMENT_INITIATED","PENDING_PAYMENT_INITIATION","PAYMENT_INITIATION_COMPLETED","PAYMENT_INITIATION_REJECTED"]}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"401":{"description":"Unauthorised \n
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiatePaymentListResponse"}}}},"400":{"description":"Bad Request \n \n \"
Error CodeError Message
PAYT-ERR-1058Invalid Request: Failed to read the request.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-2601Invalid Date Range: Start date should be before end date.
PAYT-ERR-2602Invalid Date Range: Range provided should be less than or maximum upto a year.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2601","error_message":"Invalid Date Range: Start date should be before end date."}]}}}},"500":{"description":"Internal Server Error \n
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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."}]}}}},"403":{"description":"Forbidden \n
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
","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
Error CodeError Message
PAYT-ERR-2400Agreement with provided uuid does not exist.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2400","error_message":"Agreement with provided uuid does not exist."}]}}}}},"security":[{"bearerAuth":[]}]}},"/agreements/{agreement_uuid}":{"get":{"tags":["PayTo Agreements"],"summary":"Get PayTo Agreement Details","description":"Retrieve details of a PayTo agreement by UUID which uniquely identifies the agreement.\n This UUID is returned as part of the “Validate PayTo Agreement” operation.\n\n It provides complete details of a particular agreement irrespective of its current status ","operationId":"getAgreementDetails","parameters":[{"name":"agreement_uuid","in":"path","required":true,"schema":{"type":"string","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}}],"responses":{"400":{"description":"Bad Request \n \n
Error CodeError Message
PAYT-ERR-2401Invalid format for url param: agreement_uuid.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2401","error_message":"Invalid format for url param: agreement_uuid."}]}}}},"401":{"description":"Unauthorised \n
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"500":{"description":"Internal Server Error \n
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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."}]}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgreementDetailsResponse"}}}},"403":{"description":"Forbidden \n
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
","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
Error CodeError Message
PAYT-ERR-2400Agreement with provided uuid does not exist.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-2400","error_message":"Agreement with provided uuid does not exist."}]}}}}},"security":[{"bearerAuth":[]}]}},"/agreements":{"get":{"tags":["PayTo Agreements"],"summary":"Get All PayTo Agreements for a User","description":" This operation is to retrieve all PayTo agreements associated with a particular user in the provided period (date range). Agreements can be retrieved for a maximum period of one year or less at a time i.e. the period between start and end date cannot exceed more than one year.\n\n By default, all agreements will be returned irrespective of status and type (AUPM/MGCR).\n\n However, if required, results can be filtered for a particular status or agreement type. Example - Retrieve all suspended and cancelled migrated agreements.\n\nRequest parameter descriptions:\n \n - user_external_id - Unique identifier of the user that is associated with the agreement.\n - status - List of valid agreement statuses. Example - Retrieve active and suspended agreements only.\n - Valid values - PENDING_VALIDATION, VALIDATED, PENDING_CREATION, CREATED, ACTIVE, SUSPENDED, CANCELLED\n - agreement_type - List of valid agreement types. Example - Retrieve only migrated agreements.\n - Valid values - AUPM, MGCR\n - start_date - Date range start, example - fetch all agreements created between June to December 2022.\n - end_date - Date range end, example - fetch all agreements created between June to December 2022.\n - size - Number of agreements per page. Default value is 20.\n - page - Page number. Default value is 0.","operationId":"getAgreementsByUser","parameters":[{"name":"user_external_id","in":"query","required":true,"schema":{"type":"string","example":"buyer-147043828"}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PENDING_VALIDATION","VALIDATED","PENDING_CREATION","CREATED","ACTIVE","SUSPENDED","CANCELLED"]},"enum":["PENDING_VALIDATION","VALIDATED","PENDING_CREATION","CREATED","ACTIVE","SUSPENDED","CANCELLED"]}},{"name":"agreement_type","in":"query","required":false,"schema":{"type":"string","example":"AUPM"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","example":"2022-10-15"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","example":"2023-10-15"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"400":{"description":"Bad Request \n \n
Error CodeError Message
PAYT-ERR-1051Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-1058Invalid Request: request provided is not well-formatted.
PAYT-ERR-4000end_date should be greater than start_date.
PAYT-ERR-4001Period between start_date and end_date cannot exceed 1 year.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1051","error_message":"Invalid Data: user_external_id provided is invalid."}]}}}},"401":{"description":"Unauthorised \n
Error CodeError Message
PAYT-ERR-1000Invalid or missing authorisation token.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1000","error_message":"Invalid or missing authorisation token."}]}}}},"500":{"description":"Internal Server Error \n
Error CodeError Message
PAYT-ERR-1003An error occurred processing your request. Please try again.
","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."}]}}}},"403":{"description":"Forbidden \n
Error CodeError Message
PAYT-ERR-1001PayTo feature not available.
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayToErrorResponse"},"example":{"errors":[{"error_code":"PAYT-ERR-1001","error_message":"PayTo feature not available."}]}}}},"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgreementListResponse"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"InitiatePaymentRequest":{"required":["payment_info","priority"],"type":"object","properties":{"priority":{"title":"Priority","type":"string","description":"

Indicates payment processing priority. Supported values

\n
CodeDescription
ATTENDEDPayment marked as attended will be processed immediately and will be rejected if the responding participant is not available
UNATTENDEDPayments marked as unattended may not be processed immediately. In cases where the responding participant is not available, the payment will be stored for later processing and hence won’t be rejected
","example":"ATTENDED","enum":["ATTENDED","UNATTENDED"]},"payment_info":{"$ref":"#/components/schemas/PaymentInformation"},"retry_info":{"$ref":"#/components/schemas/RetryInformation"}},"description":"Definition of the Initiate Payment request data.\n \n **Property descriptions**: \n \n- **priority** - Indicates payment processing priority.\n Supported values: \n\n - Attended: Payment marked as attended will be processed immediately and will be rejected if the responding participant is not available\n - Unattended: Payments marked as unattended may not be processed immediately. In cases where the responding participant is not available, the payment will be stored for later processing and hence won’t be rejected\n- **payment_info** - Payment info for payment request.\n- **retry_info** - Retry information should be provided only if the payment request was rejected previously due to business reasons and a retry for the same is being attempted."},"PaymentInformation":{"required":["instructed_amount","last_payment"],"type":"object","properties":{"instructed_amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\nSpecifies the amount to be debited the from debtor's bank account before deduction of charges.","example":"1000"},"last_payment":{"type":"boolean","description":"Indicates a \"Yes\" or \"No\" type of answer for an element.\n\nIndicates that it is the last payment associated with the agreement. Post this, the agreement will be marked as CANCELLED automatically and no further payments can be requested on this agreement.","default":false},"end_to_end_id":{"maxLength":35,"minLength":1,"pattern":"^([a-zA-Z0-9_-]){1,35}$","type":"string","description":"Specifies a character string with a maximum length of 35 characters.\n\nUnique identification to unambiguously identify the payment. This identification is passed on, unchanged, throughout the entire end-to-end chain. It is recommended to provide this identifier which can be passed between entities to identify the payment during queries/investigations if any. If not provided, debtor reference (if available) from the agreement will be populated. If none available, default value \"NOTPROVIDED\" will be populated in the payment initiation request.","example":"0h40f9595b7449b98353c97c039485"},"remittance_info":{"maxLength":280,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 280 characters.\n\nFree text field to provide any narrative for the payment.","example":"Remittance Info"},"unique_superannuation_id":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nFor agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI number for the superannuation fund.","example":"unique superannuation id"},"unique_superannuation_code":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nFor agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI - code indicating the identifier to whom the superannuation fund will be provided.","example":"unique superannuation code"}},"description":"Payment request details.\n \n **Property descriptions**: \n \n - **instructed_amount** - Specifies the amount to be debited the from debtor's bank account before deduction of charges.\n- **last_payment** - Indicates that it is the last payment associated with the agreement. Post this, the agreement will be marked as CANCELLED automatically and no further payments can be requested on this agreement.\n- **end_to_end_id** - Unique identification to unambiguously identify the payment. This identification is passed on, unchanged, throughout the entire end-to-end chain. It is recommended to provide this identifier which can be passed between entities to identify the payment during queries/investigations if any. If not provided, debtor reference (if available) from the agreement will be populated. If none available, default value \"NOTPROVIDED\" will be populated in the payment initiation request.\n- **remittance_info** - Free text field to provide any narrative for the payment. \n\n- **unique_superannuation_code** - For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI number for the superannuation fund.\n- **unique_superannuation_id** - For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI - code indicating the identifier to whom the superannuation fund will be provided. \n\n **The following rules apply to this structure**: \n\n - **UniqueSuperannuationRule** Both unique_superannuation_code and unique_superannuation_id must be present or both fields must be absent. "},"RetryInformation":{"type":"object","properties":{"payment_request_uuid":{"maxLength":36,"minLength":36,"pattern":"^([a-zA-Z0-9_-]){36}$","type":"string","description":"Unique identifier for the payment request (in UUID format) for which the retry is being attempted.","example":"d0c40d95-95b7-449b-9835-3c97c0386585"}},"description":"Retry information should be provided only if the payment request was rejected previously due to business reasons and a retry for the same is being attempted.\n \n **Property descriptions**: \n \n- **payment_request_uuid** - Unique identifier for the payment request (in UUID format) for which the retry is being attempted."},"ErrorDetails":{"type":"object","properties":{"error_code":{"type":"string"},"error_message":{"type":"string"}}},"PayToErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"InitiatePaymentResponse":{"type":"object","properties":{"payment_request_uuid":{"maxLength":36,"minLength":36,"type":"string","description":"Unique identifier for the payment request in UUID format.","example":"d0c40d95-95b7-449b-9835-3c97c0386585"},"agreement_uuid":{"maxLength":36,"minLength":36,"type":"string","description":"Unique agreement identifier.","example":"d0c40d95-95b7-449b-9835-3c97c0386585"},"instruction_id":{"maxLength":35,"minLength":1,"type":"string","description":"Unique identifier for the payment request generated as per NPPA guidelines.","example":"BANKNTSTXXXI20180501000000000000010"},"status":{"title":"Status","type":"string","description":"Payment initiation request statuses:
CodeDescription
PENDING_PAYMENT_INITIATIONPayment request is pending for initiation.
PAYMENT_INITIATION_REJECTEDPayment request is rejected.
","example":"PENDING_PAYMENT_INITIATION","enum":["PENDING_PAYMENT_INITIATION","PAYMENT_INITIATION_REJECTED"]},"created_at":{"type":"string","description":"Payment request creation date in UTC format.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"Payment request modification date in UTC format.","example":"2022-03-21 16:25:00.190831"},"agreement_id":{"type":"string","description":"Unique agreement identifier generated by NPPA.","example":"ef0fcd9799431ef783204966f010603c"}}},"CreateAgreementResponse":{"type":"object","properties":{"agreement_uuid":{"type":"string","description":"Agreement uuid","example":"b2dd5934-478c-45ce-9528-b63c869e6f28"},"status":{"type":"string","description":"Status of the create agreement request.","example":"PENDING_CREATION"},"created_at":{"type":"string","description":"creation date.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"modification date.","example":"2022-03-22 16:25:00.190831"}}},"AgreementInformation":{"required":["agreement_type","creditor_info","debtor_info","payment_initiator_info","payment_terms","purpose_code","validity_start_date"],"type":"object","properties":{"description":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 characters.\n\nDescribes 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.","example":"agreement desc"},"short_description":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 characters.\n\nDescribes 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.","example":"short desc"},"purpose_code":{"title":"PurposeCode","type":"string","description":"

Specifies the high-level purpose of the mandate based on a set of pre-defined categories.\nMost appropriate code that represents the purpose for which this agreement is being established.

\n
CodeDescription
MORTMortgage payments, including payments for a home/business loan
UTILUtility payments such as gas, electricity, water etc
LOANLoan payments, other than mortgage payments
DEPDDependant support payments (e.g. child support)
RETLRetail payments, including e-commerce and online shopping (payments are for provision of goods or services)
SALASalary payments
PERSPersonal payments (payments to an individual which excludes any payments for salary and superannuation purposes)
GOVTGovernment payments
PENSPension payments (superannuation payments)
TAXSTax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)
OTHROther service related payments (when there is no other appropriate purpose code)
","enum":["MORT","UTIL","LOAN","DEPD","RETL","SALA","PERS","GOVT","PENS","TAXS","OTHR"]},"agreement_type":{"title":"AgreementType","type":"string","description":"

Agreement type to be created.

\n
CodeNameDescription
AUPMAuthorisedPaymentMandateEstablished bilaterally as 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\".
MGCRMigratedByCreditorEstablished by migration from legacy service by Creditor.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.
","enum":["AUPM","MGCR"]},"automatic_renewal":{"type":"boolean","description":"Indicates a \"Yes\" or \"No\" type of answer for an element.\n\nAutomatic 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":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A date expressed in the YYYY-MM-DD format.\n\nValidity start date of the agreement. The agreement is valid as of 00:00:00.000 Australia Sydney time on this date.","format":"yyyy-MM-dd","example":"2022-04-05"},"validity_end_date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A date expressed in the YYYY-MM-DD format.\n\nValidity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date.","format":"yyyy-MM-dd","example":"2022-04-25"},"transfer_arrangement":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 characters.\n\nAdditional 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.\n","example":"transfer arrangement"},"debtor_info":{"$ref":"#/components/schemas/DebtorInformation"},"creditor_info":{"$ref":"#/components/schemas/CreditorInformation"},"payment_initiator_info":{"$ref":"#/components/schemas/PaymentInitiatorInformation"},"payment_terms":{"$ref":"#/components/schemas/PaymentTermsDetails"}},"description":"Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor.\n \n **Property descriptions**: \n \n - **description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. \n If the description is less than 35 characters, then the Short Description should be used instead of the Description field.\n - **short_description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. \n If the description is less than 35 characters, then the Short Description should be used instead of the Description field. \n- **purpose_code** - Most appropriate code that represents the purpose for which this agreement is being established. \n \n Supported values: \n \n - MORT - Mortgage payments, including payments for a home/business loan\n - UTIL - Utility payments such as gas, electricity, water etc\n - LOAN - Loan payments, other than mortgage payments\n - DEPD - Dependant support payments (e.g. child support)\n - RETL - Retail payments, including e-commerce and online shopping (payments are for provision of goods or services)\n - SALA - Salary payments\n - PERS - Personal payments (payments to an individual which excludes any payments for salary and superannuation purposes)\n - GOVT - Government payments\n - PENS - Pension payments (superannuation payments)\n - TAXS - Tax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)\n - OTHR - Other service related payments (when there is no other appropriate purpose code)\n - **agreement_type** - Agreement type to be created. \n \n Supported values: \n \n - 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\".\n - 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. \n - **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. \n- **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. \n- **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. \n- **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. \n- **debtor_info** - Debtor and Debtor Account Details. \n- **creditor_info** - Creditor Details. \n- **payment_initiator_info** - Initiating party details. \n- **payment_terms** - Set of characteristics detailing agreement payment information. \n\n The following rules apply to this structure: \n\n - **DescriptionAndShortDescriptionRule:** Either 'description' or 'short_description' must be present. \n\n - **AgreementTypeRule:** If 'agreement_type' is equal to 'MGCR' then payid details must be absent. \n\n - **ValidityStartDateRule:** validity_start_date should be either current date OR future date. \n\n - **ValidityStartAndEndDateRule:** validity_end_date should be either current date OR future date. \n\n - **AutomaticExtensionRule:** validity_end_date must be present only if 'automatic_renewal' is false. "},"CreditorInformation":{"required":["ultimate_creditor_name"],"type":"object","properties":{"ultimate_creditor_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nThis 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.","example":"ultimate creditor name"},"creditor_reference":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nReference relevant to the Creditor. Example - Invoice number.","example":"creditor reference"}},"description":"Creditor Details. \n \n**Property descriptions**: \n - **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.\n - **creditor_reference** - Reference relevant to the Creditor. Example - Invoice number. "},"DebtorAccountInformation":{"required":["account_id_type"],"type":"object","properties":{"account_id_type":{"title":"AccountIdentificationTypeCodeEnum","type":"string","description":"

Specifies the type of account identification.\n\nDebtor's bank account type

","example":"PAYID","enum":["BBAN","PAYID"]},"account_id":{"maxLength":34,"minLength":10,"type":"string","description":"Specifies a character string with a maximum length of 34 ASCII printable characters.\n\nDebtor's actual bank account number (BSB + Account Number).","example":"033547123456789"},"payid_details":{"$ref":"#/components/schemas/DebtorAccountPayidInformation"}},"description":"Debtor Account Details.\n \n **Property descriptions**: \n \n - **account_id_type** - Debtor's bank account type.\n Supported values: \n \n - BBAN (bsb/account)\n - PAYID (PayID)\n - **account_id** - Debtor's actual bank account number (BSB + Account Number).\n - **debtor_account_payid_details** - Debtor account PayID Details. \n\n \n The following rules apply to this structure: \n - AccountIdentificationRule1: If account_id_type is not equal to value 'PAYID' then account_id must be present, and payid_type and payid must be absent. \n - AccountIdentificationRule2: If account_id_type is equal to value 'PAYID' then payid_type and payid must be present, and account_id must be absent. \n - AccountIdentificationRule3: When account_id_type is 'BBAN', the account_id field should contain BSB in the first 6 positions followed by the account number. \n String with minimum length of 13 characters should be provided."},"DebtorAccountPayidInformation":{"type":"object","properties":{"payid_type":{"title":"DebtorAccountPayidTypeCode","type":"string","description":"

PayID type associated with Debtor's bank account:

CodeDescription
BBANBasic Bank Account Number
PAYIDPay Id
CodeDescription
TELITelephone Number (Note that the ISO Code is TELE, but in AU-NPP context, TELI is used)
EMALEmail Address
AUBNAustralian Business Number
ORGNOrganisation Identifier
","enum":["TELI","EMAL","AUBN","ORGN"]},"payid":{"maxLength":2048,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 2048 characters. \n \n PayID as provided by the debtor.\n 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. \n \n Format pattern: ^\\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$ \n \n Email (EMAL): \n \n 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. \n \n 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])?)$ \n \n **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. \n \n Format pattern: (MIN9 - MAX11 digit): ^((\\d{9})|(\\d{11}))$ \n \n **Organisation (ORGN):** \n \n The Identifier must include the company/organisation name and both/either the description of the business/ trade / product / campaign and/or geographic location. \n \n Format pattern: Maximum of 256 characters in lower case, to be drawn from the NPP Character Set and without leading or trailing whitespace. \n \n ^[!-@[-~][ -@[-~]{0,254}[!-@[-~]$ \n ","example":"payid"}},"description":"Debtor account PayID Details.\n\n **Property descriptions**: \n \n - **payid_type** - PayID type associated with Debtor's bank account. \n\n Supported values: \n \n - EMAL - Email Address\n - TELE - Telephone Number\n - AUBN - Australian Business Number\n - ORGN - Organisational Identifier\n - **payid** - PayID as provided by the debtor. "},"DebtorInformation":{"required":["debtor_account_details","debtor_details"],"type":"object","properties":{"debtor_account_details":{"$ref":"#/components/schemas/DebtorAccountInformation"},"debtor_details":{"$ref":"#/components/schemas/DebtorInformationDetails"}},"description":"Debtor and Debtor Account Details.\n \n **Property descriptions**: \n \n - **debtor_account_details** - Debtor Account Details. \n - **debtor_details** - Debtor Details. \n "},"DebtorInformationDetails":{"required":["debtor_name","debtor_type","ultimate_debtor_name"],"type":"object","properties":{"debtor_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nSpecifies the name by which the debtor is known and which is usually used to identify that debtor.","example":"debtor name"},"debtor_type":{"title":"DebtorType","type":"string","description":"Specifies the type of debtor involved in the transaction. \n\n Identifies debtor type.\n
CodeNameDescription
ORGNOrganisationDebtor is an organisation.
PERSPersonDebtor is a private individual.
","enum":["ORGN","PERS"]},"ultimate_debtor_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nThis 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.","example":"ultimate name"},"debtor_id":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nUnique and unambiguous ID of the debtor.","example":"debtor identification"},"debtor_id_type":{"title":"DebtorIdTypeCode","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters. Specifies the code indicating the identification type of the debtor

CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["ARNU","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"debtor_reference":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nReference 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.","example":"debtor reference"}},"description":"Debtor Details. \n \n **Property descriptions**: \n\n - **debtor_name** - Specifies the name by which the debtor is known and which is usually used to identify that debtor. \n - **debtor_type** - Identifies debtor type. \n \n Supported values: \n \n - ORGN = an organisation\n - PERS = a private individual\n - **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. \n - **debtor_id** - Unique and unambiguous ID of the debtor. \n - **debtor_id_type** - Indicates Debtor Id types. \n \n - **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.\n\n \n The following rules apply to this structure: \n - DebtorIdentificationAndTypeRule1: If debtor_id is present then debtor_id_type must be present.\n - DebtorIdentificationAndTypeRule2: If debtor_id is absent then debtor_id_type must be absent."},"FirstPaymentInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"1500"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.\n\nIf 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.","example":"2022-04-15"}},"description":"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. \n \n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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."},"LastPaymentInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"2000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.\n\nIf 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.","example":"2022-04-15"}},"description":"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. \n\n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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."},"MaximumAmountInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"5000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]}},"description":"Represents the maximum amount that may be debited in any single payment initiation. \n\n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account."},"PaymentAmountInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"type":{"title":"PaymentAmountType","type":"string","description":"

Specific type of payment amount.

Depending on the use-case for which the payment arrangement is being made, an appropriate amount type should be selected for the agreement as this defines the payments that can be initiated via the agreement.

CodeNameDescription
FIXEFixedPayments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.
BALNBalloonPayments 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).
USGBUsageBasedIf 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.
VARIVariableIf 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.
","enum":["BALN","FIXE","USGB","VARI"]}},"description":"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. \n \n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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.\n Supported values: \n - FIXE - Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.\n - 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).\n - 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.\n - 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."},"PaymentInitiatorInformation":{"required":["initiator_id","initiator_id_type_code","initiator_legal_name","initiator_name"],"type":"object","properties":{"initiator_id":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nUnique and unambiguous identification of the initiator of the PayTo payment i.e. either platform or any third party details.","example":"initiator identification"},"initiator_id_type_code":{"title":"PaymentInitiatorIdTypeCodeEnum","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters.

\n\n 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
CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSIRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["AUBN","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"initiator_legal_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nName 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.","example":"initiator legal name"},"initiator_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nName 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.","example":"initiator name"}},"description":"Initiating party details. \n \nYour 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.\n\nPlease 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.\n\nPlease 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.\n\n**Property descriptions:** \n - **initiator_id** - Unique and unambiguous identification of the initiator of the PayTo payment i.e. either platform or any third party details.\n - **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\n - **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.\n - **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.\n - 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."},"PaymentTermsDetails":{"required":["frequency","payment_amount_info"],"type":"object","properties":{"payment_amount_info":{"$ref":"#/components/schemas/PaymentAmountInformation"},"first_payment_info":{"$ref":"#/components/schemas/FirstPaymentInformation"},"last_payment_info":{"$ref":"#/components/schemas/LastPaymentInformation"},"maximum_amount_info":{"$ref":"#/components/schemas/MaximumAmountInformation"},"payment_executed_not_before_time":{"pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.[0-9]{1,3})?Z$","type":"string","description":"Specifies a time in the format HH:mm:ssZ.\n\nSpecifies 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.","example":"02:30:19Z"},"point_in_time":{"pattern":"^[0-9]\\d?$","type":"string","description":"Specifies a number in string format up to two digit.\n\nQualifies 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.","example":"24"},"count_per_period":{"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies a valid non decimal numeric value.\n\nDefines 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.","example":"10"},"frequency":{"title":"PaymentFrequency","type":"string","description":"

Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement.

\n
CodeNameDescription
ADHOCAdhocEvent takes place on request or as necessary.
INTRDYIntraDayEvent takes place several times a day.
DAILYDailyEvent takes place every day.
WEEKLYWeeklyEvent takes place once a week.
FRTNLYFortnightlyEvent takes place every two weeks.
MNTHLYMonthlyEvent takes place every month or once a month.
QURTLYQuarterlyEvent takes place every three months or four times a year.
HFYRLYHalfYearlyEvent takes place every six months or two times a year.
YEARLYYearlyEvent takes place every year or once a year.
","example":"INTRDY","enum":["ADHOC","INTRDY","DAILY","WEEKLY","FRTNLY","MNTHLY","QURTLY","HFYRLY","YEARLY"]}},"description":"Specifies payment terms for the agreement i.e. amount that can be debited per payment, min/max amounts, first and last payment terms etc.\nAll the payments initiated should be as per agreement terms.\n\nIt is very important to ensure the payments initiated **DO NOT BREACH** the agreement terms and conditions - this could lead to:\n\n- Agreement claims by debtor/payer for an amount greater than the actual payment amount\n\n **Property descriptions**: \n \n - **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.\n - **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.\n - **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.\n - **maximum_amount** - Represents the maximum amount that may be debited in any single payment initiation.\n - **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).\n 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.\n - **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.\n - Frequency = Adhoc -> point in time is not applicable\n - Frequency = IntraDay -> Point In Time = hour within day (1-24)\n - Frequency = Daily -> Point In Time = hour within day (1-24))\n - Frequency = Weekly -> Point In Time = day of week (1-7)\n - Frequency = Fortnightly -> Point In Time = day within fortnight (1-14)\n - Frequency = Monthly -> Point In Time = day of month (1- last day of month)\n - Frequency = Quarterly -> Point In Time = which month within the quarter of year (1-4)\n - Frequency = HalfYearly -> Point In Time = which month within the half of the year (1-6)\n - Frequency = Yearly -> Point In Time = month within the year (1-12)\n - **count_per_period** - Defines the number of authorised expected payments that are to be initiated according to the frequency.\n Example - With Frequency = Adhoc, Count Per Period can be used to specify a total number of allowed initiations.\n - **frequency** - Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement. \n \n Must be one of following: \n \n - Adhoc (Event takes place on request or as necessary)\n - Intraday (Event takes place several times a day)\n - Daily (Event takes place every day)\n - Weekly (Event takes place once a week)\n - Fortnightly (Event takes place every two weeks)\n - Monthly (Event takes place every month)\n - Quarterly (Event takes place every three months)\n - Half Yearly (Event takes place every six months or two times a year)\n - Yearly (Event takes place every year or once a year)\n The following rules apply to this structure: \n \n - **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.\n - **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.\n - **CurrencyAUD:** All currencies must be in AUD only.\n - **AmountRule:** All amounts should be less than or equal to Maximum amount.\n - **LastAndFirstPaymentDate:** last_payment_date cannot be less than first_payment_date.\n - **PaymentAmountTypeRule:** If payment_amount_type code is equal to value 'FIXE' then amount must be present.\n - **FrequencyCombinationRule:** The frequency, point_in_time and count_per_period combination must be valid.\n Refer frequency rules table below for valid combinations.\n - **PaymentAmountTypeCombinationRule:** The payment_amount_type, amount and maximum_amount combination must be valid.\n Refer payment amount type rules table below for valid combination. \n \n **Rules for frequency:** \n \n Valid values for frequency, point_in_time and count_per_period are given below.\n
frequencypoint_in_timecount_per_period
ADHOCMust not be presentValid non decimal numeric value, greater than zero
INTRDY01 to 24Not present
INTRDYNot presentValid non decimal numeric value, greater than zero
DAILY01 to 24Not present
DAILYNot presentValid non decimal numeric value, greater than zero
WEEKLY01 to 07Not present
WEEKLYNot presentValid non decimal numeric value, greater than zero
FRTNLY01 to 14Not present
FRTNLYNot presentValid non decimal numeric value, greater than zero
MNTHLY01 to 31Not present
MNTHLYNot presentValid non decimal numeric value, greater than zero
QURTLY01 to 03Not present
QURTLYNot presentValid non decimal numeric value, greater than zero
HFYRLY01 to 06Not present
HFYRLYNot presentValid non decimal numeric value, greater than zero
YEARLY01 to 12Not present
YEARLYNot presentValid non decimal numeric value, greater than zero
\n \n **Payment amount types rules:** \n
Payment_amount_typeamountmax_ AmountRemarks
BALNValid numeric valueNAIf Balloon, only amount should have values. Max amount should not be present
FIXEValid numeric valueNAIf Fixed, only amount should have values. Max amount should not be present
USGBValid numeric valueValid numeric valueIf Usage based, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount
VARIValid numeric valueValid numeric valueIf Variable, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount
"},"ValidateAgreementRequest":{"required":["agreement_info","priority","user_external_id"],"type":"object","properties":{"user_external_id":{"maxLength":254,"minLength":1,"type":"string","description":"Specifies a character string\n\nUnique id of the user (created via Create User API) with whom the agreement should be associated with.","example":"buyer-147043828"},"priority":{"title":"Priority","type":"string","description":"

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

\n
CodeDescription
ATTENDEDIf the marketplace wants the debtor user to be notified about the agreement creation/amendment authorisation action immediately, the priority should be set as Attended.
UNATTENDEDIf 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.
","enum":["ATTENDED","UNATTENDED"]},"response_requested_by":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.[0-9]{1,3})?(?:Z)$","type":"string","description":"A date expressed in the YYYY-MM-DD'T'HH:mm:ss[.SSS][.SS][.S]'Z' format and in Australia timezone.\n\nThis 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.","format":"yyyy-MM-dd'T'HH:mm:ss[.SSS][.SS][.S]'Z'","example":"2022-11-04T06:24:34.214Z"},"agreement_info":{"$ref":"#/components/schemas/AgreementInformation"}},"description":"Definition of the agreement validation request data.\n \n **Property descriptions**: \n \n - **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.\n - **priority** - Priority of the agreement creation/amendment authorisation notification to be sent to the user for approval. \n \n Supported values: \n \n - 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. \n \n - 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.\n - **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.\n - **agreement_info** - Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor.\n"},"ValidateAgreementResponse":{"type":"object","properties":{"agreement_uuid":{"type":"string","description":"Agreement uuid.","example":"b2dd5934-478c-45ce-9528-b63c869e6f28"},"status":{"type":"string","description":"Status of the validate agreement request.","example":"PENDING_VALIDATION"},"created_at":{"type":"string","description":"creation date.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"modification date.","example":"2022-03-22 16:25:00.190831"}}},"AmendAgreementStatusRequest":{"required":["status"],"type":"object","properties":{"status":{"title":"Status","type":"string","description":"

Identifies the agreement status.

\n
CodeDescription
CANCELLEDCancel the agreement
SUSPENDEDSuspend the agreement
ACTIVEActivate the agreement

Expected status of the agreement post amendment.

","example":"SUSPENDED","enum":["CANCELLED","SUSPENDED","ACTIVE"]},"reason_code":{"title":"ReasonCode","type":"string","description":"

Reason for status amendment. Supported values:

\n
CodeDescription
REQCUSTRequested by Debtor
REQINTPRTYRequested by Initiating Party
","enum":["REQCUST","REQINTPRTY"]},"reason_description":{"maxLength":256,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 256 characters.\n\nAmendment reason description","example":"Reason description"}},"description":"Request to change the status of an agreement.\n\n**Property descriptions**:\n- status - Expected status of the agreement post amendment.\n- reason_code - Reason for status amendment.\n- reason_description - Amendment reason description.\n\n**The following rules apply to this structure**:\n- ReasonCodeRule: reason_code is mandatory if agreement needs to be 'CANCELLED' or 'SUSPENDED'."},"AmendAgreementStatusResponse":{"type":"object","properties":{"agreement_uuid":{"type":"string","description":"Unique agreement identifier.","example":"ae07556e-22ef-11eb-adc1-0242ac12000"},"agreement_id":{"type":"string","description":"Unique agreement identifier generated by NPPA.","example":"ef0fcd9799431ef783204966f010603c"},"status":{"title":"Status","type":"string","description":"

Current status of the agreement before amendment.

\n
CodeDescription
SUSPENDEDThe agreement is suspended.
ACTIVEThe agreement is active.
","example":"ACTIVE","enum":["CANCELLED","SUSPENDED","ACTIVE"]},"created_at":{"type":"string","description":"creation date.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"modification date.","example":"2022-03-22 16:25:00.190831"}},"description":"Specific characteristics of an agreement status amendment response."},"RecallAgreementActionResponse":{"type":"object","properties":{"message":{"type":"string"}}},"AmendAgreementDetailsRequest":{"required":["priority"],"type":"object","properties":{"priority":{"title":"Priority","type":"string","description":"

Identifies the arrangement (attended or unattended).

\n\nPriority of the agreement amendment authorisation notification to be sent to the user for approval.
CodeDescription
ATTENDEDIf the marketplace wants the debtor user to be notified about the agreement amendment authorisation action immediately, the priority should be set as Attended.
UNATTENDEDIf the marketplace wants the debtor user to be notified about the agreement amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended.
","enum":["ATTENDED","UNATTENDED"]},"response_requested_by":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.[0-9]{1,3})?(?:Z)$","type":"string","description":"A date expressed in the YYYY-MM-DD'T'HH:mm:ss[.SSS][.SS][.S]'Z' format and in Australia timezone.\n\nThis field can be used to specify a custom expiry duration for the authorisation request pending debtor’s approval. Any duration which is less than the default & max duration of 5 days will be accepted. Example - If you want the debtor to approve the changes proposed on the agreement within 15 mins post creation, mention the duration in this field accordingly. However, post the duration (after 15 mins), you would need to invoke the Recall API to expire this authorisation request.","format":"yyyy-MM-dd'T'HH:mm:ss[.SSS][.SS][.S]'Z'","example":"2022-11-04T06:24:34.214Z"},"unilateral_amendments":{"$ref":"#/components/schemas/UnilateralAmendments"},"bilateral_amendments":{"$ref":"#/components/schemas/BilateralAmendments"}},"description":"Request to amend the details of an agreement.\n\n **Property descriptions**: \n - **priority** - Priority of the agreement amendment authorisation notification to be sent to the user for approval. Supported values:\n - **Attended** - If the marketplace wants the debtor user to be notified about the agreement amendment authorisation action immediately, the priority should be set as Attended.\n - **Unattended** - If the marketplace wants the debtor user to be notified about the agreement amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended.\n- **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 changes proposed on the agreement within 15 mins post creation, mention the duration in this field accordingly. However, post the duration (after 15 mins), you would need to invoke the Recall API to expire this authorisation request.\n\n- **unilateral_amendments** - Specifies fields for which amendments are effective immediately and do not require debtor authorisation.\n- **bilateral_amendments** - Specifies fields for which amendments are effective only post debtor authorisation."},"AmendCreditorInformation":{"type":"object","properties":{"ultimate_creditor_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nThis 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.","example":"ultimate creditor name"},"creditor_reference":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nReference relevant to the Creditor. Example - Invoice number.","example":"creditor reference"}},"description":"Information concerning the creditor party identified in the agreement. \n \n**Property descriptions**: \n - **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.\n - **creditor_reference** - Reference relevant to the Creditor. Example - Invoice number."},"AmendFirstPaymentInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"1500"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.\n\nIf the payment arrangement being established specifies the first date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to \"-\" indicates that the date is to be cleared on the agreement.","format":"yyyy-MM-dd","example":"2022-04-15"}},"description":"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. \n \n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **date** - If the payment arrangement being established specifies the first date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to \"-\" indicates that the date is to be cleared on the agreement."},"AmendLastPaymentInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"2000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.\n\nIf the payment arrangement being established specifies the date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to \"-\" indicates that the date is to be cleared on the agreement.","format":"yyyy-MM-dd","example":"2022-04-15"}},"description":"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. \n\n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **date** - If the payment arrangement being established specifies the date (until 23:59:59.999 Australia Sydney time, expressed in the YYYY-MM-DD format) on which payment is expected to be initiated, that date should be specified in this field. Setting this property to \"-\" indicates that the date is to be cleared on the agreement."},"AmendMaximumAmountInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"5000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]}},"description":"Represents the maximum amount that may be debited in any single payment initiation. \n\n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account."},"AmendPaymentAmountInformation":{"type":"object","properties":{"amount":{"maxLength":19,"minLength":1,"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies an amount in cents.\n\n\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".\n\nCurrency of the payment to debit the account.","example":"AUD","enum":["{AUD}"]},"type":{"title":"PaymentAmountType","type":"string","description":"

Specific type of payment amount.

Depending on the use-case for which the payment arrangement is being made, an appropriate amount type should be selected for the agreement as this defines the payments that can be initiated via the agreement.

CodeNameDescription
FIXEFixedPayments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.
BALNBalloonPayments 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).
USGBUsageBasedIf 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.
VARIVariableIf 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.
","enum":["BALN","FIXE","USGB","VARI"]}},"description":"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. \n \n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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.\n Supported values: \n - FIXE - Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.\n - 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).\n - 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.\n - 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."},"AmendPaymentInitiatorInformation":{"type":"object","properties":{"initiator_id":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.\n\nUnique and unambiguous identification of the initiator.","example":"initiator identification"},"initiator_id_type_code":{"title":"PaymentInitiatorIdTypeCodeEnum","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters.

\n\nCode 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
CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSIRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["AUBN","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"initiator_legal_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nName by which the initiator is legally known.","example":"initiator legal name"},"initiator_name":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.\n\nName by which the initiator is known and which is usually used to identify them.","example":"initiator name"}},"description":"Initiating party details. \n \n**Property descriptions**: \n - **initiator_id** - Unique and unambiguous identification of the initiator.\n - **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\n - **initiator_legal_name** - Name by which the initiator is legally known.\n - **initiator_name** - Name by which the initiator is known and which is usually used to identify them."},"AmendPaymentTermsDetails":{"type":"object","properties":{"payment_amount_info":{"$ref":"#/components/schemas/AmendPaymentAmountInformation"},"first_payment_info":{"$ref":"#/components/schemas/AmendFirstPaymentInformation"},"last_payment_info":{"$ref":"#/components/schemas/AmendLastPaymentInformation"},"maximum_amount_info":{"$ref":"#/components/schemas/AmendMaximumAmountInformation"},"payment_executed_not_before_time":{"pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.[0-9]{1,3})?Z$","type":"string","description":"Specifies a time in the format HH:mm:ssZ.\n\nSpecifies the Australia Sydney time after which payments may be initiated on the execution day (according to the frequency and other payment terms). Example - Payroll scenario, where the employer requests to not initiate payrolls until a particular time to ensure funds are available for the payment to occur. Setting this property to \"-\" indicates that the time is to be cleared on the agreement.","example":"02:30:19Z"},"point_in_time":{"pattern":"^[0-9]\\d?$","type":"string","description":"Specifies a number in string format up to two digit.\n\nQualifies the frequency in terms of an exact point in time or moment within the specified period. The granularity of point in time is a subdivision of frequency. Setting this property to \"-\" indicates that the point in time is to be cleared on the agreement.
FrequencyDescription
AdhocPoint in time is not applicable
IntraDayPoint In Time = hour within day (1-24))
DailyPoint In Time = hour within day (1-24)
WeeklyPoint In Time = day of week (1-7)
FortnightlyPoint In Time = day within fortnight (1-14)
MonthlyPoint In Time = day of month (1- last day of month)
QuarterlyPoint In Time = day of month within the quarter of year (1-4)
HalfYearlyPoint In Time = day of month within the half of the year (1-6)
YearlyPoint In Time = month within the year (1-12)
","example":"24"},"count_per_period":{"pattern":"^(?=.{1,19}$)[1-9]{1}[0-9]{0,18}$","type":"string","description":"Specifies a valid non decimal numeric value.\n\nDefines the number of authorised expected payments that are to be initiated according to the frequency. Example - With Frequency = Adhoc, Count Per Period can be used to specify a total number of allowed initiations. Setting this property to \"-\" indicates that the count per period is to be cleared on the agreement.","example":"10"},"frequency":{"title":"PaymentFrequency","type":"string","description":"

Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement.

\n
CodeNameDescription
ADHOCAdhocEvent takes place on request or as necessary.
INTRDYIntraDayEvent takes place several times a day.
DAILYDailyEvent takes place every day.
WEEKLYWeeklyEvent takes place once a week.
FRTNLYFortnightlyEvent takes place every two weeks.
MNTHLYMonthlyEvent takes place every month or once a month.
QURTLYQuarterlyEvent takes place every three months or four times a year.
HFYRLYHalfYearlyEvent takes place every six months or two times a year.
YEARLYYearlyEvent takes place every year or once a year.
","example":"INTRDY","enum":["ADHOC","INTRDY","DAILY","WEEKLY","FRTNLY","MNTHLY","QURTLY","HFYRLY","YEARLY"]}},"description":"Specifies payment terms for the agreement i.e. amount that can be debited per payment, min/max amounts, first and last payment terms etc.\nAll the payments initiated should be as per agreement terms.\n\nIt is very important to ensure the payments initiated **DO NOT BREACH** the agreement terms and conditions - this could lead to:\n\n- Agreement claims by debtor/payer for an amount greater than the actual payment amount\n\n **Property descriptions**: \n \n - **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.\n - **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.\n - **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.\n - **maximum_amount** - Represents the maximum amount that may be debited in any single payment initiation.\n - **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).\n 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.\n Setting this property to \"-\" indicates that the time is to be cleared on the agreement.\n - **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. Setting this property to \"-\" indicates that the point in time is to be cleared on the agreement.\n - Frequency = Adhoc -> point in time is not applicable\n - Frequency = IntraDay -> Point In Time = hour within day (1-24)\n - Frequency = Daily -> Point In Time = hour within day (1-24))\n - Frequency = Weekly -> Point In Time = day of week (1-7)\n - Frequency = Fortnightly -> Point In Time = day within fortnight (1-14)\n - Frequency = Monthly -> Point In Time = day of month (1- last day of month)\n - Frequency = Quarterly -> Point In Time = which month within the quarter of year (1-4)\n - Frequency = HalfYearly -> Point In Time = which month within the half of the year (1-6)\n - Frequency = Yearly -> Point In Time = month within the year (1-12)\n - **count_per_period** - Defines the number of authorised expected payments that are to be initiated according to the frequency.\n Example - With Frequency = Adhoc, Count Per Period can be used to specify a total number of allowed initiations.\n Setting this property to \"-\" indicates that the count per period is to be cleared on the agreement.\n - **frequency** - Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement. \n \n Must be one of following: \n \n - Adhoc (Event takes place on request or as necessary)\n - Intraday (Event takes place several times a day)\n - Daily (Event takes place every day)\n - Weekly (Event takes place once a week)\n - Fortnightly (Event takes place every two weeks)\n - Half Yearly (Event takes place every six months or two times a year)\n - Monthly (Event takes place every month)\n - Quarterly (Event takes place every three months)\n - Yearly (Event takes place every year or once a year)\n **The following rules apply to this structure:** \n \n - **AgreementFirstPaymentRule1:** 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.\n - **AgreementLastPaymentRule2:** 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.\n - **LastAndFirstPaymentDate:** Date provided in last_payment_info should be same OR after the date provided in first_payment_info.\n - **CurrencyAUD:** All currencies must be in AUD only.\n - **AmountRule:** All amounts should be less than or equal to Maximum amount.\n - **PaymentAmountTypeRule:** If payment_amount_type code is equal to value 'FIXE' then amount must be present.\n - **FrequencyCombinationRule:** The frequency, point_in_time and count_per_period combination must be valid.\n Refer frequency rules table below for valid combinations.\n - **PaymentAmountTypeCombinationRule:** The payment_amount_type, amount and maximum_amount combination must be valid.\n Refer payment amount type rules table below for valid combination. \n\n **Rules for frequency:** \n\n Valid values for frequency, point_in_time and count_per_period are given below.\n
frequencypoint_in_timecount_per_period
ADHOCMust not be presentValid non decimal numeric value, greater than zero
INTRDY01 to 24Not present
INTRDYNot presentValid non decimal numeric value, greater than zero
DAILY01 to 24Not present
DAILYNot presentValid non decimal numeric value, greater than zero
WEEKLY01 to 07Not present
WEEKLYNot presentValid non decimal numeric value, greater than zero
FRTNLY01 to 14Not present
FRTNLYNot presentValid non decimal numeric value, greater than zero
MNTHLY01 to 31Not present
MNTHLYNot presentValid non decimal numeric value, greater than zero
QURTLY01 to 03Not present
QURTLYNot presentValid non decimal numeric value, greater than zero
HFYRLY01 to 06Not present
HFYRLYNot presentValid non decimal numeric value, greater than zero
YEARLY01 to 12Not present
YEARLYNot presentValid non decimal numeric value, greater than zero
\n \n **Payment amount types rules:** \n
Payment_amount_typeamountmax_ AmountRemarks
BALNValid numeric valueNAIf Balloon, only amount should have values. Max amount should not be present
FIXEValid numeric valueNAIf Fixed, only amount should have values. Max amount should not be present
USGBValid numeric valueValid numeric valueIf Usage based, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount
VARIValid numeric valueValid numeric valueIf Variable, max amount is recommended.However, amount and max amount are optional and if present, amount should be less than max amount
"},"BilateralAmendments":{"type":"object","properties":{"automatic_renewal":{"type":"boolean","description":"Indicates a \"Yes\" or \"No\" type of automatic renewal.\n\nAutomatic renewal of an agreement at the end of the defined period. An example of an automatically renewing agreement might be a gym membership that automatically rolls over, or a phone contract. If this property is omitted then the automatic renewal will not be modified as part of the amendment."},"validity_end_date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.This representation is defined in \"XML Schema Part 2: Datatypes Second Edition - W3C Recommendation 28 October 2004\" which is aligned with ISO 8601.\n\nValidity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date. If this property is omitted then the validity end date will not be modified as part of the amendment. Set this property to \"-\" to indicate that the validity end date is to be cleared on the agreement. Note - Clearing validity end date requires to provide the auto-renewal property (automatic_renewal=true)","format":"yyyy-MM-dd","example":"2022-03-18"},"transfer_arrangement":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 characters.\n\nAdditional details about the agreement terms with consideration to the transfer of items/goods/services. Examples might include payment of shares, transfer of property, or fulfilment of a purchase order. If this property is omitted then the transfer arrangement will not be modified as part of the amendment. Set this property to \"-\" to indicate that the transfer arrangement is to be cleared on the agreement.","example":"transfer arrangement"},"payment_terms":{"$ref":"#/components/schemas/AmendPaymentTermsDetails"}},"description":"Specific characteristics about the bilateral fields.\n\nSpecifies fields for which amendments are effective only post debtor authorisation.\n\n **Property descriptions**: \n \n - **automatic_renewal** - Automatic renewal of an agreement at the end of the defined period. An example of an automatically renewing agreement might be a gym membership that automatically rolls over, or a phone contract. If this property is omitted then the automatic renewal will not be modified as part of the amendment.\n- **validity_end_date** - Validity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date. If this property is omitted then the validity end date will not be modified as part of the amendment. Set this property to \"-\" to indicate that the validity end date is to be cleared on the agreement. Note - Clearing validity end date requires to provide the auto-renewal property (automatic_renewal=true)\n- **transfer_arrangement** - Additional details about the agreement terms with consideration to the transfer of items/goods/services. Examples might include payment of shares, transfer of property, or fulfilment of a purchase order. If this property is omitted then the transfer arrangement will not be modified as part of the amendment. Set this property to \"-\" to indicate that the transfer arrangement is to be cleared on the agreement.\n- **payment_terms** - Set of characteristics detailing agreement payment information. If this property is omitted then the payment information will not be modified as part of the amendment.\n\n The following rules apply to this structure: \n- **ValidityEndDateRule:** validity_end_date should be greater than OR same as validity_start_date. \n\n - **AutomaticExtensionRule:** validity_end_date should not be provided if agreement should be auto-renewed."},"UnilateralAmendments":{"type":"object","properties":{"description":{"maxLength":140,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 140 characters.\n\nDescribes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the description will not be modified as part of the amendment. Set this property to \"-\" to indicate that the description is to be cleared on the agreement.","example":"Description"},"short_description":{"maxLength":35,"minLength":1,"type":"string","description":"Specifies a character string with a maximum length of 35 characters.\n\nDescribes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the short description will not be modified as part of the amendment. Set this property to \"-\" to indicate that the short description is to be cleared on the agreement.","example":"Short description"},"creditor_info":{"$ref":"#/components/schemas/AmendCreditorInformation"},"payment_initiator_info":{"$ref":"#/components/schemas/AmendPaymentInitiatorInformation"}},"description":"Specific characteristics about the unilateral fields.\nSpecifies fields for which amendments are effective immediately and do not require debtor authorisation.\n\n **Property descriptions**: \n \n - **description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. \n If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the description will not be modified as part of the amendment. Set this property to \"-\" to indicate that the description is to be cleared on the agreement. \n - **short_description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field. If this property is omitted then the short description will not be modified as part of the amendment. Set this property to \"-\" to indicate that the short description is to be cleared on the agreement.\n- **creditor_info** - Creditor Details. If this property is omitted then the creditor information will not be modified as part of the amendment.\n- **payment_initiator_info** - Initiating party details. If this property is omitted then the payment initiator information will not be modified as part of the amendment."},"AmendAgreementDetailsResponse":{"type":"object","properties":{"agreement_uuid":{"type":"string","description":"Unique agreement identifier.","example":"ae07556e-22ef-11eb-adc1-0242ac12000"},"agreement_id":{"type":"string","description":"Unique agreement identifier generated by NPPA.","example":"ef0fcd9799431ef783204966f010603c"},"status":{"title":"Status","type":"string","description":"

Current status of the agreement before amendment.

\n
CodeDescription
SUSPENDEDThe agreement is suspended.
ACTIVEThe agreement is active.
","example":"ACTIVE","enum":["SUSPENDED","ACTIVE"]},"created_at":{"type":"string","description":"creation date.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"modification date.","example":"2022-03-22 16:25:00.190831"}},"description":"Specific characteristics of an agreement details amendment response."},"InitiatePaymentStatusResponse":{"type":"object","properties":{"payment_request_uuid":{"type":"string","description":"Unique identifier for the payment request in UUID format.","example":"d0c40d95-95b7-449b-9835-3c97c0386585"},"instruction_id":{"type":"string","description":"Unique identifier for each payment and retry request generated as per NPPA guidelines.","example":"BANKNTSTXXXI20180501000000000000010"},"agreement_uuid":{"type":"string","description":"Unique agreement identifier.","example":"d0c40d95-95b7-449b-9835-3c97c0386585"},"agreement_id":{"type":"string","description":"Unique agreement identifier generated by NPPA.","example":"00000000000010008000000000000000"},"status":{"title":"Status","type":"string","description":"Possible statuses for payment or retry requests:
CodeDescription
PENDING_PAYMENT_INITIATIONPayment request is pending for initiation.
PAYMENT_INITIATEDPayment request is initiated.
PAYMENT_INITIATION_COMPLETEDPayment request is completed.
PAYMENT_INITIATION_REJECTEDPayment request is rejected.
","enum":["PENDING_PAYMENT_INITIATION","PAYMENT_INITIATED","PAYMENT_INITIATION_COMPLETED","PAYMENT_INITIATION_REJECTED"]},"status_description":{"type":"string","description":"Free text field to provide description status","example":"status description"},"status_reason_code":{"type":"string","description":"Free text field to provide reason code:
Reason CodeDescriptionRetry eligible
ClearingAndSettlementError An error occurred during clearing and settlement of the payment. Please retry the same payment again or contact Zai support.Yes
PayeeBankOffline Payee institution is offline. Please try again or contact Zai support.No
PayerAccountNumberInvalid Payer account details or PayID provided is invalid or does not exist within NPP. Please update the agreement with correct account details and try again.No
PayeeAccountNumberInvalid Payee account details provided is invalid or does not exist within NPP. Please try again or contact Zai support.No
PayerAccountClosed Payer account provided is closed. Please update the agreement with correct account details and try again.No
InsufficientFunds Payer account has insufficient funds at the moment. Please contact the payer and retry the same payment again after funds availability.Yes
BlockedAccount Account provided is temporarily blocked. Please retry the same payment again after some time or contact the payer.Yes
PayeeAccountClosed Payee account provided is closed. Please try again or contact Zai support.No
PayerAccountTypeInvalid Payer account type is invalid - unable to debit funds within NPP. Please update the agreement with correct account details and try again or contact the payer.No
PayeeAccountTypeInvalid Payee account type is invalid - unable to credit funds within NPP. Please try again or contact Zai support.No
UnexpectedError Unexpected error occurred while processing the payment initiation request. Please try again or contact Zai support.No
TransactionForbiddenOnPayerAccountEither the Payer account does not allow debits within NPP or agreement to debit the account is not active. Please update the agreement with correct account details and try again or contact the Payer.No
NPPTransactionNotSupported Payee institution has rejected the NPP payment from Payer institution. Please try again or contact Zai support.No
UnspecifiedReason Payment initiation request has been rejected by the Payer institution without any specified reason.Yes
RequestedByPayer Payment rejection has been requested by the Payer. Please contact the Payer or retry the same payment again.Yes
UndisclosedReason Payment has been rejected due to undisclosed reasons.No
RequestedByPayer-UnspecifiedReason Payment has been rejected by the Payer without any specified reason. Please retry the same payment again or contact the Payer.Yes
Prohibited Payment has been rejected as it is considered prohibited.No
RequestedByPayerBank-UnspecifiedReasonPayment has been rejected by the Payer institution without any specified reason. Please try again or contact the Payer institution.No
PayeeNotOnAllowlistOfPayer Payee not on the allowlist/trusted list of the Payer. Please try again or contact the Payer.No
PayeeOnBlocklistOfPayer Payee is blocked/blacklisted by the Payer. Please try again or contact the Payer.No
ExceedsMaxAllowedDirectDebitTransactions The payment request exceeds the maximum number of direct debit transactions allowed on the Payer account. Please retry the same payment again or contact the Payer.Yes
ExceedsMaxAllowedDirectDebitTransactionAmountThe payment amount requested exceeds the maximum amount that can be debited from the Payer account via direct debit. Please retry the same payment again or contact the Payer.Yes
UnexpectedError-RetrySamePayment Unexpected error occurred while processing the payment initiation request. Please retry the same payment again or contact Zai support.Yes
PayerUnavailable Payer institution is unavailable. Please retry the same payment again or contact the Payer.Yes
InvalidPayerPayID PayID details of the Payer are no longer valid. Please update the agreement with correct details and try again or contact the Payer.No
PayerBSBNotNPPReachable Payer BSB is not NPP reachable. Please update the agreement with correct details and try again or contact the Payer.No
PayerNotNPPReachable Payer is no longer reachable on NPP. Please try again or cancel the agreement.No
PayeeNotNPPReachable Payee is no longer reachable on NPP. Please try again or contact Zai support.No
IncorrectPayerPayID PayID details of the Payer are no longer valid as the PayID has been ported incorrectly. Please update the agreement with correct details and try again or contact the Payer.No
NotRetryEligible Retries are allowed only if the payment has been rejected with retry eligible rejection reasons.No
EndToEndIDInvalidOrMissing EndToEndID is either invalid or missing. Please correct the end to end id and retry the same payment again.Yes
Non-CompliantPayment Payment amount is not as per the agreed payment terms and conditions. Please correct the amount and retry the same payment again.Yes
NPPLimitExceeded Payment amount requested exceeds the agreed limits for the Payer account. Please correct the amount and retry the same payment again.Yes
UnrecognisedInitiatingParty The Payer has requested the payment rejection as the Initiating party is not recognised by them. Please try again or contact the Payer.No
UnknownPayer The payment has been rejected by the Payer institution as the Payer is not known as per records. Please try again or contact the Payer.No
PayeeBSBNotNPPReachable Payee BSB is not NPP reachable. Please try again or contact Zai support.No
PayerNameOrAddressDetailsMissing Payer name or address details are missing. Please update the agreement with complete Payer details and try again.No
PayeeNameOrAddressDetailsMissing Payee name or address details are missing. Please try again or contact Zai support.No
UnknownReason Payment has been rejected due to unknown reason.No
PayeeUnavailable Payee institution is unavailable. Please retry the same payment again or contact Zai support.Yes
PayerNameMissing Payer name is missing. Please update the agreement with complete Payer details and try again.No
PayeeNameMissing Payee name is missing in the agreement. Please try again or contact Zai support.No
UnsupportedCurrency Unable to debit funds in AUD from the provided Payer account.No
AmountExceedsMaxNPPLimit Payment amount either exceeds the maximum allowed NPP limit of $99,999,999,999 or maximum allowed NPP limit for the Payer account.No
"},"status_reason_description":{"type":"string","description":"Free text field to provide reason description.","example":"reason description"},"payment_reconciled":{"type":"boolean","description":"Indicator to say whether the payment has been reconciled successfully on user's wallet or not.","example":true},"created_at":{"type":"string","description":"Payment request creation date.","example":"2022-03-21 16:25:00.312368"},"updated_at":{"type":"string","description":"Payment request modification date.","example":"2022-03-22 16:25:00.312368"},"payment_info":{"$ref":"#/components/schemas/PaymentInfo"},"retry_attempts":{"$ref":"#/components/schemas/RetryAttempts"}},"description":"Definition of PayTo Payment Details. \n\n **Property descriptions**: \n\n- **payment_request_uuid** - Unique identifier for the payment request in UUID format.\n- **instruction_id** - Unique identifier for the payment request generated as per NPPA guidelines. This identifier is used to identify the payment uniquely with NPPA and payer as well.\n- **agreement_uuid** - Unique agreement identifier.\n- **agreement_id** - Unique agreement identifier generated by NPPA.\n- **status** - Current status of the payment or retry request.\n- **status_description** - Details/description for the status.\n- **status_reason_code** - Reason code for the current payment initiation request status.\n- **status_reason_description** - Detailed description of the status reason code.\n- **payment_reconciled** - Indicator to say whether the payment has been reconciled successfully on user's wallet or not.\n - **created_at** - Date representation of the payment request creation.\n - **updated_at** - Date representation of the last update of the payment request.\n- **payment_info** - Payment information for the payment request.\n- **retry_attempts** - Payment information for all retry attempts."},"PaymentInfo":{"type":"object","properties":{"instruction_id":{"type":"string","description":"Unique identifier for each payment and retry request generated as per NPPA guidelines.","example":"BANKNTSTXXXI20180501000000000000010"},"instructed_amount":{"type":"string","description":"Specifies an amount in cents","example":"1000"},"last_payment":{"type":"boolean","description":"Indicates a \"Yes\" or \"No\" type of answer for an element.","default":false},"end_to_end_id":{"type":"string","description":"Specifies a character string with a maximum length of 35 characters."},"remittance_info":{"type":"string","description":"Specifies a character string with a maximum length of 280 characters.","example":"remittance info"},"unique_superannuation_id":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"uniqueSuperannuation id"},"unique_superannuation_code":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"uniqueSuperannuation code"}},"description":"Payment Request details.\n \n **Property descriptions**: \n \n- **instruction_id** - Unique identifier for the payment request generated as per NPPA guidelines. This identifier is used to identify the payment uniquely with NPPA and payer as well.\n- **instructed_amount** - Specifies the amount to be debited the from debtor's bank account before deduction of charges.\n- **last_payment** - Indicates that it is the last payment associated with the agreement. Post this, the agreement will be marked as CANCELLED automatically and no further payments can be requested on this agreement.\n- **end_to_end_id** - Unique identification to unambiguously identify the payment. This identification is passed on, unchanged, throughout the entire end-to-end chain. It is recommended to provide this identifier which can be passed between entities to identify the payment during queries/investigations if any. If not provided, debtor reference (if available) from the agreement will be populated. If none available, default value \"NOTPROVIDED\" will be populated in the payment initiation request.\n- **remittance_info** - Free text field to provide any narrative for the payment.\n- **unique_superannuation_code** - For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI number for the superannuation fund.\n- **unique_superannuation_id** - For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI - code indicating the identifier to whom the superannuation fund will be provided."},"RetryAttempts":{"type":"object","properties":{"count":{"type":"integer","description":"Retries count.","format":"int32","example":1},"retry_info":{"type":"array","description":"Retry info for initiate payment.","items":{"$ref":"#/components/schemas/RetryInfo"}}},"description":"List of retry attempts for the payment request. \n \n **Property descriptions**: \n\n- **count** - Payment retry count. \n\n- **retry_info** - Payment information for each retry attempt, listed in descending order of retry attempts."},"RetryInfo":{"type":"object","properties":{"instruction_id":{"type":"string","description":"Unique identifier for each payment and retry request generated as per NPPA guidelines.","example":"BANKNTSTXXXI20180501000000000000010"},"status":{"title":"Status","type":"string","description":"Possible statuses for payment or retry requests:
CodeDescription
PAYMENT_INITIATION_REJECTEDPayment request is rejected.
","enum":["PAYMENT_REJECTED"]},"status_description":{"type":"string","description":"Free text field to provide description status:","example":"status description"},"status_reason_code":{"type":"string","description":"Free text field to provide reason code:"},"status_reason_description":{"type":"string","description":"Free text field to provide reason description.","example":"reason description"},"created_at":{"type":"string","description":"Payment request creation date.","example":"2022-03-21 16:25:00.312368"},"updated_at":{"type":"string","description":"Payment request modification date.","example":"2022-03-22 16:25:00.312368"},"payment_info":{"$ref":"#/components/schemas/PaymentInfo"}},"description":"Payment information for each retry attempt. \n \n **Property descriptions**: \n \n- **instruction_id** - Unique identifier for the payment request generated as per NPPA guidelines. This identifier is used to identify the payment uniquely with NPPA and payer as well.\n- **status** - Current status of Initiate Payment Request.\n- **status_description** - Details/description for the status.\n - **created_at** - Date representation of the payment request creation.\n - **updated_at** - Date representation of the last update of the payment request.\n- **payment_info** - Payment info for payment request."},"InitiatePaymentListResponse":{"type":"object","properties":{"total_count":{"type":"integer","description":"Total number of initiate payments available","format":"int64","example":1},"initiate_payment_status_responses":{"type":"array","description":"List of Initiate Payment requests.","items":{"$ref":"#/components/schemas/InitiatePaymentStatusResponse"}}},"description":"List of Initiate Payment Status details. \n"},"AgreementDetailsResponse":{"type":"object","properties":{"agreement_uuid":{"type":"string","description":"Zai generated Universally Unique Identifier (UUID).","example":"d0c40d95-95b7-449b-9835-3c97c0386700"},"user_external_id":{"type":"string","description":"Specifies a character string.","example":"buyer-147043828"},"status":{"type":"string","description":"

Current status of the agreement:

\n
Reason CodeDescriptionRetry eligible
ClearingAndSettlementError An error occurred during clearing and settlement of the payment. Please retry the same payment again or contact Zai support.Yes
PayeeBankOffline Payee institution is offline. Please try again or contact Zai support.No
PayerAccountNumberInvalid Payer account details or PayID provided is invalid or does not exist within NPP. Please update the agreement with correct account details and try again.No
PayeeAccountNumberInvalid Payee account details provided is invalid or does not exist within NPP. Please try again or contact Zai support.No
PayerAccountClosed Payer account provided is closed. Please update the agreement with correct account details and try again.No
InsufficientFunds Payer account has insufficient funds at the moment. Please contact the payer and retry the same payment again after funds availability.Yes
BlockedAccount Account provided is temporarily blocked. Please retry the same payment again after some time or contact the payer.Yes
PayeeAccountClosed Payee account provided is closed. Please try again or contact Zai support.No
PayerAccountTypeInvalid Payer account type is invalid - unable to debit funds within NPP. Please update the agreement with correct account details and try again or contact the payer.No
PayeeAccountTypeInvalid Payee account type is invalid - unable to credit funds within NPP. Please try again or contact Zai support.No
UnexpectedError Unexpected error occurred while processing the payment initiation request. Please try again or contact Zai support.No
TransactionForbiddenOnPayerAccountEither the Payer account does not allow debits within NPP or agreement to debit the account is not active. Please update the agreement with correct account details and try again or contact the Payer.No
NPPTransactionNotSupported Payee institution has rejected the NPP payment from Payer institution. Please try again or contact Zai support.No
UnspecifiedReason Payment initiation request has been rejected by the Payer institution without any specified reason.Yes
RequestedByPayer Payment rejection has been requested by the Payer. Please contact the Payer or retry the same payment again.Yes
ClearingAndSettlementError An error occurred during clearing and settlement of the payment. Please retry the same payment again or contact Zai support.Yes
UndisclosedReason Payment has been rejected due to undisclosed reasons.No
RequestedByPayer-UnspecifiedReason Payment has been rejected by the Payer without any specified reason. Please retry the same payment again or contact the Payer.Yes
Prohibited Payment has been rejected as it is considered prohibited.No
RequestedByPayerBank-UnspecifiedReasonPayment has been rejected by the Payer institution without any specified reason. Please try again or contact the Payer institution.No
PayeeNotOnAllowlistOfPayer Payee not on the allowlist/trusted list of the Payer. Please try again or contact the Payer.No
PayeeOnBlocklistOfPayer Payee is blocked/blacklisted by the Payer. Please try again or contact the Payer.No
ExceedsMaxAllowedDirectDebitTransactions The payment request exceeds the maximum number of direct debit transactions allowed on the Payer account. Please retry the same payment again or contact the Payer.Yes
ExceedsMaxAllowedDirectDebitTransactionAmountThe payment amount requested exceeds the maximum amount that can be debited from the Payer account via direct debit. Please retry the same payment again or contact the Payer.Yes
UnexpectedError-RetrySamePayment Unexpected error occurred while processing the payment initiation request. Please retry the same payment again or contact Zai support.Yes
PayerUnavailable Payer institution is unavailable. Please retry the same payment again or contact the Payer.Yes
InvalidPayerPayID PayID details of the Payer are no longer valid. Please update the agreement with correct details and try again or contact the Payer.No
PayerBSBNotNPPReachable Payer BSB is not NPP reachable. Please update the agreement with correct details and try again or contact the Payer.No
PayerNotNPPReachable Payer is no longer reachable on NPP. Please try again or cancel the agreement.No
PayeeNotNPPReachable Payee is no longer reachable on NPP. Please try again or contact Zai support.No
IncorrectPayerPayID PayID details of the Payer are no longer valid as the PayID has been ported incorrectly. Please update the agreement with correct details and try again or contact the Payer.No
NotRetryEligible Retries are allowed only if the payment has been rejected with retry eligible rejection reasons.No
EndToEndIDInvalidOrMissing EndToEndID is either invalid or missing. Please correct the end to end id and retry the same payment again.Yes
Non-CompliantPayment Payment amount is not as per the agreed payment terms and conditions. Please correct the amount and retry the same payment again.Yes
NPPLimitExceeded Payment amount requested exceeds the agreed limits for the Payer account. Please correct the amount and retry the same payment again.Yes
UnrecognisedInitiatingParty The Payer has requested the payment rejection as the Initiating party is not recognised by them. Please try again or contact the Payer.No
UnknownPayer The payment has been rejected by the Payer institution as the Payer is not known as per records. Please try again or contact the Payer.No
PayeeBSBNotNPPReachable Payee BSB is not NPP reachable. Please try again or contact Zai support.No
PayerNameOrAddressDetailsMissing Payer name or address details are missing. Please update the agreement with complete Payer details and try again.No
PayeeNameOrAddressDetailsMissing Payee name or address details are missing. Please try again or contact Zai support.No
UnknownReason Payment has been rejected due to unknown reason.No
PayeeUnavailable Payee institution is unavailable. Please retry the same payment again or contact Zai support.Yes
PayerNameMissing Payer name is missing. Please update the agreement with complete Payer details and try again.No
UnsupportedCurrency Unable to debit funds in AUD from the provided Payer account.No
AmountExceedsMaxNPPLimit Payment amount either exceeds the maximum allowed NPP limit of $99,999,999,999 or maximum allowed NPP limit for the Payer account.No
StatusDescription
PENDING_VALIDATIONAgreement validation is pending.
VALIDATEDAgreement is validated.
VALIDATION_FAILEDAgreement validation failed.
PENDING_CREATIONAgreement creation is pending.
CREATEDAgreement is created.
CREATION_FAILEDAgreement creation failed.
ACTIVEAgreement is active.
SUSPENDEDAgreement is suspended.
CANCELLEDAgreement is cancelled.
","example":"ACTIVE"},"status_description":{"type":"string","description":"Description of the associated status."},"status_reason_code":{"type":"string","description":"

Reason code of the associated status:\n
Reason CodeDescription
PayerAccountNumberInvalidPayer account details or PayID provided is invalid or does not exist within NPP.
ClosedAccountAccount provided is closed.
PayerAccountClosedPayer account provided is closed.
BlockedAccountAccount provided is temporarily blocked.
PayerAccountTypeInvalidPayer account type is invalid - unable to debit funds within NPP.
TransactionForbiddenOnPayerAccountTransaction forbidden on the provided Payer account - either agreement to debit this account does not exist/inactive or the account does not support debits within NPP.
NPPTransactionNotSupportedTransaction not supported on the provided Payer account - does not support NPP payments.
UnsupportedCurrencyUnable to debit funds in AUD from the provided Payer account.
AmountInvalidOrMissingAmount and/or maximum amount are either invalid or not specified in the agreement.
AmountExceedsAgreedLimitsForPayerAccountAmount specified in the agreement exceeds the allowed transaction amount for the Payer account.
PayerDeceasedPayer is deceased.
PayToServiceNotSupportedByPayerBankPayTo service is not supported by the Payer institution.
PayToServiceNotPermittedForPayerThis agreement type is not supported for the provided Payer customer/account OR the Payer customer account no longer supports PayTo services.
RequestedByPayerSuspension/Cancellation is requested by Payer.
RequestedByInitiatingPartySuspension/Cancellation is requested by Creditor or by the Initiating Party.
ActiveAgreementValidityExpiredValidity of the agreement has expired & is no longer active.
UndisclosedReasonSuspended/Cancelled due to undisclosed reasons.
RequestedByPayer-UnspecifiedReasonSuspended/Cancelled without any reason specified by the Payer.
RequestedByPayerBank-UnspecifiedReasonSuspended/Cancelled without any reason specified by the Payer institution.
UnspecifiedReasonSuspended/Cancelled without any specified reason.
ProhibitedSuspended/Cancelled as it is considered prohibited.
PayeeNotOnAllowlistOfPayerPayee not on the allowlist/trusted list of the Payer.
PayeeOnBlocklistOfPayerPayee is blocked/blacklisted by the Payer.
ContractAmendedExternal arrangement (or contract) between the Payer and the Initiating Party has been amended.
ContractCancellationInitiatedByDebtorExternal arrangement (or contract) cancellation has been initiated by Payer.
ContractExpiredExternal arrangement (or contract) between the Payer and the Initiating Party has expired.
FinalPaymentCompletedSuspended/Cancelled as final payment has been completed successfully.
OneOffPaymentCompletedSuspended/Cancelled as one-off payment has been completed successfully
TooManyConsecutiveUnsuccessfulPaymentsSuspended/Cancelled due to multiple consecutive unsuccessful payment attempts.
NoResponseFromPayerPayer did not respond within the expected timeframe.
UnapprovedAgreementValidityExpiredValidity of the agreement has expired before Payer authorisation.
UnknownReasonSuspended/Cancelled due to unknown reason.
","example":"RequestedByPayer"},"status_reason_description":{"type":"string","description":"Description of the reason code of the associated status."},"created_at":{"type":"string","description":"creation date.","example":"2022-03-21 16:25:00.190831"},"updated_at":{"type":"string","description":"modification date.","example":"2022-03-22 16:25:00.190831"},"agreement_info":{"$ref":"#/components/schemas/AgreementInfo"}},"description":"Definition of the agreement details response. \n\n **Property descriptions**: \n\n - **agreement_uuid** - Unique ID, used to unambiguously identify the agreement.\n - **user_external_id** - User External Id is the unique identifier of the user with whom the agreement should be associated.\n - **status** - Current status of the agreement.\n - **status_description** - Detailed description of the associated status.\n - **status_reason_code** - Reason code for the current status.\n - **status_reason_description** - Reason description if any, provided by the debtor while suspending or cancelling the agreement via banking portal.\n - **created_at** - Date representation of the initial creation of the agreement.\n - **updated_at** - Date representation of the last update of the agreement.\n - **agreement_info** - Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor."},"AgreementInfo":{"type":"object","properties":{"agreement_id":{"type":"string","description":"Unique agreement identifier generated by NPPA.","example":"00000000000010008000000000000000"},"description":{"type":"string","description":"Specifies a character string with a maximum length of 140 characters.","example":"agreement desc"},"short_description":{"type":"string","description":"Specifies a character string with a maximum length of 35 characters.","example":"short desc"},"purpose_code":{"title":"PurposeCode","type":"string","description":"

Specifies the high-level purpose of the mandate based on a set of pre-defined categories.

\n
CodeDescription
MORTMortgage payments, including payments for a home/business loan
UTILUtility payments such as gas, electricity, water etc
LOANLoan payments, other than mortgage payments
DEPDDependant support payments (e.g. child support)
RETLRetail payments, including e-commerce and online shopping (payments are for provision of goods or services)
SALASalary payments
PERSPersonal payments (payments to an individual which excludes any payments for salary and superannuation purposes)
GOVTGovernment payments
PENSPension payments (superannuation payments)
TAXSTax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)
OTHROther service related payments (when there is no other appropriate purpose code)
","enum":["MORT","UTIL","LOAN","DEPD","RETL","SALA","PERS","GOVT","PENS","TAXS","OTHR"]},"agreement_type":{"title":"AgreementType","type":"string","description":"

\n
CodeNameDescription
AUPMAuthorisedPaymentMandateEstablished bilaterally as Authorised Payment Mandate.
MGCRMigratedByCreditorEstablished by migration from legacy service by Creditor.
","enum":["AUPM","MGCR"]},"automatic_renewal":{"type":"boolean","description":"Indicates a \"Yes\" or \"No\" type of answer for an element."},"validity_start_date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A date expressed in the YYYY-MM-DD format. ","format":"yyyy-MM-dd","example":"2022-04-05"},"validity_end_date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A date expressed in the YYYY-MM-DD format. ","format":"yyyy-MM-dd","example":"2022-04-25"},"transfer_arrangement":{"type":"string","description":"Specifies a character string with a maximum length of 140 characters.","example":"transfer arrangement"},"debtor_info":{"$ref":"#/components/schemas/DebtorInfo"},"creditor_info":{"$ref":"#/components/schemas/CreditorInfo"},"payment_initiator_info":{"$ref":"#/components/schemas/PaymentInitiatorInfo"},"payment_terms":{"$ref":"#/components/schemas/PaymentTerms"}},"description":"Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor.\n \n **Property descriptions**: \n \n - **agreement_id** - Unique agreement identifier generated by NPPA.\n \n - **description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. \n If the description is less than 35 characters, then the Short Description should be used instead of the Description field.\n - **short_description** - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. \n If the description is less than 35 characters, then the Short Description should be used instead of the Description field. \n- **purpose_code** - Most appropriate code that represents the purpose for which this agreement is being established. \n\n Supported values: \n \n - MORT - Mortgage payments, including payments for a home/business loan\n - UTIL - Utility payments such as gas, electricity, water etc\n - LOAN - Loan payments, other than mortgage payments\n - DEPD - Dependant support payments (e.g. child support)\n - RETL - Retail payments, including e-commerce and online shopping (payments are for provision of goods or services)\n - SALA - Salary payments\n - PERS - Personal payments (payments to an individual which excludes any payments for salary and superannuation purposes)\n - GOVT - Government payments\n - PENS - Pension payments (superannuation payments)\n - TAXS - Tax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)\n - OTHR - Other service related payments (when there is no other appropriate purpose code)\n - **agreement_type** - Agreement type to be created. \n\n Supported values: \n \n - 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\". \n \n - 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. \n- **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. \n- **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. \n- **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. \n- **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. \n- **debtor_info** - Debtor and Debtor Account Details. \n- **creditor_info** - Creditor and Creditor Account Details. \n- **payment_initiator_info** - Initiating party details. \n- **payment_terms** - Set of characteristics detailing agreement payment information. \n"},"CreditorAccountDetails":{"type":"object","properties":{"account_id":{"type":"string","description":"Specifies a character string with a maximum length of 34 ASCII printable characters.","example":"123456789"},"account_id_type":{"title":"AccountIdType","type":"string","description":"

Specifies the type of account identification:

CodeDescription
BBANBasic Bank Account Number
PAYIDPayid Identification
","enum":["BBAN","PAYID"]}},"description":"Creditor Account Details. \n\n**Property descriptions**: \n - **account_id** - Creditor's actual bank account number (BSB + Account Number).\n - **account_id_type** - Specifies the account id type.\n Supported values: \n\n - BBAN (bsb/account)\n - PAYID"},"CreditorDetails":{"type":"object","properties":{"creditor_id":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"creditor identification"},"creditor_id_type":{"title":"CreditorIdTypeCode","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters. Specifies the code indicating the identification type of the creditor.

CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSIRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["ARNU","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"creditor_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"creditor name"},"creditor_type":{"title":"PartyType","type":"string","description":"Specifies the type of creditor involved in the transaction.\n
CodeNameDescription
ORGNOrganisationDebtor is an organisation.
PERSPersonDebtor is a private individual.
","enum":["ORGN","PERS"]},"ultimate_creditor_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"ultimate creditor name"},"creditor_reference":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"creditor reference"}},"description":"Information concerning the creditor party identified in the agreement. \n\n**Property descriptions**: \n - **creditor_id** - Unique and unambiguous identification of the creditor.\n - **creditor_id_type** - Code indicating the identification type of the creditor, 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.\n - **creditor_name** - Name by which the creditor is known and which is usually used to identify that creditor.\n - **creditor_type** - Identifies the type of a creditor.\n Supported values based on creditor type field: \n\n If Creditor Type is PERS: \n\n - CCPT = Passport Number \n - CUST = Customer Identification Number\n - DRLC = Driver’s License Number\n - EMPL = Employee Identification Number\n - TXID = Tax Identification Number \n\n If Creditor Type is ORGN: \n\n - BANK = Bank Party Identification\n - CHID = Clearing Identification Number\n - CINC = Certificate Of Incorporation Number\n - EMPL = Employer Identification Number\n - TXID = Tax Identification Number\n - **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.\n - **creditor_reference** - Reference relevant to the Creditor. Example - Invoice number."},"CreditorInfo":{"type":"object","properties":{"creditor_account_details":{"$ref":"#/components/schemas/CreditorAccountDetails"},"creditor_details":{"$ref":"#/components/schemas/CreditorDetails"}},"description":"Information concerning the creditor party identified in the agreement. \n\n**Property descriptions**: \n - **creditor_account_details** - Information containing creditor account details.\n - **creditor_details** - Information containing debtor details."},"DebtorAccountDetails":{"type":"object","properties":{"account_id":{"type":"string","description":"Specifies a character string with a maximum length of 34 ASCII printable characters.","example":"123456789"},"account_id_type":{"title":"DebtorAccountIdTypeCode","type":"string","description":"

Specifies the type of account identification:

CodeDescription
BBANBasic Bank Account Number
PAYIDPayid Identification
","example":"PAYID","enum":["BBAN","PAYID"]},"payid_details":{"$ref":"#/components/schemas/DebtorAccountPayidDetails"}},"description":"Debtor Account Details.\n\n **Property descriptions**: \n\n - **account_id** - Debtor's actual bank account number (BSB + Account Number).\n - **account_id_type** - Debtor's bank account type.\n Supported values: \n\n - BBAN (bsb/account)\n - PAYID\n - **payid_details** - Debtor account PayID Details. \n"},"DebtorAccountPayidDetails":{"type":"object","properties":{"payid_type":{"title":"DebtorAccountPayidTypeCode","type":"string","description":"

PayID type associated with Debtor's bank account:

CodeDescription
TELITelephone Number (Note that the ISO Code is TELE, but in AU-NPP context, TELI is used)
EMALEmail Address
AUBNAustralian Business Number
ORGNOrganisation Identifier
","enum":["TELI","EMAL","AUBN","ORGN"]},"payid":{"type":"string","description":"Specifies a character string with a maximum length of 2048 characters.","example":"payid"},"payid_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"payidname"}},"description":"Debtor account PayID Details.\n \n **Property descriptions**: \n\n - **payid_type** - PayID type associated with Debtor's bank account. \n\n Supported values: \n\n - EMAL - Email Address\n - TELE - Telephone Number\n - AUBN - Australian Business Number\n - ORGN - Organisational Identifier\n - **payid** - PayID as provided by the debtor.\n - **payid_name** - Debtor user's name registered with the PayID."},"DebtorDetails":{"type":"object","properties":{"debtor_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"debtor name"},"debtor_type":{"title":"DebtorType","type":"string","description":"Specifies the type of debtor involved in the transaction:\n
CodeNameDescription
ORGNOrganisationDebtor is an organisation.
PERSPersonDebtor is a private individual.
","enum":["ORGN","PERS"]},"ultimate_debtor_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"ultimate name"},"debtor_id":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"debtor identification"},"debtor_id_type":{"title":"DebtorIdTypeCode","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters. Specifies the code indicating the identification type of the debtor:

CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["ARNU","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"debtor_reference":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"debtor reference"}},"description":"Debtor Details. \n\n **Property descriptions**: \n\n - **debtor_name** - Specifies the name by which the debtor is known and which is usually used to identify that debtor.\n - **debtor_type** - Identifies debtor type. \n \n - **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.\n - **debtor_id** - Unique and unambiguous ID of the debtor.\n - **debtor_id_type** - Indicates Debtor Id types. \n\n - **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. \nIf end to end Id is not provided in the payment initiation request, then the debtor reference (if available) will be populated as end to end id in the payment initiation request."},"DebtorInfo":{"type":"object","properties":{"debtor_account_details":{"$ref":"#/components/schemas/DebtorAccountDetails"},"debtor_details":{"$ref":"#/components/schemas/DebtorDetails"}},"description":"Debtor and Debtor Account Details.\n\n **Property descriptions**: \n\n - **debtor_account_details** - Debtor Account Details.\n - **debtor_details** - Debtor Details."},"FirstPaymentInfo":{"type":"object","properties":{"amount":{"type":"string","description":"Specifies an amount in cents.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".","example":"AUD"},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format.","format":"yyyy-MM-dd","example":"2022-04-15"}},"description":"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. \n\n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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."},"LastPaymentInfo":{"type":"object","properties":{"amount":{"type":"string","description":"Specifies an amount in cents.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".","example":"AUD"},"date":{"pattern":"^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$","type":"string","description":"A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. ","format":"yyyy-MM-dd","example":"2022-04-15"}},"description":"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. \n\n **Property descriptions**: \n\n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account.\n - **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."},"MaximumAmountInfo":{"type":"object","properties":{"amount":{"type":"string","description":"Specifies an amount in cents.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".","example":"AUD"}},"description":"Represents the maximum amount that may be debited in any single payment initiation. \n\n **Property descriptions**: \n\n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account."},"PaymentAmountInfo":{"type":"object","properties":{"amount":{"type":"string","description":"Specifies an amount in cents.","example":"1000"},"currency":{"pattern":"^[A-Z]{3,3}$","type":"string","description":"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\".","example":"AUD"},"type":{"title":"PaymentAmountType","type":"string","description":"

Specific type of payment amount.

Depending on the use-case for which the payment arrangement is being made, an appropriate amount type should be selected for the agreement as this defines the payments that can be initiated via the agreement.

CodeNameDescription
FIXEFixedPayments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.
BALNBalloonPayments 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).
USGBUsageBasedIf 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.
VARIVariableIf 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.
","enum":["BALN","FIXE","USGB","VARI"]}},"description":"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. \n \n **Property descriptions**: \n \n - **amount**\n - For FIXE type of agreements, as the amount to be debited is fixed, this indicates the amount to be debited per payment.\n - 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.\n - For USGB/VARI type of agreements, this indicates the minimum amount that can be debited from the account per payment.\n - **currency** - Currency of the payment to debit the account. \n - **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.\n \n Supported values: \n - FIXE - Payments should be initiated for fixed amounts i.e. amount specified in the payment instruction must match the “amount” stated in the agreement.\n - 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).\n - 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.\n - 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."},"PaymentInitiatorInfo":{"type":"object","properties":{"initiator_id":{"type":"string","description":"Specifies a character string with a maximum length of 35 ASCII printable characters.","example":"initiator identification"},"initiator_id_type_code":{"title":"PaymentInitiatorIdTypeCodeEnum","type":"string","description":"

Specifies an alphanumeric string with a length of 4 characters:

CodeDescription
ARNUAlien Registration Number
CCPTPassport Number
CUSTCustomer Identification Number
DRLCDrivers License Number
EMPLEmployee Identification Number
NIDNNational Identity Number
SOSESocial Security Number
TXIDTax Identification Number
BANKBank Party Identification
CBIDCentral Bank Identification Number
CHIDClearing Identification Number
CINCCertificate Of Incorporation Number
COIDCountry Identification Code
DUNSData Universal Numbering System
GS1GGS1GLN Identifier
SRENSIREN
SRETSIRET
AUBNAustralian Business Number (ABN)
AUCNAustralian Company Number (ACN)
LEINLegal Entity Identification (LEI)
","enum":["AUBN","CCPT","CUST","DRLC","EMPL","NIDN","SOSE","TXID","BANK","CBID","CHID","CINC","COID","DUNS","GS1G","SREN","SRET","AUBN","AUCN","LEIN"]},"initiator_legal_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"initiator legal name"},"initiator_name":{"type":"string","description":"Specifies a character string with a maximum length of 140 ASCII printable characters.","example":"initiator name"}},"description":"Initiating party details. \n\n**Property descriptions**: \n - **initiator_id** - Unique and unambiguous identification of the initiator.\n - **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.\n - **initiator_legal_name** - Name by which the initiator is legally known.\n - **initiator_name** - Name by which the initiator is known and which is usually used to identify them."},"PaymentTerms":{"type":"object","properties":{"payment_amount_info":{"$ref":"#/components/schemas/PaymentAmountInfo"},"first_payment_info":{"$ref":"#/components/schemas/FirstPaymentInfo"},"last_payment_info":{"$ref":"#/components/schemas/LastPaymentInfo"},"maximum_amount_info":{"$ref":"#/components/schemas/MaximumAmountInfo"},"payment_executed_not_before_time":{"type":"string","description":"Specifies a time in the format HH:mm:ssZ.","example":"02:30:19Z"},"point_in_time":{"type":"string","description":"Specifies a number in string format upto two digit.","example":"24"},"count_per_period":{"type":"string","description":"Specifies a valid non decimal numeric value.","example":"10"},"frequency":{"title":"PaymentFrequency","type":"string","description":"

Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement:

\n
CodeNameDescription
ADHOCAdhocEvent takes place on request or as necessary.
INTRDYIntraDayEvent takes place several times a day.
DAILYDailyEvent takes place every day.
WEEKLYWeeklyEvent takes place once a week.
FRTNLYFortnightlyEvent takes place every two weeks.
MNTHLYMonthlyEvent takes place every month or once a month.
QURTLYQuarterlyEvent takes place every three months or four times a year.
HFYRLYHalfYearlyEvent takes place every six months or two times a year.
YEARLYAnnualEvent takes place every year or once a year.
","example":"INTRDY","enum":["ADHOC","INTRDY","DAILY","WEEKLY","FRTNLY","MNTHLY","QURTLY","HFYRLY","YEARLY"]}},"description":"Specifies payment terms for the agreement i.e. amount that can be debited per payment, min/max amounts, first and last payment terms etc.\nAll the payments initiated should be as per agreement terms.\n\nIt is very important to ensure the payments initiated **DO NOT BREACH** the agreement terms and conditions - this could lead to:\n\n- Agreement claims by debtor/payer for an amount greater than the actual payment amount\n\n **Property descriptions**: \n\n - **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.\n - **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.\n - **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. \n - **maximum_amount** - Represents the maximum amount that may be debited in any single payment initiation.\n - **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).\n 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.\n - **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. \n - Frequency=Adhoc -> point in time is not applicable\n - Frequency=IntraDay -> Point In Time = hour within day (1-24)\n - Frequency=Daily -> Point In Time = hour within day (1-24))\n - Frequency=Weekly -> Point In Time = day of week (1-7)\n - Frequency=Fortnightly -> Point In Time = day within fortnight (1-14)\n - Frequency=Monthly -> Point In Time = day of month (1- last day of month)\n - Frequency=Quarterly -> Point In Time = which month within the quarter of year (1-4)\n - Frequency=HalfYearly -> Point In Time = which month within the half of the year (1-6)\n - Frequency=Yearly -> Point In Time = month within the year (1-12)\n - **count_per_period** - Defines the number of authorised expected payments that are to be initiated according to the frequency.\n Example - With Frequency = Adhoc, Count Per Period can be used to specify a total number of allowed initiations.\n - **frequency** - Represents the typical expected frequency with which payments will be initiated against the debtor for this arrangement. \n\n Must be one of following: \n \n - Adhoc (Event takes place on request or as necessary)\n - Intraday (Event takes place several times a day)\n - Daily (Event takes place every day)\n - Weekly (Event takes place once a week)\n - Fortnightly (Event takes place every two weeks)\n - Monthly (Event takes place every month)\n - Quarterly (Event takes place every three months)\n - HalfYearly (Event takes place every six months or two times a year)\n - Yearly (Event takes place every year or once a year)"},"AgreementListResponse":{"type":"object","properties":{"totalCount":{"type":"integer","description":"Total number of agreements available","format":"int64","example":1},"agreements":{"type":"array","description":"List of agreements.","items":{"$ref":"#/components/schemas/AgreementDetailsResponse"}}},"description":"List of agreement details. \n"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}