NAV

PayWay REST API

PayWay is a simple, secure, internet-based solution to collect and manage customer payments.

Find out more about PayWay.

About This API

This page describes the PayWay REST Application Programmer Interface.

Access depends on the modules you purchased.

The PayWay Recurring Billing and Customer Vault module allows you to:

The PayWay Match module allows you to:

When a customer pays you by direct credit, PayWay matches the payment to the customer.

The PayWay Batch module allows you to:

The PayWay Connect module allows you to:

You can then upload the file into your accounting package.

Other APIs

PayWay supports other ways to interface with your software:

PayWay Module Situation
PayWay Credit Card API Process payments by sending credit card details from your PCI-DSS compliant system.
PayWay Net Process payments using a payment page hosted by us.

Developer guides for these modules are available on the Downloads page.

Quick Start

Read next:

Basics

Versioning and Base URL

Current Version

The current version of this API is version 1.

Base URL

The base URL of the PayWay REST API is https://api.payway.com.au/rest/v1/.

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

Transport Layer Security

You must connect using https supporting at least TLS version 1.2.

Backwards Compatible Changes

We will release a new major version of the API if any backwards incompatible changes are made.

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

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

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

Authentication

Basic Authentication

You must send an API key as the Basic Authentication user name. Leave the password blank.

API Keys

There are two types of keys:

Obtaining an API Key

To request a free test PayWay facility, email PayWay Technical Support (payway@qvalent.com) and request a test PayWay facility.

To purchase a live PayWay facility, see Enquire Now.

Once you have a facility, to view and manage your API keys:

  1. Sign-in to PayWay
  2. Click REST API in the menu

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

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

Sending Requests

HTTP Verbs

The standard HTTP verbs are used.

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

POST is also used on “action resources” to cause a side-effect such as sending an email receipt.

Requesting JSON or XML

To request JSON responses, send this header:

Accept: application/json

To request XML responses, send this header:

Accept: application/xml

Sending Fields for PUT, POST and PATCH

Use the x-www-form-urlencoded content type for sending fields in PUT, POST and PATCH requests.

You must send this header:

Content-Type: application/x-www-form-urlencoded

The request body must contain name/value pairs which have been URL encoded. Use a standard library for URL encoding.

Uploading Files

Use the multipart/form-data content type for uploading files.

You must send this header:

Content-Type: multipart/form-data

Use cUrl or a standard library to create the request.

Avoiding Duplicate POSTs

You should set a unique value for the Idempotency-Key header on POST requests. Use a UUID for your idempotency key. For example:

Idempotency-Key: a1b22c16-4870-428c-a199-6203cbec7290

This allows requests to be retried after a network failure without accidental duplication. If you receive a network error or timeout, you should resend the request with the same Idempotency-Key.

If you resend a POST request with the same value for the Idempotency-Key, you will receive the original response. If the server is still processing the original POST, you will receive 429 Too Many Requests.

Idempotency keys expire after 24 hours. The maximum length is 60 ascii characters.

Error Handling

If you receive one of these responses, wait 20 seconds and then resend the request with the same Idempotency-Key:

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 Response Codes.

<examples> 
<data> 
  <example>one</example>
  <example>two</example>
</data> 
<links> 
  <link rel="prev" 
        href="https://api.payway.com.au/example?page=2" /> 
  <link rel="next" 
        href="https://api.payway.com.au/example?page=4" />
</links>
</examples>
{
"data" : [ { 
    "example": "one"
  }, {
    "example": "two"
  }
],
"links" : [ {
    "rel" : "prev",
    "href" : "https://api.payway.com.au/example?page=2"
  }, {
    "rel" : "next",
    "href" : "https://api.payway.com.au/example?page=4"
  }
  ]
}

You can follow links returned in responses to related resources. This is known as HATEOAS.

Links are returned in the format shown in the examples.

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

Lists of Items

Resources which return lists use a standard structure:

Search URLs

Search URLs are templates:

/search-example?customerNumber={customerNumber}

You must replace parts delimited by braces with actual values.

Dates and Times

<example>
  <settlementDate>05 May 2015</settlementDate>
  <transactionDateTime>05 May 2015 13:00 AEST</transactionDateTime>
  <expiryDateMonth>01</expiryDateMonth>
  <expiryDateYear>22</expiryDateYear>
</example>
{
"settlementDate": "05 May 2015",
"transactionDateTime": "05 May 2015 13:00 AEST",
"expiryDateMonth": "01",
"expiryDateYear": "22"
}

Dates with no time component are formatted as dd MMM yyyy. An example of such a date is the settlement date, which groups together transactions which are part of the same logical banking day.

Dates with a time component (such as when an event happened) are formatted as dd MMM yyyy HH:mm z. In this case, z represents the timezone.

A credit card expiry month is treated as a two digit string. A credit card expiry year is treated as a two digit string. This matches what is printed on credit cards.

Tutorials

Tokenisation from Web Page

Use this tutorial to create a web page that stores credit card details in the customer vault. Your server will not store or process credit card details.

It works as follows:

  1. Your website displays a form for entering credit card details
  2. Your customer’s browser sends credit card details directly to PayWay
  3. PayWay generates a single use token and returns it to you
  4. You send the token in a request to create a customer in the vault

Step 1: Add PayWay JavaScript

Copy the line below and paste it in the <head> of your web page.

<meta charset="utf-8">

Copy the line below and paste it into the <body> of your web page.

<script type="text/javascript" src="https://api.payway.com.au/rest/v1/creditCardForm.js?apiKey={publishableApiKey}&redirectUrl={redirectUrl}"></script>

We will edit this line in the following steps.

When you reload the page, you should see:

The API key you have provided is invalid. It may be a secret key, expired or deleted.

Step 2: Set Publishable Key

  1. Sign-in to PayWay
  2. Click on REST API in the menu
  3. Go to the API Keys page
  4. Click on your publishable key (or add a new one)
  5. Copy the key
  6. In your web page, replace {publishableApiKey} with your publishable key

When you reload the web page, you should see:

The redirect URL should not be enclosed in brackets.

Step 3: Set Browser Redirect URL

Screenshot of credit card form

The redirect URL is a web page on your server which will process the token.

  1. Sign-in to PayWay
  2. Click on REST API in the menu
  3. Go to the Browser Redirect URLs page
  4. Choose a URL on your site and add your redirect URL
  5. In your web page, replace {redirectUrl} with your URL.

When you reload the web page, you should see the credit card form.

Step 4: Add a Button

Copy the line below and paste it after the <script> tag you added above.

<button id="payway-creditcard-submit" onclick="paywayCreditCardSubmit()" disabled="true">Register</button>

When you reload the web page, you should see the credit card form and a button.

Step 5: Test Redirect

Enter these card details and click Register:

Field Value
Card Number 4564 7100 0000 0004
Security Code 847
Name on Card Token Tutorial
Expiry Date 02 / 19

Your browser should redirect to the URL you set on the previous step. The URL includes a query parameter like this:

?singleUseTokenId=2bcec36f-7b02-43db-b3ec-bfb65acfe272

Step 6: Create Customer

You can now use the single use token to create a customer.

Your software should:

  1. Read the single use token from the query parameter
  2. Verify the customer using a session cookie
  3. Using your secret API key and the single use token, send a POST to store credit card for new customer

Step 7: Improve Your Solution

You may now improve your solution by:-

Use cURL to check network

For your software to work, your server must be able to connect to PayWay. Use this tutorial to determine if a problem is with your network or your software.

Step 1: Download and install cURL

Download and install the cURL client for your platform from http://curl.haxx.se/download.html. Be sure to download the correct distribution for your server’s operating system. You must download a version that includes SSL support.

If you are using Windows, we recommend that you download the binary distribution listed under the heading Win32 - Generic labelled Win32 2000/XP, binary and SSL and maintained by Günter Knauf. This document does not provide a direct link because you should always download the latest version.

Step 2: GET the root resource for the API

Expected response:

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 479
Date: Mon, 29 Jun 2015 23:43:13 GMT

{
  "clientNumber" : "T10000",
  "clientName" : "Demo Pty Ltd",
  "keyName" : "T10000_PUB...457",
  "links" : [ {
    "rel" : "single-use-tokens",
    "href" : "https://api.payway.com.au/rest/v1/single-use-tokens"
  }, {
    "rel" : "surcharges",
    "href" : "https://api.payway.com.au/rest/v1/surcharges"
  }, {
    "rel" : "help",
    "href" : "https://www.payway.com.au/rest-docs/index.html#resources"
  } ]
}

