Initiate PayTo Payment

post

https://au-0000.api.assemblypay.com/payto/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

agreement_uuid

string

required

Body Params

priority

string

enum

required

Indicates payment processing priority. Supported values

Code	Description
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

Allowed:

payment_info

object

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.

retry_info

object

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.

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.

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-2501	Payments can be initiated for ACTIVE agreements only.
PAYT-ERR-2502	Payments can be initiated only within the agreement validity period.
PAYT-ERR-2510	unique_superannuation_code is mandatory along with unique_superannuation_identification.
PAYT-ERR-2512	Payment requested for this agreement has been cleared and settled already. Please check the latest status before requesting again.
PAYT-ERR-2513	Request rejected: Exceeded the maximum retry attempts allowed for the agreement.
PAYT-ERR-2514	Request rejected: Please ensure the payment is retried within valid period.
PAYT-ERR-2528	Request rejected: Please initiate the payment on the agreed date and time as per frequency and other payment terms specified in the agreement.
PAYT-ERR-2529	Request rejected: Please initiate first payment on the agreed date as per frequency and other payment terms specified in the agreement.
PAYT-ERR-2530	Request rejected: Please initiate last payment on the agreed date as per frequency and other payment terms specified in the agreement.

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-1002	Request rejected: User associated with the agreement is not active.

Error Code	Error Message
PAYT-ERR-2500	Agreement with provided uuid does not exist.
PAYT-ERR-2511	Payment request with provided uuid does not exist.

Error Code	Error Message
PAYT-ERR-2516	A payment is already in progress for the agreement. Please try again if the current payment request is unsuccessful.
PAYT-ERR-2517	Invalid request: Payment has been rejected already and cannot be retried. Please check reason code details.
PAYT-ERR-2518	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.
PAYT-ERR-2519	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.
PAYT-ERR-2520	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.
PAYT-ERR-2521	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.
PAYT-ERR-2522	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.
PAYT-ERR-2523	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.
PAYT-ERR-2524	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.
PAYT-ERR-2525	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.
PAYT-ERR-2526	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.
PAYT-ERR-2527	Request rejected: Exceeds the count of allowed payment initiations as per frequency. Please initiate payments as per the agreement’s payment terms.

202Accepted

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

403Forbidden Error CodeError MessagePAYT-ERR-1001PayTo feature not available.PAYT-ERR-1002Request rejected: User associated with the agreement is not active.

404Not Found Error CodeError MessagePAYT-ERR-2500Agreement with provided uuid does not exist.PAYT-ERR-2511Payment request with provided uuid does not exist.

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