Validate PayTo Agreement

post

https://au-0000.api.assemblypay.com/payto/agreements/validate

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

This operation validates the details of the agreements along with ensuring the debtor and creditor are NPP and PayTo reachable before the actual agreement creation with NPPA.

PayID details provided for the debtor are also resolved as part of this operation. Customers should share the resolved PayID details with their users for confirmation before the actual agreement creation.

Post successful validation, agreement UUID is returned in the response which uniquely identifies the agreement. This UUID should be used in subsequent API calls for that particular agreement.

Note - Zai may reformat the debtor account number if it is not as per the format expected by payer institutions. Reformatted debtor account number can be accessed either via GET PayTo Agreement Details API after the validation step or via WAPI notification sent by Zai after successful agreement creation step.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

user_external_id

string

required

length between 1 and 254

Specifies a character string

Unique id of the user (created via Create User API) with whom the agreement should be associated with.

priority

string

enum

required

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

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

Allowed:

response_requested_by

string

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

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

agreement_info

object

required

Details (creditor, debtor, payment terms) which should be agreed between debtor and creditor.

Property descriptions:

description - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field.
short_description - Describes what the agreement is being established for. Examples include a product, particular service offering, etc. If the description is less than 35 characters, then the Short Description should be used instead of the Description field.
purpose_code - Most appropriate code that represents the purpose for which this agreement is being established.

Supported values:
- MORT - Mortgage payments, including payments for a home/business loan
- UTIL - Utility payments such as gas, electricity, water etc
- LOAN - Loan payments, other than mortgage payments
- DEPD - Dependant support payments (e.g. child support)
- RETL - Retail payments, including e-commerce and online shopping (payments are for provision of goods or services)
- SALA - Salary payments
- PERS - Personal payments (payments to an individual which excludes any payments for salary and superannuation purposes)
- GOVT - Government payments
- PENS - Pension payments (superannuation payments)
- TAXS - Tax payments (tax payments to Australian Taxation Office (ATO) and Australian Commonwealth, State, Territory, or other local government body)
- OTHR - Other service related payments (when there is no other appropriate purpose code)
agreement_type - Agreement type to be created.

Supported values:
- AUPM (Authorised Payment Mandate) - This type of agreement must be authorised by the payer/debtor i.e. agreement will be Active only post debtor/payer authorisation. Payment requests can be initiated immediately once the agreement is "Active".
- MGCR (Migrated by Creditor/Migrated DDR) - This type of agreement is created in order to migrate existing Direct Debit arrangement to be processed via the NPP using the PayTo rails. The agreement will be Active immediately (does not need debtor/payer authorisation as it was already pre-authorised in the existing BECS systems) post migration however payment requests can be initiated after 5 calendar days of creating the agreement.
automatic_renewal - Automatic renewal of an agreement at the end of the defined period. An example of an automatically renewing agreement might be a gym membership that automatically rolls over, or a phone contract.
validity_start_date - Validity start date of the agreement. The agreement is valid as of 00:00:00.000 Australia Sydney time on this date.
validity_end_date - Validity end date of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date.
transfer_arrangement - Additional details about the agreement terms with consideration to the transfer of items/goods/services. Examples might include payment of shares,transfer of property, or fulfilment of a purchase order.
debtor_info - Debtor and Debtor Account Details.
creditor_info - Creditor Details.
payment_initiator_info - Initiating party details.
payment_terms - Set of characteristics detailing agreement payment information.

The following rules apply to this structure:

DescriptionAndShortDescriptionRule: Either 'description' or 'short_description' must be present.
AgreementTypeRule: If 'agreement_type' is equal to 'MGCR' then payid details must be absent.
ValidityStartDateRule: validity_start_date should be either current date OR future date.
ValidityStartAndEndDateRule: validity_end_date should be either current date OR future date.
AutomaticExtensionRule: validity_end_date must be present only if 'automatic_renewal' is false.