To test if your server can connect to PayWay:

curl -i --basic --user "{publishableApiKey}:" https://api.payway.com.au/rest/v1

Replace {publishableApiKey} with your Publishable API Key.

If you receive the expected response, your network is working.

Troubleshooting

HTTP Response codes other than 200

See HTTP Response Codes.

curl: (60) SSL certificate problem: unable to get local issuer certificate

Your server does not trust the server TLS certificate presented by PayWay. Typically this is due to an out-dated root CA certificate bundle on your server. Download and install an updated VeriSign Class 3 Primary CA - G5 root certificate for your server.

curl: (56) Received HTTP code 407 from proxy after CONNECT

Your network has a proxy server. To test if your server can connect to PayWay through the proxy server:

curl --proxy {proxyServer} --proxy-user {proxyUsernamePassword} -i --basic --user "{publishableApiKey}:" https://api.payway.com.au/rest/v1

Your software must connect to PayWay through the proxy server.

curl: (6) Couldn’t resolve host ‘api.payway.com.au’

DNS resolution failed. You may need to authenticate with your proxy server.

Use Postman to Explore API

Postman is a HTTP client for testing RESTful web services. Use Postman when you wish to explore the PayWay REST API.

Step 1: Install Postman

  1. Install Google Chrome
  2. Open Google Chrome
  3. Use Google Chrome to install Postman

Step 2: Use API Key for Basic Auth

Postman’s Authorization Tab:

Screenshot of Postman's Authorization Tab
  1. Start Postman.
  2. Click the Authorization tab
  3. Select Basic Auth from the menu
  4. Enter your Publishable API key into the Username field
  5. Press Update request

Step 3: Create single use token

  1. In Postman’s URL bar, select POST
  2. Enter the URL https://api.payway.com.au/rest/v1/single-use-tokens
  3. Click the Body tab
  4. Select the x-www-form-urlencoded option
  5. Remove any parameters already present, then type the following parameters:
Key Value
paymentMethod creditCard
cardNumber 4564710000000004
expiryDateMonth 02
expiryDateYear 19
cvn 847
cardholderName Postman tutorial
  1. Press Send
  2. Copy the singleUseTokenId (e.g. 653fa421-0b91-4855-aef7-bf51a81a153e) from the response and save it for later use

Step 4: Create customer

  1. In Postman’s URL bar, select POST
  2. Enter the URL https://api.payway.com.au/rest/v1/customers
  3. Use your Secret API Key as the Basic Auth Username on the Authorization tab
  4. Click the Body tab
  5. Select the x-www-form-urlencoded option
  6. Remove any parameters already present, then type the following parameters:
Key Value
singleUseTokenId the value you saved earlier e.g. 653fa421-0b91-4855-aef7-bf51a81a153e
merchantId TEST
  1. Press Send

Step 5: Explore further

  1. In Postman’s URL bar, select GET
  2. Enter the URL https://api.payway.com.au/rest/v1
  3. Press Send
  4. Click links in the response to open them in a new tab in Postman. Use Postman to send requests to these resources

Use cURL to download a receipts file

Use this tutorial to automate downloading of your daily receipts file. Complete the cURL network connectivity tutorial first to ensure cURL can connect to PayWay.

To download receipts files through this REST API, you must purchase the PayWay Connect module and choose a receipt file format.

Step 1: Purchase PayWay Connect

To purchase PayWay Connect, your administrator must:

  1. Sign-in to PayWay
  2. Click on PayWay Connect under Administration in the menu
  3. Proceed with the purchase

Step 2: Choose a receipts file format

To choose a receipts files format:

  1. Sign-in to PayWay
  2. Click on Setup under Settlement Reports in the menu
  3. Choose a file format and Save

Step 3: Save API Key to file

  1. Enter the following into a text file:
    basic
    user={secretApiKey}:
    silent
    show-error
    fail
  2. Replace {secretApiKey} with your Secret API Key
  3. Save the file as payway-curl-config.txt

Step 4: Download a receipts file

To download a receipts file:

curl --config payway-curl-config.txt https://api.payway.com.au/rest/v1/receipts-files/{yyyy-MM-dd}

Replace {yyyy-MM-dd} with the settlement date.

Step 5: Download yesterday’s receipts file

Linux

To download yesterday’s receipts file using Linux:

curl --config payway-curl-config.txt https://api.payway.com.au/rest/v1/receipts-files/$(date -I --date=yesterday)

Windows Powershell

To download yesterday’s receipts file using Windows Powershell:

curl --config payway-curl-config.txt https://api.payway.com.au/rest/v1/receipts-files/$((Get-Date).AddDays(-1).ToString('yyyy-MM-dd'))

Step 6: Save a receipts file to the current folder

To save the receipts file instead of displaying it on screen:

curl -OJ --config payway-curl-config.txt https://api.payway.com.au/rest/v1/receipts-files/{yyyy-MM-dd}

Step 7: Improve your solution

You may now improve your solution by:

Other references:

Troubleshooting

curl: (22) The requested URL returned error: 404 Not Found

PayWay does not have a receipts file for the requested settlement date. PayWay creates files shortly after 03:00 Sydney time each day. The receipts file contains transactions from the previous settlement day. Receipts files are available for 220 days.

To see which receipts files are available:

  1. Sign-in to PayWay
  2. Click on Receipts Files under Settlement Reports in the menu

curl: (23) Failed writing body (0 != 1)

You have already saved the receipts file to the current folder. To save a new copy:

curl: (60) SSL certificate problem: unable to get local issuer certificate

Your server does not trust the server TLS certificate presented by PayWay. Typically this is due to an out-dated root CA certificate bundle on your server. Download and install an updated VeriSign Class 3 Primary CA - G5 root certificate for your server.

curl: (56) Received HTTP code 407 from proxy after CONNECT

Your network has a proxy server. To test if your server can connect to PayWay through the proxy server:

curl --proxy {proxyServer} --proxy-user {proxyUsernamePassword} -i --basic --user "{publishableApiKey}:" https://api.payway.com.au/rest/v1

Your software must connect to PayWay through the proxy server.

curl: (6) Couldn’t resolve host ‘api.payway.com.au’

DNS resolution failed. You may need to authenticate with your proxy server.

Use cURL to upload a payment file

Use this tutorial to upload a payment file. Complete the cURL network connectivity tutorial first to ensure cURL can connect to PayWay.

To upload a payment file, you must purchase the PayWay Recurring Billing and Customer Vault module or the PayWay Batch module.

Step 1: Purchase required module

To purchase PayWay Recurring Billing and Customer Vault or PayWay Batch, contact us.

Step 2: Generate a Payment File

Your software must generate a file in one of the payment file formats. Each file must have a unique name.

In this tutorial, we assume the file is called example.dat.

Step 3: Save API Key to file

  1. Enter the following into a text file:
    basic
    user={secretApiKey}:
    silent
    show-error
    fail
  2. Replace {secretApiKey} with your Secret API Key
  3. Save the file as payway-curl-config.txt

Step 4: Upload a Payment File

To upload a payment file:

curl --config payway-curl-config.txt -F "file=@example.dat" https://api.payway.com.au/rest/v1/payment-files

Step 5: Improve your solution

You may now improve your solution by:

Resources

PayWay allows you to store credit card and bank account details against your customers. You can process payment transactions using the stored details.

You can open virtual accounts for customers who pay you by direct credit/pay anyone. Each of your customers uses a different virtual account. When a payment is sent to a virtual account, PayWay matches the payment to that customer.

Upload a payment file to process transactions in bulk.

Single use tokens are used to avoid processing credit card details on your server.

Your merchants and your bank accounts are used for transaction processing and settlement.

Custom fields allow you to store extra information against each customer.

PayWay can calculate and apply surcharges.

Download receipts files containing a machine readable list of payments received.

The base URL of the PayWay REST API is https://api.payway.com.au/rest/v1/.

Root

This resource is the top level of the REST API.

To test your network connectivity and API key is working correctly, send a GET to this resource.

Get Root Resource

GET /

You may access this resource with either your secret or publishable API key.

Model

Field Notes
clientNumber Uniquely identifies your PayWay facility. Issued by us.
clientName The name of your business
keyName The name of the API key you sent

The response includes links to top level resources.

Transactions

Transactions are payments, refunds and pre-authorisations. A pre-authorisation reserves funds from your customer’s credit card limit.

You can:

To get all transactions processed on a day, see Receipts Files.

Besides this API, PayWay also has other ways to process payments.

