Skip to main content

PayTo Webhooks

QuickStream uses webhooks to notify your application as PayTo events occur in your facility.

Webhooks allow you to:

  • Eliminate the need for polling. This saves resources for your application.
  • Eliminate the need for daily reporting. Your application may consume notifications in near real-time, rather than waiting for a report at the end of the day.
  • Execute additional processing. Your application may trigger backend processing once a notification is consumed (e.g. sending a payment receipt via email or SMS, fulfilling an order, shipping goods etc.)
  • Listen for asynchronous events. Some payment channels have asynchronous processes.

Structure

Each Notification is an HTTPS POST.

The Notification includes a Content-Type header, a X-Webhook-Signature header, and optionally the Authorization header.

The body of each Notification contains id, eventType, timestamp and data fields.

{
  "id": "6d9d12d0-a640-48a4-970a-3d9631f31690",
  "timestamp": "2024-02-08T00:12:50+1100",
  "eventType": "payto.payment.approved",
  "data": {...}
}

Setup PayTo Webhooks

Start receiving notifications

  1. Determine which Event Types to listen for.
  2. Create an endpoint to receive Notifications via an HTTPS POST request.
  3. Register your endpoint by creating a Subscription in the QuickStream portal.
  4. Secure your Webhook endpoint and verify signatures.
  5. Handle duplicate notifications and return fast responses.

PayTo Event Types

The PayTo Webhook Event Types you can subscribe to are below:

Event Type Description Data Payload
payto.agreement.confirmed The Payer confirmed the PayTo Agreement. PayTo Agreement Model
payto.agreement.declined The Payer declined the PayTo Agreement. PayTo Agreement Model
payto.agreement.expired The Payer did not action the PayTo Agreement and it expired. PayTo Agreement Model
payto.agreement.recalled The Payee recalled the PayTo Agreement before it could be confirmed or declined by the Payer. PayTo Agreement Model
payto.agreement.amended The Payer amended their account details for a PayTo Agreement, or the Payee amended details of the PayTo Agreement. PayTo Agreement Model
payto.agreement.status.amended The Payer or Payee amended the status for a PayTo Agreement. PayTo Agreement Model
payto.agreement.rejected The PayTo Agreement was not created immediately and a future retry attempt resulted in a rejection. PayTo Agreement Model
payto.payment.approved The PayTo Payment was approved. Transaction Response Model
payto.payment.declined The PayTo Payment declined. Transaction Response Model
payto.refund.approved The PayTo Refund was approved. Transaction Response Model
payto.refund.declined The PayTo Refund declined. Transaction Response Model
payto.agreement.bilateralAmendment.confirmed The Payer confirmed the Bilateral Amendment. PayTo Agreement Model
payto.agreement.bilateralAmendment.declined The Payer declined the Bilateral Amendment. PayTo Agreement Model
payto.agreement.bilateralAmendment.expired The Payer did not action the Bilateral Amendment and it expired. PayTo Agreement Model
payto.agreement.bilateralAmendment.rejected A Bilateral Amendment was not created immediately and a future attempt resulted in a rejection. PayTo Agreement Model
payto.agreement.bilateralAmendment.recalled The Payee recalled the Bilateral Amendment before it could be confirmed or declined by the Payer. PayTo Agreement Model
payto.agreement.unilateralAmendment.complete A Unilateral Amendment has completed. PayTo Agreement Model
payto.agreement.unilateralAmendment.rejected A Unilateral Amendment was not created immediately and a future retry attempt resulted in a rejection. PayTo Agreement Model
payto.agreement.statusAmendment.rejected A Status Amendment was not created immediately and a future retry attempt resulted in a rejection. PayTo Agreement Model

Best Practices

Security

We recommend you use Basic Authentication over HTTPS. You can set a Basic Auth username and password on each Subscription.

We require you to use HTTPS endpoints with TLSv1.2 or TLSv1.3. QuickStream posts via port 443 (and cannot post to a different port number.)

We recommend you verify notifications by computing an HMAC and comparing it to the X-Webhook-Signature header. See Verify Signatures.

Verify Signatures

By verifying the X-Webhook-Signature header, you can confirm that the notification was sent by QuickStream and was not modified during transmission.

This header is in the format: t={timestamp},v1={signature}.

To verify a signature:

  1. Concatenate the timestamp t and data fields with a comma , character.
  2. Generate an HMAC with SHA-256 using the Signing Secret from the Subscription.
  3. Compare the output with the v1 field in the X-Webhook-Signature header.

Additionally, calculate the difference between the timestamp field and the current timestamp and decide if the difference is within your tolerance.

Rolling the Signing Secret

It is recommended that you periodically roll the Signing Secret for each Subscription at least every 2 years. This can be done in 2 ways:

  1. Generate a new secret for each Subscription. In-flight notifications will always use the new secret and so your server must expect this.
  2. Create a new Subscription with the same URL, Authorisation and Event Types. Then disable it.
  3. Once the new secret is expected by your server, enable it and disable the old one.

Disabling Subscriptions

You may want to disable Subscriptions when:

  • Rolling a Signing Secret (see above)
  • When your system is unable to receive a notification (such as during maintenance)

Automatic Disabling of Unused Subscriptions

If a subscription is unused for one year, it will be automatically disabled. We recommend making a single subscription for multiple event types so that subscriptions for uncommon event types do not get disabled while your facility is still in use.

Avoid Subscribing to Extra Event Types

It is recommended that you do not subscribe to event types that you do not need to process. Listening for extra events, or every event, adds strain to your server.

Handling Duplicate Notifications

In some cases, you may receive a notification more than once. You must make sure you system can deal with duplicates.

Duplicate notifications will have the same id and type fields while other fields may differ. Your server should use these details contained in the latest notification.

You may log the notifications that have been processed, and then not process any that have already been logged.

Retrying Notifications

To ensure notifications are delivered properly, your server must acknowledge them with an appropriate HTTP response code.

QuickStream will then retry sending the notification until it is accepted, or until it has retried too many times.

If your server doesn't acknowledge a notification, you will receive an email after the final retry. To make sure you receive these emails, you should always provide a group email address for these notifications.

Notifications can then be re-submitted to the queue manually if required.

Verify Notifications are Sent from QuickStream

Notifications are sent from 192.170.86.153 in Production, and 203.39.159.31 in Test. You may use an IP address allow list to accept notifications from these IP addresses.

Additionally, you can confirm notifications are sent from us by Verifying Signatures and adding Security.

Return a Fast HTTP 2xx Response

Your endpoint must return an HTTP 2xx response as fast as possible, before processing any business logic that could cause a timeout.

Troubleshooting

If your endpoint is not accepting notifications properly, you can troubleshoot the issue by viewing the Notification History.

The history contains the HTTP response code that was sent by your system, and details about the notification.

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.