API Reference

API Reference

The PaymentsPlus REST API is RESTful. The API authorisation framework is HTTP Basic Auth.

You send JSON formatted requests and the API returns JSON formatted responses. Because the REST API is based on open standards, you can use any web development language to access the API.

Access depends on the enabled capabilities of your PaymentsPlus facility.

Our APIs

Files

PaymentsPlus uses files to group payments to be processed.

Payments

Search for payments and find payments across files.

Accounts

Determine available funding accounts and the types of payments that can be made using those accounts.

Methods

Determine the types payments you can make, and list the funding accounts that are available for those kinds of payments

Banking days

Check if a day is an Australian banking day and whether payments will be processed on that day.

API keys

Use your existing key to get a new key and automate your API key renewal.

To test your network connectivity and API credentials are working correctly, use the Root API.

Getting started

Read next:

Base URL

The URLs in this reference are relative to the base URL.

Use the PaymentsPlus REST APIs in these environments:

Environment Description URL
Support This is the Test environment. Use your test API keys to make calls to the test URIs. https://api.paymentsplus.support.qvalent.com/rest/v1
Production This is the Live environment. Use your production API keys to make calls to the live URIs. https://api.paymentsplus.stgeorge.com.au/rest/v1
Only access this API using the URIs above. The IP address can change at any time.

Versioning

The current version of the API is v1.

Our change log outlines changes between various API versions to help our clients better integrate with our API service.

If we make any backwards incompatible changes we will release a new major version of the API.

Resources

The following changes will not result in a new API version:

  • Adding new resources.
  • Supporting new HTTP verbs.
  • Changing the length or format of IDs. You can assume IDs we generate will not exceed 255 characters. You should be able to handle IDs of up to 255 characters.
  • Adding new optional request parameters.
  • Adding new properties in responses.
  • Changing the order of properties in requests and responses.
  • Changing wording of error message designed to be displayed to users.
  • Improved error reporting when an invalid request is received.
  • Appending new optional fields to, or re-purposing filler fields in reports and files.

Your software must be written to handle these types of changes.

Security

The following changes will not result in a new API version:

  • Adding or removing TLS ciphers.
  • Changing supported TLS versions.
  • Other changes made to improve security.

If you believe we have made a backwards-incompatible change, please report a defect.

Credentials and security

Authentication and headers

Authentication to the API is via HTTP Basic Auth. All API requests must be made over HTTPS.

For example:

GET /rest/v1 HTTP/1.1
Host: api.paymentsplus.westpac.com.au
Authorization: Basic cXZ0ZXN0YXBpa2V5Og==
Accept: application/json
Request header Description
Authorization When you access a resource you must use your API key. You must send an API key as the Basic Authentication username. Leave the password blank.
Accept Set to application-json. Required.

API credentials

API Key

You must provide the API Key to access the API. The API Key allows you to process payments and provides full access to the API.

Treat your API key like a password.

To get these values:

  1. Sign-in to PaymentsPlus in the test or production environment.
  2. To get an API key, navigate to Administration -> REST API -> REST API Keys.

API Keys Screen

From this screen you can create additional keys as required, or you can click on the key name to view the details key. When a key is created you will be shown the full API key value. Once you leave that page the full key will not be able to be seen again. If you don't note the value down you will need to create a new key to get access.

API keys expire after 2 years and then you must use a new key. You can automate API key renewal.

Each resource in this API requires your API Key to access.

Sending an invalid API key returns a 401 Unauthorized HTTP status code.

To test authentication, send a GET to the base URL.

IP Whitelisting

You must whitelist the IP addresses you wish to connect to the API with. Any IP addresses not whitelisted through the portal will not be allowed to connect to the API.

To whitelist an IP address:

  1. Sign-in to PaymentsPlus in the test or production environment.
  2. Navigate to Administration -> REST API -> IP Whitelisting.

IP Whitelisting Screen

From this screen you can add, edit, and remove IP addresses that have been whitelisted. An IP address range can be used using CIDR Notation

Transport layer security

You must secure your connection using Transport Layer Security (TLS) 1.2 over HTTPS.

DDOS Protection

This API has Distributed Denial-of-Service (DDOS) protection. DDOS protection is used to prevent malicious users using all the available resources.

HTTP verbs

The standard HTTP verbs used are:

Verb Purpose
GET Read a resource
PUT Create or replace a resource when URL is known
POST Create a resource when URL is not known
PATCH Update details of a resource
DELETE Delete a resource
If you send a PUT request and omit a field, the server removes or defaults the field value.

HATEOAS and pagination

If available, each response from the API includes an array of contextual HATEOAS links. You can follow links returned in responses to related resources.

Open help URLs in your browser to access developer help (usually this reference).