Process a Payment

To process a payment:

POST /transactions

You must send:

Field Notes
customerNumber This customer’s credit card or bank account will be used to process the payment.
transactionType payment
principalAmount The amount of the payment before any surcharge is added.
currency aud
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.

Merchant Id / Your Bank Account

PayWay will process the payment using the merchant or settlement bank account from the customer’s payment setup. To use a different settlement bank account or merchant, send:

Field Notes
merchantId If the customer is paying by credit card, this merchant will be used for payment processing and settlement. Ignored otherwise.
bankAccountId If the customer is paying by bank account direct debit, this account will be used for payment processing and settlement. Ignored otherwise.

Avoid Duplicate Payments

To avoid processing duplicate payments:

Void a Transaction

To void a transaction:

POST /transactions/{transactionId}/void

Do not send any fields.

If you void a transaction, it will not appear on your customer’s statement or form part of your settlement total. To determine if a transaction can be voided, get the transaction details and use the isVoidable field.

Refund a Payment

To refund a payment:

POST /transactions

You must send:

Field Notes
transactionType refund
parentTransactionId The transactionId of the payment to be refunded.
principalAmount The amount of the refund before any surcharge is added. Send a positive value.
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.

To avoid processing duplicate refunds, send a unique Idempotency-Key header and handle errors as described above.

To determine if a payment can be refunded, get the transaction details and use the isRefundable field. The refund will credit the bank account or credit card used on the payment. You can never refund more than the payment amount.

Search Transactions

To search for transactions:

GET /transactions/search-customer?customerNumber={customerNumber}

GET /transactions/search-receipt?receiptNumber={receiptNumber}

GET /transactions/search-order?orderNumber={orderNumber}

These are paginated resources. Most recent transactions are first.

The following fields are returned for each transaction:

Field Notes
transactionId Uniquely identifies a transaction
receiptNumber Receipt number to display to customers
status approved, approved*, pending, declined, voided or suspended. See transaction status.
transactionType payment, refund or preAuth
customerNumber
orderNumber A reference number for this transaction, generated by you.
currency aud
paymentAmount Total amount of payment, including any surcharge. Negative for a refund.
settlementDate The day on which this transaction was considered to have been processed
declinedDate The day on which this transaction was considered to have been declined.

Get Transaction Details

To get details of a transaction:

GET /transactions/{transactionId}

Transactions Model

Example transaction

{
  "transactionId" : 1179985404,
  "receiptNumber" : "1179985404",
  "status" : "approved",
  "responseCode" : "11",
  "responseText" : "Approved VIP",
  "transactionType" : "payment",
  "customerNumber" : "1",
  "customerName" : "Po & Sons Pty Ltd",
  "customerEmail" : "henry@example.net",
  "currency" : "aud",
  "principalAmount" : 100.00,
  "surchargeAmount" : 1.00,
  "paymentAmount" : 101.00,
  "paymentMethod" : "creditCard",
  "creditCard" : {
    "cardNumber" : "456471...004",
    "expiryDateMonth" : "02",
    "expiryDateYear" : "19",
    "cardScheme" : "visa",
    "cardholderName" : "Po & Sons Pty Ltd"
  },
  "merchant" : {
    "merchantId": "4638116",
    "merchantName": "MEGS BEAUTY AND NAILS",
    "settlementBsb": "133-605",
    "settlementAccountNumber": "172174",
    "surchargeBsb": "133-606",
    "surchargeAccountNumber": "172131"
  },
  "transactionDateTime" : "12 Jun 2015 18:22 AEST",
  "user" : "BILLC786",
  "settlementDate" : "13 Jun 2015",
  "isVoidable" : true,
  "isRefundable": false
}
<transaction>
  <transactionId>1179985404</transactionId>
  <receiptNumber>1179985404</receiptNumber>
  <status>approved</status>
  <responseCode>11</responseCode>
  <responseText>Approved VIP</responseText>
  <transactionType>payment</transactionType>
  <customerNumber>1</customerNumber>
  <customerName>Po &amp; Sons Pty Ltd</customerName>
  <customerEmail>henry@example.net</customerEmail>
  <currency>aud</currency>
  <principalAmount>100.00</principalAmount>
  <surchargeAmount>1.00</surchargeAmount>
  <paymentAmount>101.00</paymentAmount>
  <paymentMethod>creditCard</paymentMethod>
  <creditCard>
    <cardNumber>456471...004</cardNumber>
    <expiryDateMonth>02</expiryDateMonth>
    <expiryDateYear>19</expiryDateYear>
    <cardScheme>visa</cardScheme>
    <cardholderName>Po &amp; Sons Pty Ltd</cardholderName>
  </creditCard>
  <merchant>
    <merchantId>4638116</merchantId>
    <merchantName>MEGS BEAUTY AND NAILS</merchantName>
    <settlementBsb>133-605</settlementBsb>
    <settlementAccountNumber>172174</settlementAccountNumber>
    <surchargeBsb>133-606</surchargeBsb>
    <surchargeAccountNumber>172131</surchargeAccountNumber>
  </merchant>
  <transactionDateTime>12 Jun 2015 18:22 AEST</transactionDateTime>
  <user>BILLC786</user>
  <settlementDate>13 Jun 2015</settlementDate>
  <isVoidable>true</isVoidable>
  <isRefundable>false</isRefundable>
</transaction>
Field Notes
transactionId Uniquely identifies a transaction.
receiptNumber Receipt number to display to customers (not always same as transactionId).
status approved, approved*, pending, declined, voided or suspended. See transaction status.
responseCode Reason code for the status.
responseText Reason description for the status.
transactionType payment, refund or preAuth
customerNumber Customer to which this payment belongs.
customerName
customerEmail
bpayRef A reference number used by this customer when paying by BPAY.
orderNumber A reference number for this transaction, generated by you.
customerBankReference For a directCredit, the reference entered by the customer when sending payment
currency aud
principalAmount Amount before any surcharge added. Negative for a refund.
surchargeAmount Amount of surcharge. See surcharges.
paymentAmount Total amount of transaction. Principal amount plus surcharge.
paymentMethod creditCard, bankAccount, directCredit, australiaPost, bpay, westpacBranch, remittanceProcessingService or payPal.
creditCard If creditCard, customer’s credit card.
merchant If creditCard, your merchant facility.
bankAccount If bankAccount, customer’s direct debit bank account.
virtualAccount If directCredit, the virtual account which the customer credited.
australiaPost If australiaPost, details of the Australia Post payment.
bpay If bpay, details of the BPAY payment.
yourBankAccount If bankAccount, directCredit, bpay, australiaPost, westpacBranch or remittanceProcessingService your settlement bank account.
customerPayPalAccount If payPal, customer’s PayPal account.
yourPayPalAccount If payPal, your PayPal account.
transactionDateTime Date and time (if known) when transaction processing was initiated.
user The user who processed the payment manually.
settlementDate The day on which this transaction was considered to have been processed.
declinedDate The day on which this transaction was considered to have been declined.
parentTransaction If a refund, the original payment. If a payment, the original preAuth.
customFields Values for any custom fields. See Transaction Custom Fields.
isVoidable If true, this transaction may be voided. See Void a Transaction.
isRefundable If true, this payment may be refunded. See Refund a Payment.

Transaction Status

Status Meaning
approved A successful transaction.
approved* A successful transaction during period when it may be declined or dishonoured.
pending Currently processing.
declined An unsuccessful transaction. See responseCode and responseText for more.
voided Originally approved, but then cancelled prior to settlement. Does not appear on your customer’s statement or form part of your settlement total.
suspended A payment declined by Fraud Guard before processing.

Note:

Credit Card

These fields are returned under the creditCard field:

Field Notes
cardNumber Masked credit card number.
expiryDateMonth Two digit expiry month.
expiryDateYear Two digit expiry year.
cardScheme visa, mastercard, amex, diners, eftpos or jcb.
cardholderName The name printed on the card.

Customer Bank Account

Example customer bankAccount

{
  "bsb" : "000-000",
  "accountNumber" : "123123",
  "accountName" : "Jenny Nguyen"
}
<bankAccount>
  <bsb>000-000</bsb>
  <accountNumber>123123</accountNumber>
  <accountName>Jenny Nguyen</accountName>
</bankAccount>

These fields are returned under the bankAccount field:

Field Notes
bsb The bank-state-branch holding their account.
accountNumber The account number at that branch.
accountName Name of account holder.

Virtual Account

A virtual account is used to accept direct credit payments from a customer.

