Skip to main content

PayTo in QuickStream

QuickStream allows you to take advantage of PayTo®. PayTo is a fast, smart, and safe way for consumers and businesses to pay and get paid directly from a bank account. For biller merchants and businesses, it provides more certainty with real-time payments, account validation, payment confirmation and notifications at each step of the process. It’s also more flexible, providing richer payment data and may assist in reducing the chances of exception processing.

View the technical guide
Real-time advantage
  • Real-time settlement provides certainty of collections and cash flow.
  • Immediate notification of rejected payments due to insufficient funds allows you to act sooner.
  • Real-time, richer transaction data supports easy same-day matching and reconciliation.
Operational efficiency
  • Reduce administration burden and associated costs of maintaining direct debit agreements & arrangements.
  • Avoid costly payment return fees, rework, and reduce and resolve payment rejections with real-time notifications.
  • Real-time account validation ensures account details are correct every time, reducing disputes.
Customer experience
  • Gain a competitive advantage by offering a seamless digital onboarding experience.
  • Establish secure payment arrangements (one-off and reoccurring) in minutes.
  • Consumers have more transparency and control of their payment agreements.
Enhanced security
  • Take payment from the right account – every time.
  • Reduce direct debit fraud with PayTo’s verified customer authorisation.
  • PayTo Agreements are stored digitally in a secure centralised repository, minimising the need for you to maintain sensitive customer data.

Reporting

Use these methods to find PayTo transactions made through QuickStream:

Refunds

Refund PayTo transactions using QuickStream portal and the REST API.

Only the full amount may be returned. Partial refunds are not supported for PayTo.

Settlement and response codes

Surcharging

Automatic calculation of surcharges by QuickStream is not supported for PayTo.

PayTo with QuickStream REST API

Getting started

This page explains adding PayTo to your QuickStream REST API integration. If you haven't done this integration yet, refer to our API reference.

Before starting your PayTo integration:

  1. Ensure you have received your Secret REST API key for our QuickStream REST API.
  2. Create a Webhook Subscription for the payto.agreement.confirmed and payto.payment.approved events that are posted to your back-end implementation.
  3. Update your existing back-end integration to be ready to:

How to implement PayTo

Sequence diagram illustrating the steps below.

Find or create a Customer

PayTo Agreements are associated with a Customer. Perform the following steps to find or create a Customer.

  1. Obtain a unique identifier for a Customer.
  2. From your server, request GET /v1/customers?customerNumber={customerNumber} using your Secret REST API key.
    GET /rest/v1/customers?customerNumber=CUSTOMER123 HTTP/1.1
Host: api.quickstream.support.qvalent.com
Authorization: Basic eW91cmFwaWtleTo=
  3. The response contains the result of the query. Determine if there is an existing Customer returned in the response and retrieve the customerId.
  4. If there is no existing Customer returned, create a new one. From your server, request POST /v1/customers using your Secret API key. Provide at least a customerName and a unique customerNumber in the request body.
    POST /rest/v1/customers HTTP/1.1
Host: api.quickstream.support.qvalent.com
Accept: application/json
Content-Type: application/json
Authorization: Basic eW91cmFwaWtleTo=
Content-Length: 78

{
    "customerNumber": "AMIRAF",
    "customerName": "Amira Fontius"
}
  5. Retrieve the value of customerId from the response.
Create a PayTo Agreement

Perform the following steps to create a new PayTo Agreement for the Customer.

A PayTo Agreement must be confirmed or declined by a Payer in their banking app. In this case, you will simulate a Payer immediately confirming this PayTo Agreement by providing specific details in the payerDetails request object.

  1. From your server, request POST /v1/customers/{customerId}/payto-agreements with the details of the PayTo Agreement. Send payerDetails.payIdType=EMAL and payerDetails.payId=TEST@MYCUSTOMER.COM.AU.
    POST /rest/v1/customers/236010801/payto-agreements HTTP/1.1
Host: api.quickstream.support.qvalent.com
Content-Type: application/json
Authorization: Basic eW91cmFwaWtleTo=
Content-Length: 645

{
    "supplierBusinessCode": "MYBUSINESS",
    "paymentDetails": {
        "purpose": "UTIL",
        "description": "Your monthly utility payments",
        "startDate": "2024-01-01",
        "automaticRenewal": true
    },
    "paymentTerms": {
        "frequency": "MNTH",
        "agreementType": "FIXE",
        "paymentAmount": "10.00",
        "currency": "AUD"
    },
    "payerDetails": {
        "payerType": "PERS",
        "payerId": "PS19400650001",
        "payerName": "AMIRA FONTIUS",
        "payerReference": "PY19000890013",
        "payIdType": "EMAL",
        "payId": "TEST@MYCUSTOMER.COM.AU"
    }
}
  2. The response contains a PayTo Agreement Model. The status will be PENDING. Retrieve the value of agreementToken.
Receive PayTo Agreement Webhooks

QuickStream will post a Notification to the endpoint you used in your Webhook Subscription when PayTo events occur. Your server will listen for an event signalling that the Payer has confirmed the PayTo Agreement in their banking app.

  1. Your server receives the request. The data object in the Notification is the PayTo Agreement Model.
    POST /notifications HTTP/1.1
Host: myserver.com.au
X-Webhook-Signature: t=1704075274000,v1=a78e48ed6b5dd86830f6c571d41d19fb4829ce33f9da0c2f72656b1a4cd4dab8
Content-Type: application/json
Content-Length: 1788

