Skip to main content

PayID in QuickStream

Westpac’s PayID Biller is designed to speed up the push payment experience by providing a real-time receivables solution via QuickStream REST API. It enables businesses to generate unique, easily-recognisable PayIDs for customers, facilitating instant payments through online banking.

PayIDs can be configured as Static or Single-use, depending on your payment use case.

View the technical guide

How it works

  1. Create a PayID for your customer. This is an email address that you choose. It can represent your customer, an invoice, or use it for a one-off payment.
  2. Provide this to your customer. You can do this on the web, on bills and invoices, in person or over the phone.
  3. Your customers send the payment to this PayID using their banking app.
  4. You will be notified that the payment was received.

PayIDs

PayID are unique aliases (e.g., 12345678@yourdomain.com.au) linked to your settlement account. It replaces traditional Biller Codes and Customer Reference Numbers (CRNs) used in BPAY, offering a streamlined real-time payment experience.

A PayID can be linked to various identifiers such as a mobile number, email address, Australian Business Number (ABN), or Organisation ID.

With Westpac’s PayID Biller, you can create PayIDs in the form of email addresses.

PayID Types

Single-use PayID

  • Automatically deregisters after one payment.
  • Can be configured to receive a fixed value to prevent an incorrect amount being received.

Static PayID

  • Used for ongoing payments like subscriptions, memberships or regular invoices.
  • Stays active until you request it to be deregistered.

PayID Domains

When setting up PayID Biller, Westpac will configure the domains that will be linked to your PayIDs. These domains must be owned by your business and will form part of the PayID.

For example: 12345678@yourdomain.com.au

If your business requires additional flexibility for reporting, reconciliation, or operational segmentation, you can optionally configure subdomains for your PayID.

For example: 12345678@nsw.yourdomain.com.au

PayID Display Names

Each PayID will be associated with a display name. This must be your legal, business, or trading name, and must be easily recognisable to your customers.

The display name is registered with the PayID Addressing Service and is shown to customers when they enter your PayID in their online banking. This ensures customers can confidently identify your business before making a payment.

Choosing a PayID

The PayID local-part is the numeric or alphanumeric string that appears before the @ symbol in a PayID (e.g., 123456@biller.com.au). It serves as a unique reference for the customer or transaction.

You can determine the local-part based on your business case, including:

  • Repurposing BPAY Customer Reference Numbers (CRNs) or internal customer references that already appear on your invoice/bill.
  • Using invoice numbers or order numbers for single-use PayIDs.

PayID Length

When constructing a PayID in the format local-part@domain, the entire PayID value must not exceed 255 characters. This includes:

  • The local-part (the part before @.)
  • The @ symbol.
  • The domain.

Other considerations:

  • No white spaces are allowed.
  • PayIDs are converted to lowercase before registration.
  • While the PayID format allows for a maximum of 255 characters, using a shorter PayID is recommended for a better customer experience. Shorter PayIDs will also fit more cleanly on invoices, bills and digital interfaces, particularly mobile screens.

UI and Invoicing Guidance

You may wish to include the PayID brandmark when you are presenting PayID as a payment option on a bill, on a payment page or within your checkout screen on a site or in an app.

Copyright

  • On first use, the word PayID should be accompanied by the ® symbol.
  • You must include the following trademark note - "PayID is a registered trademark of NPP Australia Limited".

Instructions to payers

  • Consider including instructions such as "Pay this invoice from your online banking using this PayID".
  • If you are presenting the PayID online, consider including a copy button to enable customers to copy the PayID easily into their online banking.

Reporting

Use these methods to find PayID transactions made through QuickStream:

Refunds

Refund PayID transactions using QuickStream portal and the REST API.

Settlement and response codes

Surcharging

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

PayID with QuickStream REST API

Getting started

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

Before starting your PayID integration:

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

How to implement PayID

PayID Sequence Diagram

Find or create a Customer

PayIDs 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 ••••••

  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 ••••••
Content-Length: 78

{
    "customerNumber": "AMIRAF",
    "customerName": "Amira Fontius"
}

  5. Retrieve the value of customerId from the response.