Example customer virtualAccount

{
  "bsb": "037-889",
  "accountNumber": "80000000"
}
<virtualAccount>
  <bsb>037-889</bsb>
  <accountNumber>80000000</accountNumber>
</virtualAccount>

These fields are returned under the virtualAccount field:

Field Notes
bsb The bank-state-branch holding the virtual account
accountNumber The virtual account number

Customer PayPal Account

These fields are returned under the customerPayPalAccount field:

Field Notes
payPalEmail Email address your customer used to register with PayPal
payPalName Payer name

Australia Post

This field is returned under the australiaPost field:

Field Notes
cheque true if paid by cheque

BPAY

This field is returned under the bpay field:

Field Notes
bank A code for the bank used by the customer

Transaction Custom Fields

Example customFields

{
  "data" : [ {
    "customFieldId" : 1,
    "fieldName" : "Campaign Id",
    "fieldValue" : "489590",
    "required" : false,
    "hidden" : true
  }, {
    "customFieldId" : 2,
    "fieldName" : "Membership Type",
    "fieldValue" : "social",
    "help" : "e.g. junior, senior, social",
    "required" : false,
    "hidden" : false
  } ]
}
<customFields>
 <data>
  <customField>
    <customFieldId>1</customFieldId>
    <fieldName>Campaign Id</fieldName>
    <fieldValue>489590</fieldValue>
    <required>false</required>
    <hidden>true</hidden>
  </customField>
 <customField>
  <customFieldId>2</customFieldId>
    <fieldName>Membership Type</fieldName>
    <fieldValue>social</fieldValue>
    <help>e.g. junior, senior, social</help>
    <required>false</required>
    <hidden>false</hidden>
  </customField>
  </data>
</customFields>

customFields contains a list of the transaction’s custom fields.

These fields are returned for each customField:

Field Notes
customFieldId A number from 1 to 4
fieldName Name for the custom field
fieldValue Value for the custom field for this transaction
required true or false. If true, this field was mandatory when this transaction was created.
hidden true or false. If true, this field was hidden from customers (e.g. in receipt emails).
links parent link to the master configuration of the custom field (not shown in examples).

When the master list of custom fields is modified, existing transactions do not change.

Customers

PayWay Recurring Billing and Customer Vault stores your customer’s credit card or bank account details. You can process payments using the stored details. Your PCI-DSS compliance costs are lower when your server does not store or process credit card details.

PayWay Match allows you to open virtual accounts for customers who pay you by direct credit/pay anyone. When a customer pays you by direct credit, PayWay matches the payment to the customer.

Store Credit Card for new Customer

For step by step instructions, see Tokenisation from Web Page tutorial.

To store a credit card or bank account in the customer vault:

POST /customers to have PayWay generate the customer number

PUT /customers/{customerNumber} to use your own customer number

Send these fields:

Field Notes
singleUseTokenId A token issued by PayWay which holds credit card or bank account details. See single use tokens.
merchantId Required if token contains a credit card. Ignored otherwise.
bankAccountId Required if token contains a bank account. Ignored otherwise.

In the same request, you may also send:

You should send an Idempotency-Key to ensure customers are not duplicated if there is a network problem.

The response is the full customer model.

Open Virtual Account for new Customer

To create a customer and open a virtual account:

POST /customers to have PayWay generate the customer number

PUT /customers/{customerNumber} to use your own customer number

Send these fields:

Field Notes
virtualAccountStatus open
bankAccountId Your bank account used for settlement

In the same request, you may also send:

The response is the full customer model, including the virtual account.

You should send an Idempotency-Key to ensure customers are not duplicated if there is a network problem.

List Customers

To list customers:

GET /customers

This is a paginated resource.

The following fields are returned for each customer:

Field Notes
customerNumber Unique identifier for a customer.
customerName Name of business or individual.

Get Customer Details

To get the full customer model:

GET /customers/{customerNumber}

Alternatively, use these URLs to get only that part of the customer model:

GET /customers/{customerNumber}/payment-setup

GET /customers/{customerNumber}/schedule

GET /customers/{customerNumber}/virtual-account

GET /customers/{customerNumber}/contact

GET /customers/{customerNumber}/custom-fields

GET /customers/{customerNumber}/notes

Schedule Regular Payments

PayWay can automatically process payments according to a regular schedule.

To set a new schedule for a customer:

PUT /customers/{customerNumber}/schedule

Send the fields listed in Customer Schedule.

The new schedule replaces any previous schedule.

If a scheduled payment is due, PayWay will process it before responding. To get details of the payment follow the transaction link in the response.

Stop Regular Schedule

To stop any more automatic payments being processed by PayWay:

DELETE /customers/{customerNumber}/schedule

You may continue to process individual payments using the stored payment setup.

Stop All Payments

To stop any new payments using the stored payment details:

PATCH /customers/{customerNumber}/payment-setup

Send this field:

Field Notes
stopped true

If the customer has a schedule, it is stopped.

Update Credit Card or Direct Debit Bank Account

To store a new credit card or direct debit bank account for an existing customer:

PUT /customers/{customerNumber}/payment-setup

Send the fields listed in Customer Payment Setup.

Update Contact Details

To update customer name, contact details and email preference:

PUT /customers/{customerNumber}/contact

Send name, address, phone number and email preference fields.

Open Virtual Account

To open a virtual account for an existing customer:

PUT /customers/{customerNumber}/virtual-account

Send these fields:

Field Notes
virtualAccountStatus open
bankAccountId Your bank account for settlement

The response is the new virtual account.

Close Virtual Account

To close a virtual account:

PATCH /customers/{customerNumber}/virtual-account

Send this field:

Field Notes
virtualAccountStatus closed

Update Settlement for Virtual Account

To update the settlement account used for a virtual account:

PATCH /customers/{customerNumber}/virtual-account

Send this field:

Field Notes
bankAccountId Your bank account for settlement

Update Custom Fields

To update custom fields:

PUT /customers/{customerNumber}/custom-fields

Send custom field values fields.

Update Notes

To update notes:

PUT /customers/{customerNumber}/notes

Send a single notes field.

To remove the notes:

DELETE /customers/{customerNumber}/notes

Calculate Surcharge

Example surcharge calculation response

{
  "principalAmount" : 100.00,
  "surchargeAmount" : 1.11,
  "paymentAmount" : 101.11,
  "currencyCode" : "aud"
}
<customerSurcharge>
  <principalAmount>100.00</principalAmount>
  <surchargeAmount>1.11</surchargeAmount>
  <paymentAmount>101.11</paymentAmount>
  <currencyCode>aud</currencyCode>
</customerSurcharge>

To calculate the surcharge payable by a customer:

GET /customers/{customerNumber}/surcharge?principalAmount={principalAmount}

The following fields are returned:

Field Notes
principalAmount The amount before any surcharge is added. As passed in query parameter.
surchargeAmount Amount of surcharge payable by this customer, based on their payment setup.
paymentAmount Total amount of payment, including the surcharge.
currencyCode aud

See surcharges.

Delete Customer

DELETE /customers/{customerNumber}

A customer can not be deleted if they:

Customer Model

A customer in PayWay is uniquely identified by a customer number.

The customer model consists of:

Example customer response