{
  "id": "f9424430-3abc-49b5-be58-1f772be68d83",
  "timestamp": "2024-01-01T13:14:34+1100",
  "eventType": "payto.agreement.confirmed",
  "data": {
    "agreementToken": "AGREEMENT_TOKEN",
    "status": "ACTIVE",
    "priority": "UNAT",
    "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": 10,
        "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": "T****@M****.COM.AU"
    },
    "payeeDetails": {
      "supplierBusinessCode": "MYCOMPANY",
      "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"
    }
  }
}
  2. Acknowledge the request immediately by returning an HTTP 200.
  3. Confirm eventType=payto.agreement.confirmed, data.status=ACTIVE and data.agreementToken matches the one you created in the previous step.

Take a Payment

  1. After obtaining the agreementToken and receiving the confirmation event via the Notification above, take a payment for the PayTo Agreement.
  2. From your server, request POST /v1/transactions using your Secret REST API key, specifying the agreementToken .
    POST /rest/v1/transactions HTTP/1.1
Host: api.quickstream.support.qvalent.com
Content-Type: application/json
Authorization: Basic eW91cmFwaWtleTo=
Content-Length: 385

{
    "transactionType" : "PAYMENT",
    "payToData": {
        "agreementToken": "AGREEMENT_TOKEN",
        "remittanceInformation1": "PAYMENT FOR CUSTOMERA",
        "finalPayment": false
    },
    "supplierBusinessCode": "MYCOMPANY",
    "principalAmount": 10.00,
    "currency" : "AUD"
}
  3. The response contains the result of the payment. Retrieve the value of receiptNumber.

Receive PayTo Transaction Webhooks

QuickStream will post a Notification to the endpoint you used in your Webhook Subscription when PayTo events occur. Your server will listen for an event signalling that the Transaction has been approved or declined.

  1. Your server receives the request. The data object in the Notification is the Transaction Response Model.
    POST /notifications HTTP/1.1
Host: myserver.com.au
X-Webhook-Signature: t=1704075312000,v1=088f48ed6b5dd86880f6c571d41d19fb4829ce33f9da0c2f72656b1a4cd4dab8
Content-Type: application/json
Content-Length: 1774

{
  "id": "f9424430-3abc-49b5-be58-1f772be68d83",
  "timestamp": "2024-01-01T13:15:12+1100",
  "eventType": "payto.payment.approved",
  "data": {
    "receiptNumber": "1694965611",
    "principalAmount": {
        "currency": "AUD",
        "amount": 10.00,
        "displayAmount": "$10.00"
    },
    "surchargeAmount": {
        "currency": "AUD",
        "amount": 0.00,
        "displayAmount": "$0.00"
    },
    "totalAmount": {
        "currency": "AUD",
        "amount": 10.00,
        "displayAmount": "$10.00"
    },
    "status": "Approved",
    "responseCode": "ACSC",
    "responseDescription": "Accepted Settlement Completed Debtor Account",
    "summaryCode": "0",
    "transactionType": "PAYMENT",
    "fraudGuardResult": null,
    "transactionTime": "2024-01-01T13:15:12+1100",
    "settlementDate": "2024-01-01",
    "source": "RESTAPI",
    "voidable": false,
    "refundable": true,
    "comment": null,
    "ipAddress": null,
    "debtRepayment": false,
    "supplierBusinessCode": "MYCOMPANY",
    "payToData": {
        "agreementToken": "AGREEMENT_TOKEN",
        "endToEndId": "1694965611",
        "priority": "NORM",
        "remittanceInformation1": "PAYMENT FOR CUSTOMERA",
        "remittanceInformation2": null
    },
    "payToPayeeAccount": {
        "displayName": "xxx-002 xxxxxx465",
        "currency": "AUD"
    },
    "payToPayerAccount": {
        "accountType": "PAYTO",
        "customerId": "87556623117",
        "payerType": "PERS",
        "payerId": "PS19400650001",
        "payerName": "AMIRA FONTIUS",
        "ultimatePayerName": "AMIRA FONTIUS",
        "maskedAccountNumber": null,
        "payIdType": "EMAL",
        "payId": "T****@M****.COM.AU"
    }
  }
}
  2. Acknowledge the request immediately by returning an HTTP 200.
  3. Confirm eventType=payto.payment.approved, data.status=Approved and data.receiptNumber matches the one you created in the previous step.

Testing PayTo with QuickStream

QuickStream can generate different responses to test a broad range of PayTo scenarios. See the Test PayTo Account Numbers.

Improving your solution
  1. If you are building a UI for your customers, refer to the PayTo Brand Portal guidelines:
  2. If you wish to submit payments in batches, provide the Agreement Token in one of these Payment File formats and upload it:
  3. Subscribe to and listen for other PayTo events in your Webhook integration.
  4. Improve the security of your Webhook integration by adding Basic Authorisation and Verifying Signatures.
  5. Use Bilateral Amendments, Unilateral Amendments and Status Amendments to manage existing PayTo Agreements.

Go live

Once you are ready to go live you must:

  • Complete your integration with the QuickStream REST API and Payment Files in the Production environment.
  • Perform live testing for PayTo. Create PayTo Agreements in Production, and approve/decline them via financial institution banking apps.
  • Roll out your solution to customers as a new payment method.

See also

PayTo is a registered trademark of NPP Australia Limited.

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.