---
title: "Initiate PayTo Payment"
method: POST
path: "/agreements/{agreement_uuid}/payment_requests/initiate"
tags: ["PayTo Payments"]
---

# Initiate PayTo Payment

`POST /agreements/{agreement_uuid}/payment_requests/initiate`

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

 Payment initiation request statuses -
- PENDING_PAYMENT_INITIATION - when the payment initiation request has been accepted for processing 
- PAYMENT_INITIATED - when the payment initiation request is being processed 
- PAYMENT_INITIATION_COMPLETED - when the payment initiation request is cleared and settled successfully. Funds can be expected in the user's wallet soon 
- 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 
business reason. A retry can be performed in such scenarios 

If the payment collection request has been rejected due to valid business reasons (example - insufficient funds), a retry can be attempted 5 times within 24 hours for the same request.

Payment_request_uuid generated will be the same for the payment collection request and all subsequent retry attempts, however, instruction_id differs for each.

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

## Path parameters

- `agreement_uuid` string, required

## Request body

- InitiatePaymentRequest — Definition of the Initiate Payment request data. **Property descriptions**: - **priority** - Indicates payment processing priority. Supported values: - Attended: Payment marked as attended will be processed immediately and will be rejected if the responding participant is not available - 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 - **payment_info** - Payment info for payment request. - **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.<br><br>*Note - Rejected and retry eligible payment request can be retried 5 times within 24 hours.*
  - `priority` 'ATTENDED' | 'UNATTENDED', required — <p>Indicates payment processing priority. Supported values</p> <table><tr><td>Code</td><td>Description</td></tr><tr><td>ATTENDED</td><td>Payment marked as attended will be processed immediately and will be rejected if the responding participant is not available</td></tr><tr><td>UNATTENDED</td><td>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</td></tr></table>
  - `payment_info` PaymentInformation, required — Payment request details. **Property descriptions**: - **instructed_amount** - Specifies the amount to be debited the from debtor's bank account before deduction of charges. - **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. - **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. - **remittance_info** - Free text field to provide any narrative for the payment. - **unique_superannuation_code** - For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI number for the superannuation fund. - **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. **The following rules apply to this structure**: - **UniqueSuperannuationRule** Both unique_superannuation_code and unique_superannuation_id must be present or both fields must be absent.
    - `instructed_amount` string, required — Specifies an amount in cents. Specifies the amount to be debited the from debtor's bank account before deduction of charges.
    - `last_payment` boolean, required — Indicates a "Yes" or "No" type of answer for an element. 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.
    - `end_to_end_id` string — Specifies a character string with a maximum length of 35 characters. 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.
    - `remittance_info` string — Specifies a character string with a maximum length of 280 characters. Free text field to provide any narrative for the payment.
    - `unique_superannuation_id` string — Specifies a character string with a maximum length of 35 ASCII printable characters. For agreements created with PURPOSE_CODE = PENS (pension payments), this should be the USI number for the superannuation fund.
    - `unique_superannuation_code` string — Specifies a character string with a maximum length of 35 ASCII printable characters. 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.
  - `retry_info` RetryInformation — 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.<br><br>*Note - Rejected and retry eligible payment request can be retried 5 times within 24 hours.* **Property descriptions**: - **payment_request_uuid** - Unique identifier for the payment request (in UUID format) for which the retry is being attempted.
    - `payment_request_uuid` string — Unique identifier for the payment request (in UUID format) for which the retry is being attempted.

## Response `202`

Accepted

- InitiatePaymentResponse
  - `payment_request_uuid` string — Unique identifier for the payment request in UUID format.
  - `agreement_uuid` string — Unique agreement identifier.
  - `instruction_id` string — Unique identifier for the payment request generated as per NPPA guidelines.
  - `status` 'PENDING_PAYMENT_INITIATION' | 'PAYMENT_INITIATION_REJECTED' — Payment initiation request statuses:<table><tr><td>Code</td><td>Description</td></tr><tr><td>PENDING_PAYMENT_INITIATION</td><td>Payment request is pending for initiation.</td></tr><tr><td>PAYMENT_INITIATION_REJECTED</td><td>Payment request is rejected.</td></tr></table>
  - `created_at` string — Payment request creation date in UTC format.
  - `updated_at` string — Payment request modification date in UTC format.
  - `agreement_id` string — Unique agreement identifier generated by NPPA.