{
  "customerNumber" : "98",
  "paymentSetup" : {
    "paymentMethod" : "creditCard",
    "stopped" : false,
    "creditCard" : {
      "cardNumber" : "376000...006",
      "expiryDateMonth" : "06",
      "expiryDateYear" : "20",
      "cardScheme" : "amex",
      "cardholderName" : "Rebecca Turing",
      "surchargePercentage" : 1.543
    },
    "merchant" : {
      "merchantId": "4638116",
      "merchantName": "MEGS BEAUTY AND NAILS",
      "settlementBsb": "133-605",
      "settlementAccountNumber": "172174",
      "surchargeBsb": "133-606",
      "surchargeAccountNumber": "172131"
    }
  },
  "contact" : {
    "customerName" : "Rebecca Turing",
    "emailAddress" : "bect@example.net",
    "sendEmailReceipts" : true,
    "phoneNumber" : "04 9999 8888",
    "address" : {
      "street1" : "12 Test St",
      "street2" : null,
      "cityName" : "Wombat",
      "state" : "NSW",
      "postalCode" : "2587"
    }
  },
  "customFields" : {
    "customField1" : "Senior"
  },
  "notes" : {
    "notes" : "Example notes"
  } ,
  "virtualAccount" : {
    "bsb" : "037-889",
    "accountNumber" : "80000000",
    "virtualAccountStatus" : "open",
    "yourBankAccount" : {  
      "bankAccountId": "133605172174A",
      "remitterName": "MEGS BEAUTY AND NAILS",
      "accountName": "MEGAN ZUCKER",
      "settlementBsb": "133-605",
      "settlementAccountNumber": "172174"
    }
  }
}
<customer>
  <customerNumber>98</customerNumber>
  <paymentSetup>
    <paymentMethod>creditCard</paymentMethod>
    <stopped>false</stopped>
    <creditCard>
      <cardNumber>376000...006</cardNumber>
      <expiryDateMonth>06</expiryDateMonth>
      <expiryDateYear>20</expiryDateYear>
      <cardScheme>amex</cardScheme>
      <cardholderName>Rebecca Turing</cardholderName>
      <surchargePercentage>1.543</surchargePercentage>
    </creditCard>
    <merchant>
      <merchantId>4638116</merchantId>
      <merchantName>MEGS BEAUTY AND NAILS</merchantName>
      <settlementBsb>133-605</settlementBsb>
      <settlementAccountNumber>172174</settlementAccountNumber>
      <surchargeBsb>133-606</surchargeBsb>
      <surchargeAccountNumber>172131</surchargeAccountNumber>
    </merchant>
  </paymentSetup>
  <contact>
    <customerName>Rebecca Turing</customerName>
    <emailAddress>bect@example.net</emailAddress>
    <sendEmailReceipts>true</sendEmailReceipts>
    <phoneNumber>04 9999 8888</phoneNumber>
    <address>
      <street1>12 Test St</street1>
      <street2/>
      <cityName>Wombat</cityName>
      <state>NSW</state>
      <postalCode>2587</postalCode>
    </address>
  </contact>
  <customFields>
    <customField1>Senior</customField1>
  </customFields>
  <notes>
    <notes>Example notes</notes>
  </notes>
  <virtualAccount>
    <bsb>037-889</bsb>
    <accountNumber>80000000</accountNumber>
    <virtualAccountStatus>open</virtualAccountStatus>
    <yourBankAccount>
      <bankAccountId>133605172174A</bankAccountId>
      <remitterName>MEGS BEAUTY AND NAILS</remitterName>
      <accountName>MEGAN ZUCKER</accountName>
      <settlementBsb>133-605</settlementBsb>
      <settlementAccountNumber>172174</settlementAccountNumber>
    </yourBankAccount>    
  </virtualAccount>
</customer>
Field Notes
customerNumber Up to 20 letters and digits. Case insensitive. Leading zeroes ignored if entirely numeric. Uniquely identifies a customer.

The customer may be paying by either credit card or bank account direct debit.

The customer’s payment details include their credit card or bank account details, which merchant id or bank account should be used for transaction processing and the surcharge payable on transactions.

Customer Payment Setup

To store credit card or bank account details, send these fields:

Field Notes
singleUseTokenId A token issued by PayWay which holds credit card or bank account details. See single use tokens.
merchantId Required if token contains a credit card. Ignored otherwise.
bankAccountId Required if token contains a bank account. Ignored otherwise.

These fields are returned in responses when the customer is paying by credit card:

Field Notes
paymentMethod creditCard
stopped true if payments have been stopped, false if these details can be used
cardNumber Masked credit card number.
expiryDateMonth Two digit expiry month.
expiryDateYear Two digit expiry year.
cardScheme visa, mastercard, amex, diners, eftpos or jcb.
cardholderName The name printed on the card.
surchargePercentage The percentage to be applied to principal amount to calculate payment amount.
merchant The merchant used for transaction processing and settlement.

These fields are returned when the customer is paying by bank account direct debit:

Field Notes
paymentMethod bankAccount
stopped true if payments have been stopped, false if these details can be used
bsb The bank-state-branch holding their account.
accountNumber The account number at that branch.
accountName Name of account holder.
surchargeAmount Dollar amount added to principal amount to calculate payment amount.
yourBankAccount The bank account used for transaction processing and settlement.

Customer Contact Details

The customer’s contact details:

Field Notes
customerName Name of business or individual.
emailAddress
sendEmailReceipts true or false. If true email receipts are automatically sent for each transaction.
phoneNumber
street1
street2
cityName
state ACT, NSW, NT, QLD, SA, TAS, VIC or WA.
postalCode A valid four digit Australian post code.

Customer Custom Fields

The customer may have values for custom fields:

Field Notes
customField1 Value for your first custom field.
customField2 Value for your second custom field.
customField3 Value for your third custom field.
customField4 Value for your fourth custom field.

Use custom fields to store additional information about your customer. You must first setup a master list of custom fields in your PayWay facility.

Notes

A free text field allowing you to comment on the customer.

Field Notes
notes Up to 4000 ASCII characters of free text

Customer Schedule

Example schedule response with 12 payments

{
  "frequency" : "monthly",
  "nextPaymentDate" : "31 Jul 2015",
  "numberOfPaymentsRemaining" : 12,

  "nextPrincipalAmount" : 100.00,
  "nextSurchargeAmount" : 1.00,
  "nextPaymentAmount" : 101.00,

  "regularPrincipalAmount" : 200.00,
  "regularSurchargeAmount" : 2.00,
  "regularPaymentAmount" : 202.00,

  "finalPrincipalAmount" : 300.00,
  "finalSurchargeAmount" : 3.00,
  "finalPaymentAmount" : 303.00
}
<schedule>
  <frequency>monthly</frequency>
  <nextPaymentDate>31 Jul 2015</nextPaymentDate>
  <numberOfPaymentsRemaining>12</numberOfPaymentsRemaining>

  <nextPrincipalAmount>100.00</nextPrincipalAmount>
  <nextSurchargeAmount>1.00</nextSurchargeAmount>
  <nextPaymentAmount>101.00</nextPaymentAmount>

  <regularPrincipalAmount>200.00</regularPrincipalAmount>
  <regularSurchargeAmount>2.00</regularSurchargeAmount>
  <regularPaymentAmount>202.00</regularPaymentAmount>

  <finalPrincipalAmount>300.00</finalPrincipalAmount>
  <finalSurchargeAmount>3.00</finalSurchargeAmount>
  <finalPaymentAmount>303.00</finalPaymentAmount>
</schedule>

PayWay can process payments according to a regular schedule. The customer’s stored credit card or bank account and surcharge rate is used.

To create a schedule that continues you stop it, send these fields:

Field Notes
frequency weekly, fortnightly, monthly, quarterly, six-monthly, yearly.
nextPaymentDate The date on which the next payment will be collected.
nextPrincipalAmount Different amount for the next payment (optional).
regularPrincipalAmount Usual amount for payments.

To create a schedule that stops after a fixed number of payments, also send:

Field Notes
numberOfPaymentsRemaining Number of payments.
finalPrincipalAmount Different amount for the very last payment (optional).

If you have enabled surcharges, PayWay will calculate and add surcharges to the amounts.

If a scheduled payment is due, PayWay will process it before responding. To get details of the payment follow the transaction link in the response.

These fields are returned:

Field Notes
frequency weekly, fortnightly, monthly, quarterly, six-monthly, yearly.
nextPaymentDate When the next automatic payment will be processed.
nextPrincipalAmount Amount of next payment before surcharge is added.
nextSurchargeAmount Surcharge added to next payment.
nextPaymentAmount Amount of the next payment, including any surcharge.
regularPrincipalAmount Regular amount for each payment before surchage is added.
regularSurchargeAmount Surcharge added to regular amount for each payment.
regularPaymentAmount Amount of each regular payment, including any surcharge.

If a fixed number of payments, these fields are also returned:

Field Notes
numberOfPaymentsRemaining The total number of payments yet to be collected.
finalPrincipalAmount Amount of the very last payment before surchage is added.
finalSurchargeAmount Surcharge added to the very last payment.
finalPaymentAmount Amount of very last payment, including any surcharge.

On each payment date, PayWay processes a payment and updates the schedule with the next payment date.

For a fixed schedule, numberOfPaymentRemaining counts down to zero, and then the schedule is deleted.

Virtual Account

An account used to accept direct credit payments from the customer.

These fields are returned:

Field Notes
bsb BSB for customer to direct credit
accountNumber Account number for customer to direct credit
virtualAccountStatus open, suspended, closed
yourBankAccount Your bank account used for settlement

All virtual accounts belong to a customer. Each customer may only have one virtual account.

