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

API collection & environment

These files are used to import the PaymentsPlus API Environment and Collection of API's into Postman for use and testing.

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

Getting started

• Sign-in to PaymentsPlus to get your API keys.
• This API is RESTful.
• Determine the base URL for the Test environment.
• Send your API key as the HTTP Basic Auth username. Leave the password blank.
• You send JSON formatted requests and the API returns JSON formatted responses.
• You must put in place error handling based on HTTP status codes.
• Files and Payments are the most important resources.

Read next:

• Explore the Tutorials.
• Resource Summary.
• Keep up-to-date with the Change-log.

Base URL

Use the PaymentsPlus REST APIs in these environments:

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

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.

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.

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 1 year 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.

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:

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.

Links

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

For example:

{
    "rel": "",
    "href": "",
    "requestMethod": ""
}

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:

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.

API Keys

For API Keys resource details, see API Keys API.

Methods

For Methods resource details, see Methods API.

Accounts

For Accounts resource details, see Accounts API.

Banking Days

For Banking Days resource details, see Banking Days API.

Files

For Files resource details, see Files API.

Payments

For Payments resource details, see Payments API.

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 errors

The response body includes field-level validation errors.

For example:

{
    "messages": [],
    "fieldName": "",
    "fieldValue": ""
}

HTTP status codes

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

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.

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.

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).

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).