## Other responses

- `400` — Bad Request <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1050</td><td>Mandatory info missing: [FieldName] cannot be null or empty.</td></tr><tr><td>PAYT-ERR-1051</td><td>Invalid Data: [FieldName] provided is invalid.</td></tr><tr><td>PAYT-ERR-1052</td><td>Invalid Data: [FieldName] provided should contain any of the values [Acceptable values].</td></tr><tr><td>PAYT-ERR-1053</td><td>Invalid Data: [FieldName] provided is invalid. Expected format [DateFormat].</td></tr><tr><td>PAYT-ERR-1054</td><td>Invalid Data: [FieldName] length is invalid. Expected minimum [MinLength] and maximum [MaxLength].</td></tr><tr><td>PAYT-ERR-1057</td><td>Unrecognized Field: [FieldName] is not a valid field.</td></tr><tr><td>PAYT-ERR-1058</td><td>Invalid Request: request provided is not well-formatted.</td></tr><tr><td>PAYT-ERR-2501</td><td>Payments can be initiated for ACTIVE agreements only.</td></tr><tr><td>PAYT-ERR-2502</td><td>Payments can be initiated only within the agreement validity period.</td></tr><tr><td>PAYT-ERR-2510</td><td>unique_superannuation_code is mandatory along with unique_superannuation_identification.</td></tr><tr><td>PAYT-ERR-2512</td><td>Payment requested for this agreement has been cleared and settled already. Please check the latest status before requesting again.</td></tr><tr><td>PAYT-ERR-2513</td><td>Request rejected: Exceeded the maximum retry attempts allowed for the agreement.</td></tr><tr><td>PAYT-ERR-2514</td><td>Request rejected: Please ensure the payment is retried within valid period.</td></tr><tr><td>PAYT-ERR-2528</td><td>Request rejected: Please initiate the payment on the agreed date and time as per frequency and other payment terms specified in the agreement.</td></tr><tr><td>PAYT-ERR-2529</td><td>Request rejected: Please initiate first payment on the agreed date as per frequency and other payment terms specified in the agreement.</td></tr><tr><td>PAYT-ERR-2530</td><td>Request rejected: Please initiate last payment on the agreed date as per frequency and other payment terms specified in the agreement.</td></tr></table>
- `401` — Unauthorised <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1000</td><td>Invalid or missing authorisation token.</td></tr></table>
- `403` — Forbidden <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1001</td><td>PayTo feature not available.</td></tr><tr><td>PAYT-ERR-1002</td><td>Request rejected: User associated with the agreement is not active.</td></tr></table>
- `404` — Not Found <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2500</td><td>Agreement with provided uuid does not exist.</td></tr><tr><td>PAYT-ERR-2511</td><td>Payment request with provided uuid does not exist.</td></tr></table>
- `409` — Conflict <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-2516</td><td>A payment is already in progress for the agreement. Please try again if the current payment request is unsuccessful.</td></tr><tr><td>PAYT-ERR-2517</td><td>Invalid request: Payment has been rejected already and cannot be retried. Please check reason code details.</td></tr><tr><td>PAYT-ERR-2518</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2519</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2520</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2521</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2522</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2523</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2524</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2525</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2526</td><td>For 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.</td></tr><tr><td>PAYT-ERR-2527</td><td>Request rejected: Exceeds the count of allowed payment initiations as per frequency. Please initiate payments as per the agreement’s payment terms.</td></tr></table>
- `500` — Internal Server Error <table><tr><td><b>Error Code</b></td><td><b>Error Message</b></td></tr><tr><td>PAYT-ERR-1003</td><td>An error occurred processing your request. Please try again.</td></tr></table>

---

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