Virtual Account Status
Status Notes
open Payments made to the virtual account will settle to yourBankAccount.
suspended Payments made to the account will be returned to the customer. Contact us.
closed Payments made to the account will be returned to the customer

Single Use Tokens

Single use tokens allow you to avoid sending credit card or bank account details to your server.

Tokens are temporary. To store a credit card or bank account, use a token to create a customer in the customer vault.

Tokenise from Web Page

Screenshot of credit card form

For step by step instructions, see the Tokenisation from Web Page tutorial.

To display a credit card input form on your website, include creditCardForm.js and a button in the <body>:

<script type="text/javascript" src="https://api.payway.com.au/rest/v1/creditCardForm.js?apiKey={publishableApiKey}&redirectUrl={redirectUrl}"></script>

<button id="payway-creditcard-submit" onclick="paywayCreditCardSubmit()" disabled="true">Register</button>

Screenshot of bank account form

To display a bank account input form on your website, include bankAccountForm.js and a button in the <body>:

<script type="text/javascript" src="https://api.payway.com.au/rest/v1/bankAccountForm.js?apiKey={publishableApiKey}&redirectUrl={redirectUrl}"></script>

<button id="payway-bankaccount-submit" onclick="paywayBankAccountSubmit()" disabled="true">Register</button>

When the form is submitted, PayWay creates a single use token and redirects to {redirectUrl} with a singleUseTokenId parameter.

GET {redirectUrl}?singleUseTokenId={id}

Query Parameters

You must provide these query parameters in the src attribute:

Field Notes
apiKey Your publishable API key.
redirectUrl URL on your server which accepts the single use token.

You may optionally provide these query parameters in the src attribute:

Field Notes
cvnRequired false if you do not wish to collect the card verification number (security code)

To pass additional information to your server along with the single use token, use a redirectUrl with a query string. To use query strings:

Setup API Keys and Redirect URL Whitelist

To view your API keys and setup your whitelist of redirect URLs:

  1. Sign-in to PayWay
  2. Click on REST API in the menu

Styling

You can style the credit card form using these CSS selectors:

CSS Selector Notes
div.payway-card Entire form
.payway-card label, .payway-card legend Labels
.payway-card input, .payway-card select Input fields
.payway-card button.payway-csc-help Help Button

You can style the bank account form using these CSS selectors:

CSS Selector Notes
div.payway-account Entire form
.payway-account label Labels
.payway-account input Input fields

Tokenise a Credit Card

To tokenise a credit card from fully PCI-DSS compliant software:

POST /single-use-tokens

You must use your publishable API key.

Send these fields:

Field Notes
paymentMethod creditCard
cardNumber Digits printed on the card
cardholderName Name printed on the card
cvn Card Verification Number. Also known as Security Code, CVV2 and CVC2. The three or four digit security code.
expiryDateMonth Two digit expiry month
expiryDateYear Two digit expiry year

Tokenise a Bank Account

To tokenise a direct debit bank account:-

POST /single-use-tokens

You must use your publishable API key.

Send these fields:

Field Notes
paymentMethod bankAccount
bsb The bank-state-branch holding their account.
accountNumber The account number at that branch.
accountName Name of account holder.

Single Use Token Response

Example singleUseToken response

{
  "singleUseTokenId" : "2bcec36f-7b02-43db-b3ec-bfb65acfe272"
}
<singleUseToken>
  <singleUseTokenId>2bcec36f-7b02-43db-b3ec-bfb65acfe272</singleUseTokenId>
</singleUseToken>

If you send valid fields:

Alternatively, you can update a customer in the vault.

If you send invalid fields, you will receive a 422 Unprocessable Entity response.

Receipts Files

Receipts files contain a machine readable list of payments received.

PayWay can generate receipts files suitable for upload into various accounting software packages. For file specifications, see the PayWay User Guide on the downloads page. We recommend the RECall File format.

Receipts files include payments processed through all PayWay modules. PayWay creates files shortly after 03:00 Sydney time each day. The receipts file contains transactions from the previous settlement day. Receipts files are available for 220 days.

Download Receipts Files

For step by step instructions for downloading a receipts file using cURL, see the Use cURL to download a receipts file tutorial.

To download a receipts file:

GET /receipts-files/{yyyy-mm-dd}

List Receipts Files

To list receipts files:

GET /receipts-files

This is a paginated resource. Most recent files are first.

The following fields are returned for each file:

Field Notes
fileName This depends on which receipts file format has been selected.
settlementDate The day on which the transactions were processed.
amount Total value of the file

Follow the self link to download an individual file.

Payment Files

Payment files contain payments that you want PayWay to process.

To use this feature:

  1. Generate a file in one of the Payment File Formats.
  2. Upload the file
  3. Get the status of the file
  4. If checking, PayWay is checking the format of the file. Wait a minute and then get the status of the file again
  5. If error, correct the errors and upload the file again
  6. If scheduled, wait until your requested settlement date
  7. If processing, PayWay is processing transactions in the file. Wait a minute and then get the status of the file again
  8. If processed, update your system with the status of individual payments

Upload a Payment File

To upload a payment file:

POST /payment-files

You must:

201 CREATED means the file has been stored. Next, PayWay will check the format of the file and then process transactions. You must check the status of the file.

409 CONFLICT means that the server already has a file with the same name.

Get Payment File

To get the status of a payment file:

GET /payment-files/{fileName}

The following fields are returned:

Field Notes
fileName Your name for the file
status See below

Status Notes
checking Checking the file for format errors. Get the status again in one minute.
error Unable to understand the file format. No transactions will be processed. See Get File Errors
awaiting-auth A payment file uploaded through the PayWay website is awaiting user authorisation. Files uploaded through this API do not require user authorisation
scheduled File is held until the requested settlement date
processing No errors in the file. Payments in the file are being processed
processed Transactions have been processed. See Get File Transactions
voided Transactions in the file have been cancelled through the PayWay website

Get File Errors

This resource is only valid when the file status is error.

To list the errors in a payment file:

GET /payment-files/{fileName}/errors

The following fields are returned for each error:

Field Notes
fieldName The location of the error within the file
message The error message
fieldValue The value in the file

Get File Transactions

This resource is only valid when the file status is processed.

To get the transactions in a payment file:

GET /payment-files/{fileName}/transactions

The response is the same as returned for a transaction search.

The transaction status allows you to determine if transactions were declined.

This is a paginated resource.

Download Transaction Report

These resources are only valid when the file status is processed. Use these resources if your software is compatible with these file formats.

To download transaction reports for a payment file in PayWay CSV format:

GET /payment-files/{fileName}/csv

To download a declined transaction report for a payment file in Westpac MTS rejects format:

GET /payment-files/{fileName}/mts-rejects-report

To download transaction reports for a payment file in St.George Internet Payment Gateway format:

GET /payment-files/{fileName}/ipg-transaction-report

List Payment Files

To list payment files:

GET /payment-files

This is a paginated resource. Most recently uploaded files are first.

The following fields are returned for each file:

Field Notes
fileName Your name for the file
status See payment file status notes

Payment File Formats

Payment files contain payments that you want PayWay to process.

PayWay Recurring Billing and Customer Vault

If you use this module, the file contains the customer number for each payment. PayWay uses the customer’s stored payment setup to process payments.

The file format is a CSV file.

The header row:

Column Value
A Always “Recurring Billing and Customer Vault Upload”
B Always “v1.00”
C Earliest settlement date in d Mmm YYYY format. e.g. 14 Feb 2016

Detail rows:

Column Value
A The customer number
B Optional customer name. This is not checked
C Payment amount in dollars and cents
D Optional. Your orderNumber for this payment

Do not include any further columns.

PayWay Batch

If you are using this module, the file contains the full credit card details.

You can process payments by sending a file in one of these formats:

Merchants

To process credit card transactions, you must open a merchant facility. You can do this when you purchase PayWay.

To change details of your merchant facility or add a merchant facility, contact us.

Settlement is the process of paying you for transactions which have been processed. Each merchant facility has its own name and settlement details. Use extra merchant facilities if you have more than one trading name or settlement account.

There is one test merchant facility in a test PayWay facility.

List Merchants

To list all the merchants in your PayWay facility:

GET /merchants

This is a paginated resource.

Get a Merchant

To get details of a single merchant in your PayWay facility:

GET /merchants/{merchantId}

Merchant Model

Example Merchant with surcharge settled separately

