Skip to main content

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 that have past this time.
payeeReference string Optional. Your reference for this PayTo Agreement. Up to 35 characters.
supplierBusinessCode string The code that uniquely identifies your business and that references your Payee account details.
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:
  • MORT - Mortgage Payments
  • UTIL - Utility Payments
  • LOAN - Loan Payments (other than Mortgate Payments)
  • DEPD - Dependent Support Payments
  • GAMP - Gambling Payments
  • RETL - Retail Payments (incl. eCommerce)
  • SALA - Salary Payments
  • PERS - Personal Payments
  • GOVT - Government Payments
  • PENS - Pension Payments
  • TAXS - Tax Payments
  • OTHR - Other Service-related Payments
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 Optional. A free-text field in which other information relevant to the PayTo Agreement is provided. Up to 140 characters.
Payment Terms Request Model
Field Format Description
frequency string The expected frequency with which payments will be initiated for this PayTo Agreement.

One of:
  • ADHO - Adhoc (on request or as necessary)
  • DAIL - Daily (once a day)
  • WEEK - Weekly (once a week)
  • FRTN - Fortnightly (once every two weeks)
  • MNTH - Monthly (once a month)
  • QURT - Quarterly (once every three months)
  • MIAN - Semi-annually (two times a year or every six months)
  • YEAR - Yearly (every year or once per year)
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.

  • 1-24 for DAIL
  • 1-7 for WEEK
  • 1-14 for FRTN
  • 1-31 for MNTH
  • 1-12 for YEAR
  • 1-3 for QURT
  • 1-6 for MIAN
  • Do not provide for ADHO
agreementType string The type of PayTo Agreement.

One of:
  • BALN - Baloon (Payment amount is fixed with a large final payment amount)
  • FIXE - Fixed (Payment amount is fixed)
  • USGB - Usage-based (Payment amount is based on usage)
  • VARI - Variable (Payment amount is variable - non-uage based)
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:
  • ORGN - An Organisation
  • PERS - An Individual
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:
  • EMAL - Email Address
  • TELI - Mobile Phone Number
  • AUBN - Australian Business Number
  • ORGN - Organisational Identifier
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 /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.
customerNumber string Required. Search for PayTo Agreements for a matching Customer.
status string Optional. The status of the PayTo Agreement. See PayTo Agreement Status.
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.

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:
  • ACTIVE - When the status is SUSPENDED the PayTo Agreement will be un-suspended and set to ACTIVE.
  • SUSPENDED - When the status is ACTIVE the PayTo Agreement will be suspended and set to SUSPENDED.
  • CANCELLED - When the status is ACTIVE or SUSPENDED the PayTo Agreement will be cancelled and set to CANCELLED.
reasonCode string 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 that requires 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. 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 expected frequency with which payments will be initiated for this PayTo Agreement.

One of:
  • ADHO - Adhoc (on request or as necessary)
  • DAIL - Daily (once a day)
  • WEEK - Weekly (once a week)
  • FRTN - Fortnightly (once every two weeks)
  • MNTH - Monthly (once a month)
  • QURT - Quarterly (once every three months)
  • MIAN - Semi-annually (two times a year or every six months)
  • YEAR - Yearly (every year or once per year)
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:
  • BALN - Baloon (Payment amount is fixed with a large final payment amount)
  • FIXE - Fixed (Payment amount is fixed)
  • USGB - Usage-based (Payment amount is based on usage)
  • VARI - Variable (Payment amount is variable - non-uage based)
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.
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.
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 expected frequency with which payments will 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 payment amount.
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.
Westpac Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.