Responses

Error Code	Error Message
PAYT-ERR-1050	Mandatory info missing: [FieldName] cannot be null or empty.
PAYT-ERR-1051	Invalid Data: [FieldName] provided is invalid.
PAYT-ERR-1052	Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].
PAYT-ERR-1053	Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].
PAYT-ERR-1054	Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].
PAYT-ERR-1057	Unrecognized Field: [FieldName] is not a valid field.
PAYT-ERR-1058	Invalid Request: request provided is not well-formatted.
PAYT-ERR-2001	Either description or short_description should be provided.
PAYT-ERR-2002	Response_Requested_By date must be a future date and less than 5 days.
PAYT-ERR-2004	PayID details are not supported for migrated agreements.
PAYT-ERR-2005	validity_start_date should be either current date OR future date.
PAYT-ERR-2006	validity_end_date should be greater than OR same as validity_start_date.
PAYT-ERR-2008	validity_end_date should not be provided if agreement should be auto-renewed.
PAYT-ERR-2009	account_details in the request are invalid as per the account_type provided.
PAYT-ERR-2010	Either account (bsb/account number) or PayID details should be provided.
PAYT-ERR-2011	Invalid PayID format for the PayID type provided.
PAYT-ERR-2013	debtor_id_type is mandatory along with debtor_id.
PAYT-ERR-2014	Invalid debtor_id_type for the debtor_type provided.
PAYT-ERR-2015	Date provided in first_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2016	Date provided in last_payment_info should be between validity_start_date and validity_end_date OR can be same as validity_start_date and validity_end_date.
PAYT-ERR-2018	payment_amount should be less than or equal to maximum amount.
PAYT-ERR-2019	Amount provided in last_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2020	Amount provided in first_payment_info should be less than or equal to maximum amount.
PAYT-ERR-2021	Date provided in last_payment_info should be same OR after the date provided in first_payment_info.
PAYT-ERR-2025	Incorrect value provided for either of these fields - frequency, point_in_time, count_per_period. The combination provided should be valid.
PAYT-ERR-2027	Active direct debit agreement which needs to be migrated does not exist for the user.
PAYT-ERR-2028	Response_Requested_By is applicable only for AUPM agreements with 'ATTENDED' priority type.
PAYT-ERR-2029	For FIXE/BALN type of agreements, specifying payment amount is mandatory.
PAYT-ERR-2031	Invalid Data: Please provide info for all parameters under agreement_info.payment_terms.maximum_amount_info
PAYT-ERR-2032	Invalid Data: Payment frequency [frequency] is not enabled for your platform. If you require this payment frequency to be enabled for your business use-case, kindly get in touch with Zai support.
PAYT-ERR-2033	Invalid Data: Payment parameter '[payment_parameter]' provided is not enabled for your platform. If you require this parameter to be enabled for your business use-case, kindly get in touch with Zai support.
PAYT-ERR-2034	Invalid Data: Agreement type [type] is not enabled for your platform. If you require this agreement type to be enabled for your business use-case, kindly get in touch with Zai support.
PAYT-ERR-2035	Invalid Data: Payment amount type [amount_type] is not enabled for your platform. If you require this payment amount type to be enabled for your business use-case, kindly get in touch with Zai support.

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

Error Code	Error Message
PAYT-ERR-1001	PayTo feature not available.
PAYT-ERR-1004	User with provided user_external_id does not exist.

Error Code	Error Message
PAYT-ERR-2000	Active user with provided user_external_id does not exist.

Error Code	Error Message
PAYT-ERR-1003	An error occurred processing your request. Please try again.

202Accepted

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

403Forbidden Error CodeError MessagePAYT-ERR-1001PayTo feature not available.PAYT-ERR-1004User with provided user_external_id does not exist.

404Not Found Error CodeError MessagePAYT-ERR-2000Active user with provided user_external_id does not exist.

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