Resources which return lists use a standard structure:

  • The data JSON property holds up to 20 items.
  • More results can be found by following next and prev links.

See Links for the response body.

The response body contains links in most responses generated by this API.

For example:

{
    "rel": "",
    "href": "",
    "requestMethod": ""
}
Field Format Data
rel string The relationship to the resource. Open help URLs in a browser to view this developer reference. next and prev are used for paginated resources.
href string URL of a related document or resource.
requestMethod string HTTP Verb

Filtering

You can use query parameters to filter the responses to some GET requests.

For example, to List Files for a date you must provide the query parameter date.

For example

GET rest/v1/files/for-date?date=2018-01-01 HTTP/1.1
Host: api.paymentsplus.westpac.com.au
Authorization: Basic cXZ0ZXN0YXBpa2V5Og==
Accept: application/json

Dates

Dates are requested and returned as a string in the following formats:

Reference Format Description
date YYYY-MM-DD For dates with no time component, use the ISO-8601 short date format. An example is the settlement date, which groups together transactions which are part of the same logical banking day.
date-time YYYY-MM-DDTHH:mm:ssZ For dates with a time component, use the ISO-8601 extended format.
date-month YYYY-MM For dates with no day component, use the ISO-8601 year and month format. This format is used to filter large result sets by month and year.

For example:

{
    "settlementDate": "2022-01-02",
    "month": "2022-01",
    "transactionDateTime": "2022-01-02T03:48:40+00:00"
}

Resource summary

This API reference is organised by resource type. Each resource type has one or more data models and one or more methods.

Root

For Root resource details, see Root API.

Action HTTP request Description
Get GET / Gets information about your facility. Use to test your network connectivity and API credentials are working correctly.

API Keys

For API Keys resource details, see API Keys API.

Action HTTP request Description
Get latest GET /api-keys/latest Get your latest API Key and automate your key renewal code.

Methods

For Methods resource details, see Methods API.

Action HTTP request Description
Get available methods GET /methods Return a list of Payment Methods that are available for the Buyer.

Accounts

For Accounts resource details, see Accounts API.

Action HTTP request Description
Get Australian settlement account GET /accounts/{bsb}-{accountNumber} Get Australian settlement account details.
List settlement accounts GET /accounts List buyer settlement accounts.

Banking Days

For Banking Days resource details, see Banking Days API.

Action HTTP request Description
Get Australian settlement account GET /banking-days/{yyyy-MM-dd}?instrument={string} Check if the date is a banking day for an instrument.

Files

For Files resource details, see Files API.

Action HTTP request Description
Upload a file PUT /files/{fileIdentifier}/upload Upload a file and process the payments immediately.
Create a file PUT /files/{fileIdentifier} Create a file that will be sent later.
Cancel a file POST /files/{fileIdentifier}/cancel Cancel a file that has been created.
Close and Send a file POST /files/{fileIdentifier}/send Close and send a file.
List recent files GET /files/ Return the last 20 files.
Search files by status GET /files/for-status?status={string} Search files in a particular status.
Search files by date GET /files/for-date?date={string} Search files created on a particular date.
Search files by file name GET /files/for-filename?filename={string} Search files by the file name.
Create payment PUT /files/{fileIdentifier}/payments/{paymentIdentifier} Create a payment in a file.
Cancel payment POST /files/{fileIdentifier}/payments/{paymentIdentifier}/cancel Cancel a payment in a file.
List file payments GET /files/{fileIdentifier}/payments List the payments in a file.
Get payment GET /files/{fileIdentifier}/payments/{paymentIdentifier} Get the details of a payment.

Payments

For Payments resource details, see Payments API.

Action HTTP request Description
Search payments by date GET /payments/for-date?date={string} Search payments created on a particular date.
Search payments by reference GET /payments/for-reference?reference={string} Search payments by reference.
List pending payments GET /payments/pending List pending payments.
List returned payments GET /payments/returns List payments returned in the last 2 banking days.

Errors

Error handling

If you receive one of these responses, wait 20 seconds and then re-send the same request.

  • 429 Too Many Requests
  • 503 Service Unavailable
  • A transient network error, such as a time-out or closed socket

If you receive a 422 Unprocessable Entity you may display the error message to your user and allow them to correct the data.

If you receive any other response code, you should log the response code and response body.

See HTTP Status Codes.

Error responses

The response body for all HTTP errors includes additional error details.

For example:

{
    "links": [],
    "status": "",
    "requestMethod": "",
    "requestUrl": "",
    "customerMessage": "",
    "developerMessage": "",
    "errors": []
}
Field Format Data
links Array of Links One or more links related to the error.
status string HTTP status code.
requestMethod string HTTP method used in the request that resulted in this error.
requestUrl string URL used in the request that resulted in this error.
customerMessage string A user friendly message you can display to your customers.
developerMessage string A developer friendly message that may provide more information.
errors Array of Field Errors (optional) A list of validation errors that may be applicable to the response.

