Sign in

v1

latestOpenAPI 3.0.02026-07-24126202516.7 KB
PayTo Agreements

Validate PayTo Agreement

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.

post/agreements/validate

Request body

user_external_idstring required

Specifies a character string

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

priority'ATTENDED' | 'UNATTENDED' required
<p>Priority of the agreement creation/amendment authorisation notification to be sent to the user for approval.</p> <table><tr><td>Code</td><td>Description</td></tr><tr><td>ATTENDED</td><td>If the marketplace wants the debtor user to be notified about the agreement creation/amendment authorisation action immediately, the priority should be set as Attended.</td></tr><tr><td>UNATTENDED</td><td>If the marketplace wants the debtor user to be notified about the agreement creation/amendment authorisation at an appropriate time (not immediately), the priority should be set as Unattended.</td></tr></table>
response_requested_bystring yyyy-MM-dd'T'HH:mm:ss[.SSS][.SS][.S]'Z'

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

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

Example request

{
  "user_external_id": "buyer-147043828",
  "response_requested_by": "2022-11-04T06:24:34.214Z",
  "agreement_info": {
    "description": "agreement desc",
    "short_description": "short desc",
    "validity_start_date": "2022-04-05",
    "validity_end_date": "2022-04-25",
    "transfer_arrangement": "transfer arrangement",
    "debtor_info": {
      "debtor_account_details": {
        "account_id_type": "PAYID",
        "account_id": "033547123456789",
        "payid_details": {
          "payid": "payid"
        }
      },
      "debtor_details": {
        "debtor_name": "debtor name",
        "ultimate_debtor_name": "ultimate name",
        "debtor_id": "debtor identification",
        "debtor_reference": "debtor reference"
      }
    },
    "creditor_info": {
      "ultimate_creditor_name": "ultimate creditor name",
      "creditor_reference": "creditor reference"
    },
    "payment_initiator_info": {
      "initiator_id": "initiator identification",
      "initiator_legal_name": "initiator legal name",
      "initiator_name": "initiator name"
    },
    "payment_terms": {
      "payment_amount_info": {
        "amount": "1000",
        "currency": "AUD"
      },
      "first_payment_info": {
        "amount": "1500",
        "currency": "AUD",
        "date": "2022-04-15"
      },
      "last_payment_info": {
        "amount": "2000",
        "currency": "AUD",
        "date": "2022-04-15"
      },
      "maximum_amount_info": {
        "amount": "5000",
        "currency": "AUD"
      },
      "payment_executed_not_before_time": "02:30:19Z",
      "point_in_time": "24",
      "count_per_period": "10",
      "frequency": "ADHOC"
    }
  }
}

Response

Accepted

agreement_uuidstring

Agreement uuid.

statusstring

Status of the validate agreement request.

created_atstring

creation date.

updated_atstring

modification date.

Example response

{
  "agreement_uuid": "b2dd5934-478c-45ce-9528-b63c869e6f28",
  "status": "PENDING_VALIDATION",
  "created_at": "2022-03-21 16:25:00.190831",
  "updated_at": "2022-03-22 16:25:00.190831"
}