{
  "merchantId": "4638116",
  "merchantName": "MEGS BEAUTY AND NAILS",
  "settlementBsb": "133-605",
  "settlementAccountNumber": "172174",
  "surchargeBsb": "133-606",
  "surchargeAccountNumber": "172131"
}
<merchant>
  <merchantId>4638116</merchantId>
  <merchantName>MEGS BEAUTY AND NAILS</merchantName>
  <settlementBsb>133-605</settlementBsb>
  <settlementAccountNumber>172174</settlementAccountNumber>
  <surchargeBsb>133-606</surchargeBsb>
  <surchargeAccountNumber>172131</surchargeAccountNumber>
</merchant>
Field Notes
merchantId Uniquely identifies a merchant facility. Issued by us.
merchantName
settlementBsb The BSB of your settlement bank account
settlementAccountNumber The account number of your settlement bank account
surchargeBsb If surcharges are settled separately, the BSB for your surcharge settlement account
surchargeAccountNumber If surcharges are settled separately, the account number for your surcharge settlement account

A TEST merchant does not have a settlement account.

Your Bank Accounts

To process bank account direct debit transactions, you must have a bank account linked to your facility. You can do this when you purchase PayWay.

To change your linked bank accounts or add an account, contact us.

Settlement is the process of paying you for transactions which have been processed. Each of your bank accounts has its own name and settlement details. Use extra bank accounts if you have more than one trading name or settlement account.

There is one test bank account in a test PayWay facility.

List Your Bank Accounts

To list all of your settlement bank accounts:

GET /your-bank-accounts

This is a paginated resource.

Get one of Your Bank Accounts

To get details of a single one of your bank accounts:

GET /your-bank-accounts/{bankAccountId}

Your Bank Account Model

Example Your Bank Account with surcharge settled separately

{
  "bankAccountId": "133605172174A",
  "remitterName": "MEGS BEAUTY AND NAILS",
  "accountName": "MEGAN ZUCKER",
  "settlementBsb": "133-605",
  "settlementAccountNumber": "172174",
  "surchargeBsb": "133-606",
  "surchargeAccountNumber": "172131"
}
<yourBankAccount>
  <bankAccountId>133605172174A</bankAccountId>
  <remitterName>MEGS BEAUTY AND NAILS</remitterName>
  <accountName>MEGAN ZUCKER</accountName>
  <settlementBsb>133-605</settlementBsb>
  <settlementAccountNumber>172174</settlementAccountNumber>
  <surchargeBsb>133-606</surchargeBsb>
  <surchargeAccountNumber>172131</surchargeAccountNumber>
</yourBankAccount>
Field Notes
bankAccountId Uniquely identifies your bank account.
remitterName Trading Name of your business. This appears on your customer’s bank statement.
accountName Name used to open your bank account.
directEntryUserId A unique direct entry user identification number, issued by us. If blank, transaction are processed under a shared user id.
settlementBsb The BSB of your settlement bank account
settlementAccountNumber The account number of your settlement bank account
surchargeBsb If surcharges are settled separately, the BSB for your surcharge settlement account
surchargeAccountNumber If surcharges are settled separately, the account number for your surcharge settlement account

To change the remitterName:

  1. Sign-in to PayWay
  2. Click on Administration in the menu
  3. Click on Bank Accounts

Your PayPal Accounts

To process PayPal transactions with the PayWay Net module, you must link a PayPal account to your facility. PayPal can not be used with the PayWay Recurring Billing and Customer Vault module.

To link a PayPal account:

  1. Sign-in to PayWay
  2. Click on Administration in the menu
  3. Click on PayPal Accounts

List Your PayPal Accounts

To list all of your settlement bank accounts in your PayWay facility:

GET /your-paypal

This is a paginated resource.

Get a PayPal Account

To get details of a single one of your PayPal accounts:

GET /your-paypal/{payPalEmail}

Your PayPal Accounts Model

Example PayPal account

{
  "payPalEmail" : "test@example.com",
  "payPalName" : "Test PayPal"
}
<your-paypal>
  <payPalEmail>test@example.com</payPalEmail>
  <payPalName>Test PayPal</payPalName>
</your-paypal>
Field Notes
payPalEmail Email address you used to register with PayPal
payPalName Name of this PayPal facility

Surcharges

PayWay can apply surcharges on your behalf. When you create a customer, we will store the surcharge rate applicable to their payment method.

To process payments, send the principal amount. PayWay calculates the surcharge amount. The customer pays the principal plus surcharge.

You receive settlement for the full payment amount. If you wish, we can set up your bank account or merchant facility to settle the surcharges separately. This may make bank statement reconciliation easier.

If you decide to impose a surcharge, you must ensure your customers are aware - before they enter into the transaction or contract - that a surcharge will apply and the amount of the surcharge.

To set your surcharge rates:-

  1. Sign-in to PayWay
  2. Click on Administration in the menu
  3. Click on Surcharges

If you change your surcharge rates, those rates will apply only to new customers.

Get Surcharges

To get the surcharges configured for your facilty:

GET /surcharges

You may access this resource with either your secret or publishable API key.

Surcharges Model

Example of Surcharge Rates

{
  "visaMastercardPercentage" : 0.0,
  "americanExpressJcbPercentage" : 2.0,
  "dinersClubPercentage" : 1.777,
  "bankAccountAmount" : 2.00,
  "currency" : "aud"
}
<surcharges>
  <visaMastercardPercentage>0.0</visaMastercardPercentage>
  <americanExpressJcbPercentage>2.0</americanExpressJcbPercentage>
  <dinersClubPercentage>1.777</dinersClubPercentage>
  <bankAccountAmount>2.00</bankAccountAmount>
  <currency>aud</currency>
</surcharges>
Field Notes
visaMastercardPercentage Percentage added to Visa and MasterCard payments
americanExpressJcbPercentage Percentage added to American Express and JCB payments
dinersClubPercentage Percentage added to Diners Club payments
bankAccountAmount Dollar amount added to bank account direct debit payments
currency The currency of the bankAccountAmount

Surcharge percentages allow at most three decimal places.

Users

Users are people who can sign-in to the PayWay website.

You can add and update users through the PayWay website.

List Users

To list all the users in your PayWay facility:

GET /users

This is a paginated resource.

Get a User

To get details of a single user:

GET /user/{loginName}

User Model

Example User

{
  "loginName" : "CODING1",
  "fullName" : "Joe King",
  "phone" : "0299999999",
  "mobile" : "0499999999",
  "email" : "joe.king@example.com",
  "status" : "enabled"
}
<user>
  <loginName>DEMO</loginName>
  <fullName>Joe King</fullName>
  <phone>0299999999</phone>
  <mobile>0499999999</mobile>
  <email>joe.king@example.com</email>
  <status>enabled</status>
 </user>
Field Notes
loginName Uniquely identifies a user. Used when logging in.
fullName The person’s name.
phone
mobile
email
status enabled, locked or disabled

Custom Fields

Use custom fields to store extra information about your customers. For example, you may want a custom field named “Campaign Id” or “Membership Type”. You can have up to four custom fields.

When you create a customer you can send values for your custom fields.

To set up custom fields:

  1. Sign-in to PayWay
  2. Click on Administration in the menu
  3. Click on Custom Fields

List Custom Fields

To list your custom fields:

GET /custom-fields

Get a Custom Field

To get details of a single custom field:-

GET /custom-fields/{customFieldId}

Custom Fields Model

Example Custom Field

{
  "customFieldId" : 2,
  "fieldName" : "Membership Type",
  "help" : "e.g. junior, senior, social",
  "required" : true,
  "hidden" : false
}
<customField>
  <customFieldId>2</customFieldId>
  <fieldName>Membership Type</fieldName>
  <help>e.g. junior, senior, social</help>
  <required>true</required>
  <hidden>false</hidden>
</customField>
Field Notes
customFieldId A number from 1 to 4
fieldName Display name for the field
help Help text for the field
required true or false. If true, this field is mandatory when creating or updating a customer
hidden true or false. If true, this field is hidden from customers (e.g. in receipt emails)

API Keys

Your API keys are used to authenticate with this API.

You can generate new keys and delete keys through the PayWay website. See Obtaining an API Key.

Secret API keys expire after 2 years.

Automate Secret API Key Renewal

To use your existing key to get a new key:

GET /api-keys/latest

The response contains the key you should use from now on.

Usually this is your existing key. When your existing key is about to expire, this is your new key.

You should do this once per day.

To test your automatic key renewal code:

  1. Create two secret API keys using the PayWay website.
  2. Configure your application to use the first key.
  3. Confirm that your application automatically switches to the second key.

API Key Model

Example API key response