Field errors

The response body includes field-level validation errors.

For example:

{
    "messages": [],
    "fieldName": "",
    "fieldValue": ""
}
Field Format Data
messages Array of string A list of error messages you can display to your customers. Do not rely on error messages as we may change them without notice.
fieldName string The name of the field in the request that resulted in this error.
fieldValue string The value of the field provided in the request that resulted in this error.

HTTP status codes

PaymentsPlus REST API returns standard HTTP status codes for successful and error responses.

Status Code Description More information
200 OK The request has succeeded.
201 CREATED The server has created the resource you requested. If you created a transaction, you must use the status field to determine if the transaction was approved. The Location header points to the new resource.
202 ACCEPTED The request has been accepted for processing, but the processing has not completed.

For transactions, this response code is returned if the banking network is slow to respond when processing a transaction. The status of the transaction will be pending. To find out if a transaction is approved or declined, send a request to get transaction details.
204 NO CONTENT Response to a successful request that won't be returning a body. This response code is returned for DELETE requests.
400 BAD REQUEST The request could not be understood by the server due to malformed syntax.

This response code is returned if you send query parameters on a PUT, POST or PATCH request.
401 UNAUTHORIZED View more.
403 FORBIDDEN View more.
404 NOT FOUND The server has not found anything matching the Request-URI. The response body may contain more information.
405 METHOD NOT ALLOWED A request was made of a resource using a request method not supported by that resource. For example, you sent a POST to a resource that only allows GET. Refer to the documentation of the resource for supported methods.
406 NOT ACCEPTABLE The server can not send the representation requested by the client. For example, the accept header provided was not application/json.
407 PROXY AUTHENTICATION REQUIRED This error is returned by your proxy server, not PaymentsPlus. You need to configure a proxy username and password in order to access the internet.
409 CONFLICT The server can not process the request as it has conflicted with another request. For example, this occurs if you attempt to create two customers with the same customer number simultaneously.
415 UNSUPPORTED_MEDIA_TYPE The server can not process the content type which was provided. The content type header provided was not application/json.
422 UNPROCESSABLE ENTITY View more.
429 TOO MANY REQUESTS View more.
500 INTERNAL SERVER ERROR View more.
501 NOT IMPLEMENTED The server does not recognize the request method. Use one of the standard HTTP verbs.
503 SERVICE UNAVAILABLE View more.

401 Unauthorized

The server can not authenticate the details in the Authorization header. The response body contains more specific information.

This indicates that you have not passed a valid API key, the key has expired, or the Authorization header is not formatted correctly. Correctly formatted requests include a header like this:

Authorization: Basic cXZ0ZXN0YXBpa2V5Og==

The letters after Basic are the base-64 encoded representation of your API key.

See Authentication and Headers.

403 Forbidden

A valid API key was provided, but it does not have access to the requested resource.

Facility setup incomplete

Your facility configuration is not completed. Contact your Westpac representative.

Facility is not live

Your facility is not live in the Production environment. This error is not returned in the Support (test) environment. Contact your Westpac representative.

422 Unprocessable Entity

The server can not process the content of the request. The response body indicates which parameters are in error. You may display the error messages to users.

Do not rely on a specific wording. We may change the wording of error messages without notification. Use the error codes instead.

You should resend the request with corrected parameters.

Payment method required

The requested payment method is not accepted by your facility. For example, you tried to make a bank account payment when your facility is not set up to accept bank account payments.

429 Too Many Requests

When a request is rejected due to rate limiting you have sent too many requests in a given amount of time. If you send more than 10 simultaneous requests, you may receive this response code.

Token Quota Exceeded

A quota of 1000 unused single-use-tokens applies per facility and per IP address. Immediately after obtaining a single-use-token, you should use it.

If you exceed the quota, it is likely that you are creating tokens and not using them. Tokens expire after 10 minutes. After they expire, you can create more.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

You should not resend the request. The server may have completed some of the request processing. Contact PaymentsPlus Technical Support. Provide the following information:

  • the PaymentsPlus community code for your facility,
  • the method you sent in the request (e.g. GET, POST),
  • the URL you sent in the request,
  • the date/time of the request,
  • the response body returned by the server (if any).
Do not email an API key. Email is not secure.

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

If you continue to experience problems, contact PaymentsPlus Technical Support. Provide the following information:

  • the PaymentsPlus buyer code for your facility,
  • the method you sent in the request (e.g. GET, POST),
  • the URL you sent in the request,
  • the date/time of the request,
  • the response body returned by the server (if any).
Do not email an API key. Email is not secure.