Create a PayID

Perform the following steps to create a new PayID for the Customer.

  1. From your server, request POST /v1/customers/{customerNumber}/payids with the details of the PayID. Send type=STATIC and payId=testpayment@<your domain>. Replace with one of the allowed domains you have registered in your facility.
    POST /v1/customers/{customerId}/payids HTTP/1.1
Host: api.quickstream.support.qvalent.com
Content-Type: application/json
Authorization: Basic ••••••
Content-Length: 108

{
  "payId": "testpayment@mydomain.com.au",
  "type": "STATIC",
  "supplierBusinessCode": "MYCOMPANY"
}

2.The response contains a PayID Model. The status will be PENDING. Retrieve the value of id.

Receive PayID Webhooks

QuickStream will post a Notification to the endpoint you used in your Webhook Subscription when PayID events occur. Your server will listen for an event signalling that the PayID was created.

  1. Your server receives the request. The data object in the Notification is the PayID Model.
    POST /notifications HTTP/1.1
Host: myserver.com.au
X-Webhook-Signature: t=1704075274000,v1=a78e48ed6b5dd86830f6c571d41d19fb4829ce33f9da0c2f72656b1a4cd4dab8
Content-Type: application/json
Content-Length: 404
{
    "id": "f9424430-3abc-49b5-be58-1f772be68d83",
    "timestamp": "2024-01-01T13:14:34+1100",
    "eventType": "payid.registered",
    "data": {
        "id": "f27371ce-0757-4767-aaf6-05ac7ce9dbe3",
        "payId": "testpayment@mydomain.com.au",
        "type": "STATIC",
        "supplierBusinessCode": "MYCOMPANY",
        "customerId": "87556623117",
        "status": "REGISTERED"
    }
}
  2. Acknowledge the request immediately by returning an HTTP 200.
  3. Confirm eventType=payid.registered, data.status=REGISTERED and data.id matches the one you created in the previous step.
Receive PayID Transaction Webhooks

QuickStream will post a Notification to the endpoint you used in your Webhook Subscription when PayID events occur. Your server will listen for an event signalling that a payment was received for the PayID.

  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=1704075274000,v1=a78e48ed6b5dd86830f6c571d41d19fb4829ce33f9da0c2f72656b1a4cd4dab8
Content-Type: application/json
Authorization: Basic ••••••
Content-Length: 1373

{
  "id": "f9424430-3abc-49b5-be58-1f772be68d83",
  "timestamp": "2024-01-01T13:15:12+1100",
  "eventType": "payto.payment.received",
  "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": "PAYID",
    "voidable": false,
    "refundable": true,
    "comment": null,
    "ipAddress": null,
    "debtRepayment": false,
    "supplierBusinessCode": "MYCOMPANY",
    "payIdBillerAccount": {
        "displayName": "xxx-002 xxxxxx465",
        "currency": "AUD"
    },
    "payIdAccount": {
        "accountType": "PAYID",
        "customerId": "87556623117",
        "id": "f27371ce-0757-4767-aaf6-05ac7ce9dbe3",
        "payId": "testpayment@mydomain.com.au"
    }
  }
}
  2. Acknowledge the request immediately by returning an HTTP 200.
  3. Confirm eventType=payid.payment.received, data.status=Approved and data.payId.id matches the one you created in a previous step.

Testing PayID with QuickStream

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

Improving your solution
  1. If you are building a UI for your customers, refer to the PayID Brand Portal guidelines:
  2. Determine whether Static and/or Single-Use PayID implementations are suitable for your business processes.
  3. Subscribe to and listen for other PayID events in your Webhook integration.
  4. Improve the security of your Webhook integration by adding Basic Authorisation and Verifying Signatures.

Go live

Once you are ready to go live you must:

  • Complete your integration with the QuickStream REST API in the Production environment.
  • Perform live testing for PayID. Create PayIDs in Production, and send payments using Osko® via banking apps.
  • Roll out your solution to customers as a new payment method.

See also

PayID is a registered trademark of NPP Australia.
Osko is a registered trademark of BPAY Pty 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.