{
  "keyName": "T10000_SEC...1A4",
  "key": "T100000_SEC_RANDOM_RANDOM_RANDOM_1A4"
}
<apiKey>
  <keyName>T10000_SEC...1A4</keyName>
  <key>T100000_SEC_RANDOM_RANDOM_RANDOM_1A4</key>
</apiKey>
Field Notes
keyName Use for logging.
key The secret API key.

Modules

PayWay is made up of modules which you can buy. Find out more about PayWay for a description of each module.

Contact us to buy a new module.

List Modules

To list the modules you have bought:

GET /modules

This is a paginated resource.

Modules Model

Example Modules response

{
    "data": [
        {
            "name": "PayWay Virtual Terminal",
            "creditCard": true
        },
        {
            "name": "PayWay Recurring Billing and Customer Vault",
            "creditCard": true,
            "bankAccount": true
        },
        {
            "name": "PayWay Net",
            "creditCard": true,
            "payPal": false,
            "fraudGuard": false,
            "threeDSecure": false
        }
    ],
    "links": [
        {
            "rel": "help",
            "href": 
               "https://api.payway.com.au/rest-docs/index.html#resources"
        }
    ]
}
<modules>
    <data>
        <module>
            <name>PayWay Virtual Terminal</name>
            <creditCard>true</creditCard>
        </module>
        <module>
            <name>PayWay Recurring Billing and Customer Vault</name>
            <creditCard>true</creditCard>
            <bankAccount>true</bankAccount>
        </module>
        <module>
            <name>PayWay Net</name>
            <creditCard>true</creditCard>
            <payPal>false</payPal>
            <fraudGuard>false</fraudGuard>
            <threeDSecure>false</threeDSecure>
        </module>
    </data>
    <links>
        <link rel="help" href="https://api.payway.com.au/rest-docs/index.html#resources"/>
    </links>
</modules>

For each of your modules, the module name and applicable options are listed.

Field Notes
name The name of the module (see table below)
creditCard
bankAccount
payPal
bpay
australiaPost
westpacBranch
remittanceProcessingService
ownNumber
fraudGuard
threeDSecure
directCredit

Options are true if enabled for your facility and otherwise false.

Modules Names
PayWay API
PayWay Additional Transaction Reporting
PayWay Batch
PayWay Connect
PayWay Match
PayWay Net
PayWay Payment Cards
PayWay Phone
PayWay Recurring Billing and Customer Vault
PayWay Virtual Terminal

Reference

Test Card Numbers

Use the following credit card numbers with your test facility. All other card numbers will return 42 No universal account. An incorrect expiry date will return 54 Expired card.

The cardholder name does not matter.

Card Number Security Code Expiry Response
4564710000000004 847 02/19 08 Visa Approved
5163200000000008 070 08/20 08 MasterCard Approved
2221000000000009 009 01/20 08 MasterCard Approved
4564710000000012 963 02/05 54 Visa Expired
4564710000000020 234 05/20 51 Visa Low Funds ($10 credit limit)
5163200000000016 728 12/19 04 MasterCard Stolen
376000000000006 2349 06/20 08 American Express Approved
343400000000016 9023 01/19 62 American Express Declined
36430000000007 348 06/22 08 Diners Club Approved
36430000000015 988 08/21 43 Diners Club Stolen

Test Bank Accounts

Use the following bank accounts for testing.

The account name does not matter.

BSB Account Number Response
000-000 Any Approved

HTTP Response Codes

The following response codes are used.

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.

If you create a payment file, you must use the status field to determine if the file has errors or is being processed.

202 Accepted

The request has been accepted for processing, but the processing has not completed.

This response code is returned if the credit card network is slow to respond when processing a transaction. The status of the transaction will be pending.

To find out if the transaction is approved or declined, send a request to get transaction details.

204 No Content

The server has fulfilled the request.

This response code is returned when a DELETE is processed.

400 Bad Request

The request could not be understood by the server due to malformed syntax.

This response code is returned if the Idempotency-Key header is too long.

This response code is returned if you send query parameters on a PUT, POST or PATCH request. See Sending Fields for PUT, POST and PATCH.

401 Unauthorised

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 cGFzc3dvcmQ=

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

See authentication for information on API keys.

403 Forbidden

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

Incorrect API Key

Check if you have provided your publishable key when you should have provided your secret key. See authentication for information on API keys.

PayWay Module Required

To create customers with a stored payment setup, you must have the PayWay Recurring Billing and Customer Vault module.

To create customers with virtual accounts, you must have the PayWay Match module.

To download receipts files, you must have the PayWay Connect module.

To upload payment files, you must have the PayWay Recurring Billing and Customer Vault module or the PayWay Batch module.

PayWay Setup Incomplete

If you receive the following message, you should contact us.

Your implementation manager must complete the following tasks before you can continue:

404 Not Found

Example 404 Not Found Response

{
  "data" : [ {
    "fieldName" : "transactionId",
    "message" : "Invalid transaction id.",
    "fieldValue" : "99999999"
  } ]
}
<errors>
  <data>
    <error>
      <fieldName>transactionId</fieldName>
      <message>Invalid transaction id.</message>
      <fieldValue>99999999</fieldValue>
    </error>
  </data>
 </errors>

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.

See Requesting JSON or XML.

407 Proxy authentication required

This error is returned by your proxy server, not PayWay.

You need to configure a proxy user name and password in order to access the internet. You can use cURL to check network connectivity.

See HTTP Status Code Definitions.

409 Conflict

The server can not process the request as it has conflicted with another request.

This occurs if you attempt to create two customers with the same customer number simultaneously.

This also occurs if you attempt to upload a payment file with a duplicate name.

See Avoiding Duplicate Posts.

415 Unsupported Media Type

The server can not process the content type which was provided.

See:

422 Unprocessable Entity

422 Unprocessable Entity Response

{
  "data" : [ {
    "fieldName" : "customerNumber",
    "message" : "Please complete this field.",
    "fieldValue" : ""
  }, {
    "fieldName" : "principalAmount",
    "message" : "Invalid amount.",
    "fieldValue" : "x"
  } ]
}
<errors>
  <data>
    <error>
      <fieldName>customerNumber</fieldName>
      <message>Please complete this field.</message>
      <fieldValue></fieldValue>
    </error>
    <error>
      <fieldName>principalAmount</fieldName>
      <message>Invalid amount.</message>
      <fieldValue>x</fieldValue>
    </error>
  </data>
</errors>

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.

429 Too Many Requests

You have sent too many requests in a given amount of time.

If you send more than 6 simultaneous requests, you may receive this response code.

If you resend a POST with an Idempotency-Key before the server has processed the original request, you will receive this response code.

You should wait for 20 seconds and resend the request with the same Idempotency-Key.

Token Quota Exceeded

A quota of 100 unused single use tokens applies. Immediately after obtaining a token, you should use it to create or update a customer. 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

Example 500 Internal Server Error Response

<error>
  <errorNumber>1</errorNumber>
  <traceCode>403686</traceCode>
</error>
{
  "errorNumber" : 1,
  "traceCode" : "403686"
}

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. If you resend a POST, you may cause duplicate processing. e.g. charge the customer twice.

Contact PayWay Technical Support. Provide the following information:-

501 Not Implemented

The server does not recognize the request method. Use one of the standard HTTP verbs.

See HTTP Verbs.

503 Service Unavailable

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

The server has not processed the request. You may resend the request.

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

Transaction Response Codes

To determine if a transaction was approved or declined, you must use the status field.

The responseCode and responseText provide further information.

For more information, see the User Guide on the Downloads page.

Contact Us

Purchase PayWay

See Enquire Now.

Add Merchants, Accounts, Modules or Close a Facilty

Phone a Customer Care Banking Representative on 1300 368 098 between 8 am and 8 pm, Monday to Friday or email prioritysegments@westpac.com.au

Reset Passwords

Visit Forgotten Password and use your email address and security question to reset your password.

If you have further problems accessing your account, please fax a written request with your name, phone number, email address and business name on a company letterhead to +61 2 4951 0055.

Technical Support

Phone the Helpdesk team on 1300 727 111 between 8.30am to 5.30pm (AEST), Monday to Friday or email payway@qvalent.com

Notice

PayWay® is a registered trademark of Westpac Banking Corporation

Copyright © Westpac Banking Corporation ABN 33 007 457 141 AFSL & Australian credit licence 233714

By accessing and viewing this website you agree to be bound by the Terms and Conditions of this website.

Click here to view our Privacy Policy.