PayTo Agreements API
Use this resource to create, amend and retrieve a PayTo Agreements.
Create
Use this resource to create a new PayTo Agreement for an existing Customer. The PayTo Agreement is sent to the Payer for approval in their banking app.
Request
POST /customers/{customerId}/payto-agreements
Use your Secret API key to access this resource.
An example request with minimal data.
{
"supplierBusinessCode": "MYBUSINESS",
"paymentDetails": {
"purpose": "UTIL",
"description": "Your monthly utility payments",
"startDate": "2024-01-01",
"automaticRenewal": true
},
"paymentTerms": {
"frequency": "MNTH",
"agreementType": "FIXE",
"paymentAmount": "100.05",
"currency": "AUD"
},
"payerDetails": {
"payerType": "PERS",
"payerId": "PS19400650001",
"payerName": "FIRSTNAME SURNAME",
"payerReference": "PY19000890013",
"payIdType": "EMAL",
"payId": "FIRSTNAME.SURNAME@MYCUSTOMER.COM.AU"
}
}
Path parameters
None.
Request body
Field | Format | Description |
---|---|---|
respondByTimeMinutes |
long |
Optional. The number of minutes from the created date of the PayTo Agreement that the Payer has to respond. Cannot be longer than 5 calendar days from now (7200 minutes). Defaults to 7200 . QuickStream automatically recalls PayTo Agreements if the Payer has not responded within this time. |
payeeReference |
string |
Your reference for this PayTo Agreement. Up to 35 characters. Required when agreementCreationType=MIGRATED_DDR , and this field must be the lodgement reference for an existing Direct Debit Arrangement that you have with this customer. Otherwise, this field is optional. |
supplierBusinessCode |
string |
The code that uniquely identifies your business and that references your Payee account details. |
agreementCreationType |
string |
Optional. One of:
AUTHORISED when blank or not provided. |
paymentDetails |
Payment Details Request Model | Details about the type of PayTo payments for this PayTo Agreement. |
paymentTerms |
Payment Terms Request Model | Details about the terms and frequency of payments for this PayTo Agreement. |
payerDetails |
Payer Details Request Model | Details about the Payer of this PayTo Agreement. |
Payment Details Request Model
Field | Format | Description |
---|---|---|
purpose |
string |
The purpose of the PayTo Agreement. One of:
|
description |
string |
Describes what the PayTo Agreement is being established for. Up to 140 characters. |
startDate |
date |
The starting date from which Payments may be initiated against the PayTo Agreement. |
endDate |
date |
Required when automaticRenewal=false . The last date from which Payments may be initiated against the PayTo Agreement. |
automaticRenewal |
boolean |
Set to true when the PayTo Agreement has no endDate . Otherwise set to false . |
additionalInformation |
string |
When agreementCreationType=AUTHORISED (or is not provided,) then this is an optional free-text field in which other information relevant to the PayTo Agreement is provided. Up to 140 characters. When agreementCreationType=MIGRATED_DDR , then this field is required, and it must contain the 6-digit APCA Number associated with an existing Direct Debit Arrangement that you have with this customer. |
Payment Terms Request Model
Field | Format | Description |
---|---|---|
frequency |
string |
The frequency with which payments can be initiated for this PayTo Agreement. One of:
|
numberOfPaymentsPermitted |
long |
Required when frequency=ADHO . The number of payments permitted per frequency. Up to 18 digits. |
pointInTime |
long |
Optional. Qualifies the frequency in terms of an exact point in time or moment within the specified period. Up to 2 digits.
|
agreementType |
string |
The type of PayTo Agreement. One of:
|
firstPaymentAmount |
money |
Optional. An amount different from the payment amount, as it includes the costs associated with the first debited amount. |
lastPaymentAmount |
money |
Required when agreementType=BALN . The last payment amount different to the payment amount. |
paymentAmount |
money |
The fixed amount to be debited when agreementType=FIXE , or the minimum payment amount for other agreementType values. |
maximumPaymentAmount |
money |
Optional. The maximum amount that may be paid per payment. |
currency |
string |
AUD . |
firstPaymentDue |
date |
Optional. The date of the first payment. |
lastPaymentDue |
date |
Optional. The date of the last payment. |
Payer Details Request Model
Field | Format | Description |
---|---|---|
payerType |
string |
The type of Payer. One of:
|
payerId |
string |
Your unique customer identifier for this Payer. |
payerName |
string |
The Payer's name. |
ultimatePayerName |
string |
Optional. The trading name of an organisation or the name of the receiver of goods or services. If not relevant, make this the same as payerName . If not provided, defaults to payerName . |
payerReference |
string |
Optional. Your reference for this Payer. |
bsb |
string |
Required when accountNumber is provided. The 6 digit BSB for the Payer's payment account. |
accountNumber |
string |
Required when bsb is provided. The 6 to 9 digit Account Number for the Payer's payment account. |
payIdType |
string |
Required when payId is provided. One of:
|
payId |
string |
Required when payIdType is provided. The PayID for the Payer's payment account. |
Response
If successful, this method returns the registered PayTo Agreement Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the newly PayTo Agreement Model is returned in the response body. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. This may also occur when the number of attempts to create a PayTo Agreement for invalid PayID's exceeds a daily limit. Refer to errors in the response body for more. View more |
Get
Get the details of a PayTo Agreement.
Request
GET /payto-agreements/{agreementToken}
Use your Secret API key to access this resource.
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
None.
Response
If successful, this method returns the registered PayTo Agreement Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
List
List PayTo Agreements with query parameters.
Request
GET /customers/{customerId}/payto-agreements
Use your Secret API key to access this resource.
Query parameters
Parameter Name | Format | Description |
---|---|---|
supplierBusinessCode |
string |
Optional. The code that uniquely identifies your Business. |
status |
string |
Optional. The status of the PayTo Agreement. See PayTo Agreement Status. |
Request body
None.
Response
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of PayTo Agreement Model | A list of PayTo Agreements. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
Recall
Use this resource to recall a PayTo Agreement in a PENDING
status.
Request
PATCH /payto-agreements/{agreementToken}
Use your Secret API key to access this resource.
An example request.
{
"updateType": "RECALL_PAYTO_AGREEMENT",
"recallPayToAgreement": {
"statusCode": "CANCELLED"
}
}
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
Field | Format | Description |
---|---|---|
updateType |
string |
The type of update to perform. Set to RECALL_PAYTO_AGREEMENT . |
recallPayToAgreement |
Recall PayTo Agreement Request Model | Required when updateType=RECALL_PAYTO_AGREEMENT . |
Recall PayTo Agreement Request Model
Field | Format | Description |
---|---|---|
statusCode |
string |
Set to CANCELLED . |
Response
If successful, this method returns an HTTP 204.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
204 |
NO CONTENT | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data or the PayTo Agreement status is not PENDING . Refer to errors in the response body for more. View more |
Status Amendment
Use this resource to change the status of a PayTo Agreement. The PayTo Agreement status must be ACTIVE
or SUSPENDED
.
Request
PATCH /payto-agreements/{agreementToken}
Use your Secret API key to access this resource.
An example request.
{
"updateType": "STATUS_AMENDMENT",
"statusAmendment": {
"statusCode": "CANCELLED",
"reasonCode": "AC04",
"reasonDescription": "Services closed"
}
}
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
Field | Format | Description |
---|---|---|
updateType |
string |
The type of update to perform. Set to STATUS_AMENDMENT . |
statusAmendment |
Status Amendment Model | Required when updateType=STATUS_AMENDMENT . |
Status Amendment Request Model
Field | Format | Description |
---|---|---|
statusCode |
string |
One of:
|
reasonCode |
string |
Required when statusCode=SUSPENDED or statusCode=CANCELLED . The reason for changing the status. See Status Amendment Reason Codes. |
reasonDescription |
string |
Optional. A description to support the reason code. Up to 256 characters. |
Status Amendment Reason Codes
Reason Code | Description | Usage |
---|---|---|
AC04 |
Closed Payer Account Number | When changing the status to CANCELLED or SUSPENDED . |
MD17 |
Requested By Initiating Party | Any status change. |
MD20 |
PayTo Agreement Expired | When changing the status to CANCELLED or SUSPENDED . |
CTAM |
Contract Amended | Any status change. |
CTCA |
Contract Cancellation Initiated By Payer | When changing the status to CANCELLED or SUSPENDED . |
CTEX |
Contract Expired | When changing the status to CANCELLED or SUSPENDED . |
MCFC |
PayTo Agreement Suspended Final Collection | When changing the status to SUSPENDED . |
MCOC |
PayTo Agreement Suspended Once Off Collection | When changing the status to SUSPENDED . |
MSUC |
PayTo Agreement Suspended 7 Consecutive Unsuccessful Collections | When changing the status to SUSPENDED . |
NOAS |
No Answer From Customer | Any status change. |
Response
If successful, this method returns an HTTP 204.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
204 |
NO CONTENT | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data or the PayTo Agreement status is not ACTIVE or SUSPENDED . Refer to errors in the response body for more. View more |
Unilateral Amendment
Use this resource to amend the details of a PayTo Agreement that does not require Payer approval. The PayTo Agreement status must be ACTIVE
or SUSPENDED
.
Each field in the Unilateral Amendment Request Model object will replace the fields on the current PayTo Agreement. If you do not provide a field, and it is optional, it will be removed from the PayTo Agreement.
Request
PATCH /payto-agreements/{agreementToken}
An example request.
{
"updateType": "UNILATERAL_AMENDMENT",
"unilateralAmendment": {
"description": "Your utility agreement.",
"payeeReference": "PS900015007",
"supplierBusinessCode": "MYBUSINESS"
}
}
Use your Secret API key to access this resource.
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
Field | Format | Description |
---|---|---|
updateType |
string |
The type of update to perform. Set to UNILATERAL_AMENDMENT . |
unilateralAmendment |
Unilateral Amendment Request Model | Required when updateType=UNILATERAL_AMENDMENT . |
Unilateral Amendment Request Model
Field | Format | Description |
---|---|---|
description |
string |
Reason for the PayTo Agreement setup as narrative text. Up to 140 characters. |
payeeReference |
string |
A reference that is relevant to you. Up to 35 characters. |
supplierBusinessCode |
string |
The code that uniquely identifies your business and that references your Payee account details. Must exactly match the supplierBusinessCode used for the PayTo Agreement. |
Response
If successful, this method returns an HTTP 204.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
204 |
NO CONTENT | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data or the PayTo Agreement status is not ACTIVE or SUSPENDED . Refer to errors in the response body for more. View more |
Bilateral Amendment
Use this resource to amend the details of a PayTo Agreement which require Payer approval. The PayTo Agreement status must be ACTIVE
or SUSPENDED
.
Each field in the Bilateral Amendment Request Model object will replace the fields on the current PayTo Agreement. If you do not provide a field, and it is optional, it will be removed from the PayTo Agreement.
Request
PATCH /payto-agreements/{agreementToken}
Use your Secret API key to access this resource.
An example request.
{
"updateType": "BILATERAL_AMENDMENT",
"bilateralAmendment": {
"respondByTimeMinutes": "7200",
"paymentDetails": {
"endDate": "2024-12-01",
"automaticRenewal": false,
"additionalInformation": null
},
"paymentTerms": {
"frequency": "MNTH",
"numberOfPaymentsPermitted": null,
"agreementType": "FIXE",
"firstPaymentAmount": null,
"lastPaymentAmount": null,
"paymentAmount": "100.05",
"maximumPaymentAmount": null,
"currency": "AUD",
"firstPaymentDue": null,
"lastPaymentDue": null
}
}
}
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
Field | Format | Description |
---|---|---|
updateType |
string |
The type of update to perform. Set to BILATERAL_AMENDMENT . |
bilateralAmendment |
Bilateral Amendment Request Model | Required when updateType=BILATERAL_AMENDMENT . |
Bilateral Amendment Request Model
Field | Format | Description |
---|---|---|
respondByTimeMinutes |
long |
Optional. The number of minutes from the created date of the Bilateral Amendment that the Payer has to respond. Cannot be longer than 5 calendar days from now (7200 minutes). Defaults to 7200 . QuickStream automatically recalls Bilateral Amendments that have past this time. |
paymentDetails |
Bilateral Amendment Payment Details Request Model | The details about the type of payments for this PayTo Agreement. |
paymentTerms |
Bilateral Amendment Payment Terms Request Model | The details about the type of payments for this PayTo Agreement. |
Bilateral Amendment Payment Details Request Model
Field | Format | Description |
---|---|---|
endDate |
date |
Required when automaticRenewal=false . The last date from which Payments may be initiated against the PayTo Agreement. |
automaticRenewal |
boolean |
Set to true when the PayTo Agreement has no endDate and is automatically renewed. Otherwise set to false . |
additionalInformation |
string |
Optional. A free-text field in which other information relevant to the PayTo Agreement is provided. Up to 140 characters. |
Bilateral Amendment Payment Terms Request Model
Field | Format | Description |
---|---|---|
frequency |
string |
The frequency with which payments can be initiated for this PayTo Agreement. One of:
|
numberOfPaymentsPermitted |
long |
Required when frequency=ADHO . The number of payments permitted per frequency. Up to 18 digits. |
pointInTime |
long |
Optional. Qualifies the frequency in terms of an exact point in time or moment within the specified period. Up to 2 digits. |
agreementType |
string |
The type of PayTo Agreement. One of:
|
firstPaymentAmount |
money |
Optional. An amount different from the payment amount, as it includes the costs associated with the first debited amount. |
lastPaymentAmount |
money |
Required when agreementType=BALN . The last payment amount different to the payment amount. |
paymentAmount |
money |
The fixed amount to be debited. |
maximumPaymentAmount |
money |
Optional. The maximum amount that may be paid per payment. |
currency |
string |
AUD . |
firstPaymentDue |
date |
Optional. The date of the first payment. |
lastPaymentDue |
date |
Optional. The date of the last payment. |
Response
If successful, this method returns an HTTP 204.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
204 |
NO CONTENT | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data or the PayTo Agreement status is not ACTIVE or SUSPENDED . Refer to errors in the response body for more. View more |
Recall Amendment
Use this resource to recall a Pending Bilateral Amendment for a PayTo Agreement.
Request
PATCH /payto-agreements/{agreementToken}
Use your Secret API key to access this resource.
An example request.
{
"updateType": "RECALL_BILATERAL_AMENDMENT"
}
Path parameters
Parameter Name | Format | Description |
---|---|---|
agreementToken |
string |
The unique identifier for a PayTo Agreement. |
Request body
Field | Format | Description |
---|---|---|
updateType |
string |
The type of update to perform. Set to RECALL_BILATERAL_AMENDMENT . |
Response
If successful, this method returns an HTTP 204.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
204 |
NO CONTENT | The request has succeeded. |
404 |
NOT FOUND | The agreementToken path parameter may be incorrect. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data, the Bilateral Amendment is no longer pending, or the PayTo Agreement status is not ACTIVE or SUSPENDED . Refer to errors in the response body for more. View more |
PayTo Agreement Model
An example response.
{
"agreementToken": "MYCOM97445488",
"status": "ACTIVE",
"respondByTime": "2023-12-01T16:45:00Z",
"payeeReference": "PS19400650001",
"hasPendingBilateralAmendment": false,
"paymentDetails": {
"purpose": "UTIL",
"description": "Your monthly utility payments",
"startDate": "2024-01-01",
"endDate": null,
"automaticRenewal": true,
"additionalInformation": null
},
"paymentTerms": {
"frequency": "MNTH",
"numberOfPaymentsPermitted": null,
"pointInTime": null,
"agreementType": "FIXE",
"firstPaymentAmount": null,
"lastPaymentAmount": null,
"paymentAmount": {
"currency": "AUD",
"amount": 100.05,
"displayAmount": "$100.05"
},
"maximumPaymentAmount": null,
"firstPaymentDue": null,
"lastPaymentDue": null
},
"payerDetails": {
"customerId": "87556623117",
"payerType": "PERS",
"payerId": "PS19400650001",
"payerName": "AMIRA FONTIUS",
"ultimatePayerName": "AMIRA FONTIUS",
"paymentReference": "PY19000890013",
"payIdType": "EMAL",
"maskedPayId": "A****@C****.COM.AU"
},
"payeeDetails": {
"supplierBusinessCode": "MYBUSINESS",
"payeeName": "MY COMPANY PTY LTD",
"ultimatePayeeName": "MY COMPANY PTY LTD",
"payeeAbn": "12345678901",
"maskedAccountNumber": "***-002 ******465",
"initiatorName": "MY COMPANY PTY LTD",
"initiatorLegalName": "MY COMPANY PTY LTD",
"initiatorAbn": "12345678901"
}
}
Field | Format | Description |
---|---|---|
agreementToken |
string | A unique identifier for the PayTo Agreement which can be used for Payments. |
status |
string | The status of the PayTo Agreement. See PayTo Agreement Status. |
respondByTime |
date | The date and time a Payer should approve or decline the PayTo Agreement. |
payeeReference |
string | Your reference for this PayTo Agreement. |
hasPendingBilateralAmendment |
boolean | Returns true when there is a Pending Bilateral Amendment, otherwise false . |
rejectionReason |
string | A message with a rejection reason. This message is populated when the status is REJECTED . |
paymentDetails |
Payment Details Model | Details about the type of payments for this PayTo Agreement. |
paymentTerms |
Payment Terms Model | Details about the frequency and terms of payments for this PayTo Agreement. |
payerDetails |
Payer Details Model | Details about the Payer of this PayTo Agreement. |
payeeDetails |
Payee Details Model | Details about the Payee of this PayTo Agreement. |
Payment Details Model
Field | Format | Description |
---|---|---|
purpose |
string | The reason for the PayTo Agreement. |
description |
string | Describes what the PayTo Agreement was established for. |
startDate |
date | The starting date from which Payments may be initiated against the PayTo Agreement. |
endDate |
date | The last date from which Payments may be initiated against the PayTo Agreement. |
automaticRenewal |
boolean | true when there is no endDate and the PayTo Agreement is automatically renewed. |
additionalInformation |
string | A free-text field in which other information relevant to the PayTo Agreement is provided. |
Payment Terms Model
Field | Format | Description |
---|---|---|
frequency |
string | The frequency with which payments can be initiated for this PayTo Agreement. |
numberOfPaymentsPermitted |
string | Qualifies the frequency in terms of the number of instructions to be created and processed during the specified period. |
pointInTime |
string | Qualifies the frequency in terms of an exact point in time or moment within the specified period. |
agreementType |
string | The type of agreement. |
firstPaymentAmount |
money | An amount different from the payment amount, as it includes the costs associated with the first debited amount. |
lastPaymentAmount |
money | The last payment amount different to the payment amount. |
paymentAmount |
money | The fixed amount to be debited. |
maximumPaymentAmount |
money | The maximum amount that may be paid, per payment. |
firstPaymentDue |
date | The date of the first payment is predefined in the PayTo Agreement. |
lastPaymentDue |
date | The date of the last payment is predefined in the PayTo Agreement. |
Payer Details Model
Field | Format | Description |
---|---|---|
customerId |
string | QuickStream's unique identifier for the customer. This customer is created automatically when using the Create endpoint or from your server when using Create Customer and then Create for Customer. See Customers API for more. |
payerType |
string | The type of Payer. |
payerId |
string | Your unique customer identifier for this Payer. |
payerName |
string | The name of the Payer. |
ultimatePayerName |
string | The trading name of an organisation or the name of the receiver of goods or services. |
payerReference |
string | Your reference for this Payer. |
maskedAccountNumber |
string | The masked BSB and Account number for the Payer's payment account. |
payIdType |
string | The PayID type. |
maskedPayId |
string | The masked PayID for the Payer's payment account. |
Payee Details Model
Field | Format | Description |
---|---|---|
supplierBusinessCode |
string | The code that uniquely identifies your Business. |
payeeName |
string | The Payee name. |
ultimatePayeeName |
string | The ultimate Payee name. |
payeeAbn |
string | The Payee ABN. |
maskedAccountNumber |
string | The masked BSB and Account Number of the Payee settlement account. |
initiatorName |
string | The Initiator's name. |
initiatorLegalName |
string | The Initiator's legal name. |
initiatorAbn |
string | The Initiator's ABN. |
PayTo Agreement Status
Status | Description |
---|---|
CREATED |
Created. |
REJECTED |
Rejected while being sent to the Payer for approval. |
PENDING |
Sent to the Payer for approval. |
ACTIVE |
Approved by the Payer. |
CANCELLED |
Cancelled by you, declined by the Payer, or the Payer did not respond. Payments cannot be taken. Amendments cannot be made. |
SUSPENDED |
Suspended. Payments cannot be taken. Amendments can be made. |