Skip to main content

PayWay REST API

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

Developer? Get a PayWay test facility.

About PayWay REST API

This page describes the PayWay REST Application Programmer Interface.

Access to the API depends on the PayWay modules you have purchased.

The PayWay Net module allows you to:

  • Create a check-out or donations page and process one-time credit card payments
  • Maintain full control over the customer experience and styling
  • Reduce your PCI-DSS compliance scope by not processing or storing credit card details on your server.

Find out how to accept online payments and reduce PCI-DSS scope.


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

  • Store credit card and bank account details in the PayWay customer vault
  • Take payments using the stored details individually or using a file
  • Reduce your PCI-DSS compliance scope by not processing or storing credit card details on your server
  • Schedule regular collection of payments from a customer.

The PayWay Match module allows you to:

  • Open virtual accounts for customers who pay you by direct debit/pay anyone.

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

Find out how to automatically match EFT payments to customers.


The PayWay Batch module allows you to:

  • Process a file of credit card payments
  • Download reports indicating which payments were approved or declined.

The PayWay Connect module allows you to:

  • Download a machine-readable file listing all received payments for a day.

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 Classic Credit Card API Process payments by sending credit card details from your PCI-DSS compliant system.

See PayWay Classic Credit Card API.

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 on this page 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.

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

Resources

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

  • adding new resources
  • supporting new HTTP verbs
  • adding new optional request parameters
  • adding new properties or XML elements in responses
  • changing wording of error message designed to be displayed to users
  • improved error reporting when an invalid request is received.

Write your software to handle these types of changes.

Javascript

The following changes to payway.js will not result in a new API version:

  • changing resources used internally by payway.js
  • adding new properties to objects passed to callback functions
  • adding new optional properties to payway.js functions you call
  • modifying messages posted between payway.js and an iframe hosted by us.

Write your software based on the documented API.

Security

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

  • adding or removing TLS ciphers
  • changing supported TLS versions
  • changing the PayWay server SSL certificate or which certificate authority signs this certificate
  • other changes made to improve security.

Authentication

Basic authentication

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

API keys

There are two types of keys:

  • Your publishable API key is used by payway.js to send credit card details directly from the browser to PayWay
  • Your secret API key allows your server to process payments and provides full access to the API
Treat your secret API key like a password.

Obtaining an API key

To develop and test, get a free PayWay test facility.

To purchase a live PayWay facility, contact us.

Once you have a sign in to view and manage your API keys:

  1. Sign in to PayWay
  2. Click Settings
  3. Click REST API Keys

Secret API keys expire after one year 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
If you send a PUT request and omit a field, the server removes or defaults the field value.

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 a HTTP response code from 200 to 299, the server has accepted your request. When you create a transaction or file you must also check the status in the response body.

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.

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

Example links in JSON response

{
"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"
  }
  ]
}

Example links in XML response

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

Lists of items

Resources which return lists use a standard structure:

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

Search URLs

Search URLs are templates:

/search-example?customerNumber={customerNumber}

You must replace parts delimited by braces with actual values.

Dates and times

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.

Example of date and times in JSON response

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

Example of date and times in XML response

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

Tutorials

Trusted frame

Use this tutorial to create a server-side rendered web page that takes a one-off credit card payment or stores credit card details in the customer vault. Your server will not store or process credit card details.

This iframe solution allows you to be compliant with PCI-DSS SAQ A. This is the easiest level of compliance.

It works as follows:

  1. Your server hosts a web page containing a form and payway.js
  2. You call createCreditCardFrame which creates a PayWay iframe for collecting credit card details
  3. The iframe sends credit card details securely to PayWay
  4. The iframe sends a single use token to your website
  5. Your server uses the token in place of the credit card details when you take a payment or create a customer in the customer vault.
If you want to receive the token via a javascript callback see Trusted frame (SPA).

Step 1: Host example page

Host this page on your website. Cardholders will enter their details on this page.

<!DOCTYPE html>
<html>
  <body>
    <!-- this form will POST a single use token to your server -->
    <form action="/process-payment" method="post">
      <div id="payway-credit-card"></div>
      <input id="payway-cc-submit" type="submit" disabled="true"/>
    </form>
    <script src="https://api.payway.com.au/rest/v1/payway.js">
    </script>
    <script type="text/javascript">
      var submit = document.getElementById('payway-cc-submit');
      payway.createCreditCardFrame({
          publishableApiKey: '{publishableApiKey}',
          onValid: function() { submit.disabled = false; },
          onInvalid: function() { submit.disabled = true; }
      });
    </script>
  </body>
</html>

Open the page. You should see this error message:

You must replace {publishableApiKey} with your publishable API key when calling payway.createCreditCardFrame()

Step 2: Set publishable API key

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

You may also change /process-payment to a URL you prefer.

Step 3: Test page

Load your web page, you should see the credit card form.

Screenshot of credit card form

Enter these card details:

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

Click Submit.

Your browser will POST to /process-payment on your server. The POST includes a parameter like this:

singleUseTokenId: 2bcec36f-7b02-43db-b3ec-bfb65acfe272

Step 4: Take payment or save credit card

You can now use the single use token to take a payment or save the credit card to the PayWay customer vault.

When you receive a POST to /process-payment you should:

  1. Read the single use token from the parameter
  2. Verify your customer using a session cookie
  3. Using your secret API key and the single use token, send a request to take a one-time payment.

If you need to take more than one payment with the credit card details, you should store the credit card, optionally verify the stored card and then take payments using stored details.

Step 5: Improve your solution

You must now improve your solution by:

You may also wish to:

Trusted frame (SPA)

Use this tutorial to create a single-page application (SPA) that takes a one-off credit card payment or stores credit card details in the customer vault. Your server will not store or process credit card details.

This iframe solution allows you to be compliant with PCI-DSS SAQ A. This is the easiest level of compliance.

It works as follows:

  1. Your single page application fetches payway.js
  2. You call createCreditCardFrame which creates a PayWay iframe for collecting credit card details
  3. The cardholder enters their details in the frame
  4. You call frame.getToken and the iframe sends credit card details securely to PayWay
  5. The iframe makes a callback to your application passing a single use token
  6. You send the single use token to your server using ajax
  7. Your server uses the token in place of the credit card details when you take a payment or create a customer in the customer vault.

Step 1: Host example page

Host this page on your website. Cardholders will enter their details on this page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>PayWay Trusted Frame Example Code</title>
    <meta charset="UTF-8">
  </head>
  <body>
    <h1>PayWay Trusted Frame Example</h1>

    <div id="payway-credit-card">
    </div>

    <br/>

    <button id="pay" disabled>Pay</button>

    <script src="https://api.payway.com.au/rest/v1/payway.js">
    </script>

    <script>
      "use strict";
      const payButton = document.getElementById( "pay" );
      let creditCardFrame = null;

      const tokenCallback = function( err, data ) {
        if ( err ) {
          console.error( "Error getting token: " + err.message );
        } else {
          // TODO: send token to server with ajax
          console.log( "singleUseTokenId: " + data.singleUseTokenId );
        }
        creditCardFrame.destroy();
        creditCardFrame = null;
      };

      payButton.onclick = function() {
        payButton.disabled = true;
        creditCardFrame.getToken( tokenCallback );
      };

      const createdCallback = function( err, frame ) {
        if ( err ) {
          console.error( "Error creating frame: " + err.message );
        } else {
          // Save the created frame for when we get the token
          creditCardFrame = frame;
        }
      };

      const options = {
        // TODO: Replace {publishableApiKey} with your key
        publishableApiKey: "{publishableApiKey}",
        tokenMode: "callback",
        onValid: function() { payButton.disabled = false; },
        onInvalid: function() { payButton.disabled = true; }
      };
      payway.createCreditCardFrame( options, createdCallback );
    </script>

  </body>
</html>

Open the page and open the javascript developer console.

You should see this error message:

You must replace {publishableApiKey} with your publishable API key when calling payway.createCreditCardFrame()

Step 2: Set publishable API key

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

Step 3: Test page

Load your web page, you should see the credit card form.

Screenshot of credit card form

Enter these card details:

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

Click Pay.

The single use token will be logged to the javascript console.

singleUseTokenId: 2bcec36f-7b02-43db-b3ec-bfb65acfe272

Step 4: Send token to server

You must now write code to send the token to your server using ajax.

Step 5: Take payment or save credit card

Your server can now use the single use token to take a payment or save the credit card to the PayWay customer vault.

  1. Read the single use token from the ajax endpoint
  2. Verify your customer using a session cookie
  3. Using your secret API key and the single use token, send a request to take a one-time payment.

If you need to take more than one payment with the credit card details, you should store the credit card, optionally verify the stored card and then take payments using stored details.

Make sure the cardholder can not tamper with the payment amount before your sever sends it to PayWay

Step 6: Improve your solution

You must now improve your solution by:

You may also wish to:

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

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.

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/docs/rest.html#resources"
  } ]
}

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 Entrust Certification Authority - L1M 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

  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.
Screenshot of Postman's Authorization Tab

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 add the PayWay Connect module and choose a receipts file format.

Step 1: Add PayWay Connect

To add PayWay Connect, your administrator must:

  1. Sign in to PayWay
  2. Click Settings
  3. Click PayWay Connect
  4. Proceed to add the module.

Step 2: Choose a receipts file format

To choose a receipts files format:

  1. Sign in to PayWay
  2. Click Settings
  3. Click Receipts Files
  4. 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
  1. Replace {secretApiKey} with your Secret API Key
  2. 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:

  • Logging errors
  • Automating the process by creating a scheduled task - refer to your operating system's documentation
  • Import the file you have downloaded into your accounting system
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 3 am Sydney time each day. The receipts file contains transactions from the previous settlement day. Receipts files are available for 365 days.

To see which receipts files are available:

  1. Sign in to PayWay
  2. Click Receipts Files under the Reports menu
curl: (23) Failed writing body (0 != 1)

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

  • Backup the receipts file already saved
  • Delete the receipts file
  • Run the command again
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 Entrust Certification Authority - L1M 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
  1. Replace {secretApiKey} with your Secret API Key
  2. 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:

  • Logging errors
  • Automating the process by creating a scheduled task - refer to your operating system's documentation
  • Polling the status of your file
  • Downloading errors in your file and reporting them to your staff

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 Issued by us to uniquely identify your PayWay facility
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 may be payments, refunds, pre-authorisations, captures or account verifications. An account verification checks if a customer's credit card is valid. A pre-authorisation reserves money on your customer's credit card. Later, a capture debits the reserved money.

You can:

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

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

Take payment

To take a one-time credit card payment, first get a single use token and then:

POST /transactions

You must send:

Field Notes
singleUseTokenId A token issued by PayWay which holds credit card details. See single use tokens.
customerNumber Your reference for the customer. Up to 20 letters and digits. Case insensitive. Leading zeroes ignored if entirely numeric. Customer does not need to exist in the customer vault.
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.
merchantId This merchant will be used for payment processing and settlement.
customerIpAddress If the cardholder entered their card number directly send their IPv4 or IPv6 address. If your staff entered the card number, do not send this field. See customer IP address.
threeDS2 Optional. true if you have implemented EMV 3-D Secure Version 2.

In the same request, you may also send custom fields.

Avoid duplicate payments

To avoid processing duplicate payments:

To reduce the risk of fraud:
  • enable Fraud Guard
  • send the customerIpAddress if your customers trigger payments directly
  • protect against card testing

Take payment using stored card or account

To take a payment using credit card or bank account stored against a customer:

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.
customerIpAddress If the cardholder triggered this payment directly send their IPv4 or IPv6 address. Otherwise do not send this field. See customer IP address.

You must handle errors and avoid duplicates and reduce your fraud risk.

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, the merchant to be used for payment processing and settlement. Ignored otherwise.
bankAccountId If the customer is paying by bank account direct debit, your bank account to be used for payment processing and settlement. Ignored otherwise.

Verify a stored card

To verify a credit card stored against a customer:

POST /transactions

You must send:

Field Notes
customerNumber This customer's credit card will be verified.
transactionType accountVerification
currency aud
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.
customerIpAddress If the cardholder initiated the card registration, send their IPv4 or IPv6 address. Otherwise do not send this field. See customer IP address.

You must handle errors and avoid duplicates and reduce your fraud risk.

Merchant ID

PayWay will process the payment using the merchant from the customer's payment setup. To use a different merchant, send:

Field Notes
merchantId The merchant to be used for payment processing and settlement.

Process pre-authorisation

To process a credit card pre-authorisation, first get a single use token and then:

POST /transactions

You must send:

Field Notes
singleUseTokenId A token issued by PayWay which holds credit card details. See single use tokens.
customerNumber Up to 20 letters and digits. Case insensitive. Leading zeroes ignored if entirely numeric. Uniquely identifies a customer.
transactionType preAuth
principalAmount The amount of the pre-authorisation before any surcharge is added.
currency aud
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.
merchantId This merchant will be used for processing.
customerIpAddress If the cardholder triggered this pre-authorisation directly send their IPv4 or IPv6 address. If your staff entered the card number, do not send this field. See customer IP address.
threeDS2 Optional. true if you have implemented EMV 3-D Secure Version 2.

In the same request, you may also send custom fields.

You must handle errors and avoid duplicates and reduce your fraud risk.

Later, you can capture the pre-authorisation to charge the card.

Process pre-authorisation using stored credit card

To process a credit card pre-authorisation using the credit card stored against a customer:

POST /transactions

You must send:

Field Notes
customerNumber This customer's credit card will be used to process the pre-authorisation.
transactionType preAuth
principalAmount The amount of the pre-authorisation before any surcharge is added.
currency aud
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.
customerIpAddress If the cardholder triggered this pre-authorisation directly send their IPv4 or IPv6 address. Otherwise, do not send this field. See customer IP address.
Merchant ID

PayWay will process the pre-authorisation using the merchant from the customer's payment setup. To use a different merchant, send:

Field Notes
merchantId This merchant will be used for processing.

You must handle errors and avoid duplicates and reduce your fraud risk.

Later, you can capture the pre-authorisation to charge the card.

Capture a pre-authorisation

To capture a pre-authorisation:

POST /transactions

You must send:

Field Notes
transactionType capture
parentTransactionId The transactionId of the pre-authorisation
principalAmount The amount of the capture before any surcharge is added. Send a positive value.
orderNumber Optional. Your reference for this transaction. At most 20 ascii characters.
customerIpAddress If the cardholder triggered this capture directly send their IPv4 or IPv6 address. Otherwise, do not send this field. See customer IP address.

In the same request, you may also send custom fields.

You must handle errors and avoid duplicates and reduce your fraud risk.

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.
customerIpAddress If the cardholder triggered this refund directly send their IPv4 or IPv6 address. Otherwise, do not send this field. See customer IP address.

In the same request, you may also send custom fields.

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.

Custom fields

To provide values for custom fields for a transaction:

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

Use custom fields to store additional information about your transaction. You must first set up a master list of custom fields in your PayWay facility. Each field can store 60 ASCII characters.

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, preAuth, capture or accountVerification
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

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, preAuth, capture or accountVerification
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 a creditCard transaction, customer's credit card.
merchant If a creditCard transaction, your merchant facility.
bankAccount If a bankAccount transaction, customer's direct debit bank account.
virtualAccount If a directCredit transaction, the virtual account which the customer credited.
australiaPost If an australiaPost transaction, details of the Australia Post payment.
bpay If a bpay transaction, details of the BPAY payment.
yourBankAccount If a bankAccount, directCredit, bpay, australiaPost, westpacBranch or remittanceProcessingService transaction your settlement bank account.
customerPayPalAccount If a payPal transaction, customer's PayPal account.
yourPayPalAccount If a payPal transaction, 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 capture, the original pre-authorisation.
customerIpAddress IP address your customer used to connect and process the transaction (if applicable). See customer IP address.
fraudResult Outcome of Fraud Guard checks. See Fraud Result.
customerIpCountry If suspended because of the country the customer connected from, the two character code of that country
cardCountry If suspended because of the country of the bank which issued the credit card, the two character code of that country
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.

Example transaction JSON response

{
  "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",
    "cardType" : "credit",
    "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
}

Example transaction XML response

<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>
    <cardType>credit</cardType>
    <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>
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 An unusual payment for you to review. See fraudResult for more.

Note:

  • Bank account direct debit transactions may be declined by your customer's bank for three banking days after processing
  • Cheques may be dishonoured up to five banking days after processing.
Banking Days are Monday to Friday excluding national public holidays.

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, unionpay, amex, diners, eftpos or jcb.
cardType credit or debit if cardScheme is visa or mastercard.
cardholderName The name printed on the card.
walletType applePay or googlePay if the customer paid by digital wallet.
panType fpan if a full card number was provided, dpan if a digital card number was provided.

Customer bank account

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.

Example bank account JSON response

{
  "bsb" : "000-000",
  "accountNumber" : "123123",
  "accountName" : "Jenny Nguyen"
}

Example bank account XML response

<bankAccount>
  <bsb>000-000</bsb>
  <accountNumber>123123</accountNumber>
  <accountName>Jenny Nguyen</accountName>
</bankAccount>

Virtual account

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

These fields are returned under the virtualAccount field:

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

Example virtual account JSON response

{
  "bsb": "037-889",
  "accountNumber": "80000000"
}

Example virtual account XML response

<virtualAccount>
  <bsb>037-889</bsb>
  <accountNumber>80000000</accountNumber>
</virtualAccount>

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

Fraud result

Fraud Guard suspends unusual credit card payments. You can review suspended payments and choose to complete or cancel them.

You must send the customerIpAddress in order to have payments checked by Fraud Guard. See customer IP address for more information.

fraudResult indicates if the payment was checked by Fraud Guard:

Fraud Result Notes
ok Payment was not unusual
skip Fraud Guard was skipped for this payment
velcty Many payments using the same credit card were made in a short period of time
lrgamt Payment is unusually large
hrskip Customer connected from a high-risk country (e.g. Nigeria). See customerIpCountry
anprxy Customer connected using an anonymous or suspicious proxy
blckip Customer connected from country where you do not do business. See customerIpCountry
blkbin The bank which issued the credit card is not in a country where you do business. See cardCountry
binmip Customer is in a different country to the bank which issued the credit card. See customerIpCountry and cardCountry
blkipa IP address is blocked
blkpan Credit card number is blocked
error Contact Technical Support

If fraudGuard is not in the response, the payment was not checked by Fraud Guard.

To review suspended payments:

  1. Sign in to PayWay
  2. Click Suspended in the Transactions menu

To configure Fraud Guard:

  1. Sign in to PayWay
  2. Click Settings
  3. Click Fraud Guard under the PayWay Modules heading

Transaction custom fields

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.

Example custom fields JSON response

{
  "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
  } ]
}

Example custom fields XML response

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

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 scope is reduced 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 or bank account for new customer

For step-by-step instructions, see Trusted Frame 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 If token contains a credit card, the merchant to be used for payment processing and settlement. Ignored otherwise.
bankAccountId If token contains a bank account, your bank account to be used for payment processing and settlement. Ignored otherwise.
threeDS2 Optional. true if the token contains a credit card and you have implemented EMV 3-D Secure Version 2.
Testing? Use merchantId=TEST and bankAccountId=0000000A

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.

Next, you may wish to verify the stored card prior to processing payments.

Open a 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
Testing? Use bankAccountId=0000000A

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 credit card or bank account:

PATCH /customers/{customerNumber}/payment-setup

Send this field:

Field Notes
stopped true

If the customer has a schedule, it is stopped.

Later, to allow the stored credit card or bank account to be used again:

PATCH /customers/{customerNumber}/payment-setup

Send this field:

Field Notes
stopped false

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 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.
threeDS2 Optional. true if the token contains a credit card and you have implemented EMV 3-D Secure Version 2.

Update the settlement account for a customer

To change the settlement account for transactions made with a specific customer:

PATCH /customers/{customerNumber}/payment-setup

Send only one of the below fields, depending on the customer's payment method:

Field Notes
merchantId Required if the customer has a credit card linked. Considered an error otherwise.
bankAccountId Required if the customer has a bank account linked. Considered an error otherwise.

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 a 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 a 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

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.

Example customer surcharge JSON response

{
  "principalAmount" : 100.00,
  "surchargeAmount" : 1.11,
  "paymentAmount" : 101.11,
  "currencyCode" : "aud"
}

Example customer surcharge XML response

<customerSurcharge>
  <principalAmount>100.00</principalAmount>
  <surchargeAmount>1.11</surchargeAmount>
  <paymentAmount>101.11</paymentAmount>
  <currencyCode>aud</currencyCode>
</customerSurcharge>

Delete customer

DELETE /customers/{customerNumber}

A customer can not be deleted if they:

  • have been issued a PayWay Payment Card
  • have a payment in their payment history
  • have pending payments
  • have an active recurring schedule.

Customer model

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

The customer model consists of:

  • Payment setup - customer's credit card or direct debit bank account
  • Contact details - name, email, phone number and address
  • Custom fields - values for fields you have defined
  • Notes - free text
  • Payment schedule - a regular series of payments to be processed using the payment setup
  • Virtual account - an account used to accept direct credit payments from the 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.

Example customer JSON 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"
    }
  }
}

Example customer XML response

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

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, unionpay, amex, diners, eftpos or jcb.
cardType credit or debit if cardScheme is visa or mastercard.
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. Maximum 60 ASCII characters, letters, numbers and punctuation.
emailAddress Maximum 128 ASCII characters. We validate based on RFC 5322 and RFC 1035.
sendEmailReceipts true or false. If true email receipts are automatically sent for each transaction.
phoneNumber We use the libphonenumber library for validation, with a default country of Australia.
street1 Maximum 128 ASCII characters.
street2 Maximum 128 ASCII characters.
cityName Maximum 60 ASCII characters.
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 set up a master list of custom fields in your PayWay facility. Each field can store 60 ASCII characters.

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

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

Example customer schedule JSON response

{
  "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
}

Example customer schedule XML response

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

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.

Your PCI-DSS compliance scope is reduced when your server does not store or process credit card details.

Tokenise credit card (webpage)

To add a PayWay iframe containing credit card fields to your page, include payway.js, create a div with id payway-credit-card, and call payway.createCreditCardFrame.

For step-by-step instructions, see the Trusted Frame tutorial.

For JavaScript reference, see payway.js.

Screenshot of credit card form

Tokenise bank account (webpage)

To add a PayWay iframe containing bank account fields to your page, include payway.js, create a div with id payway-bank-account, and call payway.createBankAccountFrame.

For JavaScript reference, see payway.js.

Screenshot of bank account form

Tokenise credit card (mobile app)

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

POST /single-use-tokens

Use your publishable API key.

Only call this API directly from your mobile app. Do not send credit card details to your server.

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 bank account (mobile app)

To tokenise a direct debit bank account from your mobile application:

POST /single-use-tokens

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

If you send valid fields:

  • the credit card or direct debit bank account details are stored by PayWay for 10 minutes
  • a singleUseTokenId is returned in the response
  • you should send the token in a request to create a customer in the customer vault.

Alternatively, you can update a customer in the vault.

Example single use token JSON response

{
  "singleUseTokenId" : "2bcec36f-7b02-43db-b3ec-bfb65acfe272"
}

Example single use token XML response

<singleUseToken>
  <singleUseTokenId>2bcec36f-7b02-43db-b3ec-bfb65acfe272</singleUseTokenId>
</singleUseToken>

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

3-D Secure Authentication

Authentication is the process of confirming that the person making an e-commerce transaction is entitled to use the payment card.

When you create a single use token and the response indicates threeDS2AuthRequired=true, your next step is to authenticate.

Authenticate

To authenticate the credit card stored in a singleUseToken using 3-D Secure 2:

POST /single-use-tokens/{singleUseTokenId}/three-ds2-authentication

Send these fields:

Use your secret API key.

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

Make sure the cardholder can not tamper with these fields before your server sends them to PayWay.

Authentication Purpose

Send these fields when authenticating a credit card:

Field Notes
messageCategory

Required. How you will use the single use token

01 Payment Authentication. If you will use the token to conduct a payment.
02 Non-Payment Authentication. If you will use the token to store the card details.
threeDSRequestorAuthenticationInd

Required. The reason for the Authentication request.

01 Payment transaction
02 Recurring transaction
03 Instalment transaction
04 Add card
05 Maintain card
06 Cardholder verification as part of EMV token ID&V
merchantId Required. The merchant identifier issued by us to uniquely identity your merchant facility.

Purchase Information

If you will immediately conduct a payment or conduct a recurring series of payments, send these fields when authenticating a credit card:

Field Notes
principalAmount Purchase amount before any surcharge is added by PayWay
currency aud
purchaseInstalData Required if you and Cardholder have agreed to instalment payments. The maximum number of authorisations permitted for instalment payments. Max 999
recurringExpiry Optional. Date after which no further authorisations shall be performed. Format YYYYMMDD
recurringFrequency Optional. The minimum number of days between authorisations. e.g. 28. Max 9999

Merchant Risk Indicator

We strongly recommend you send these fields when authenticating a credit card:

Field Notes
deliveryEmailAddress For Electronic delivery, the email address to which the merchandise will be delivered.
deliveryTimeframe

Your delivery timeframe.

01 Electronic Delivery
02 Same day shipping
03 Overnight shipping
04 Two-day or more shipping
giftCardAmount For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s)
giftCardCount For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. Max 99
giftCardCurr For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card. e.g. 036 for Australian Dollars
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available. Format YYYYMMDD.
preOrderPurchaseInd

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

01 Merchandise available
02 Future availability
reorderItemsInd

Indicates whether the cardholder is reordering previously purchased merchandise.

01 First time ordered
02 Reordered
shipIndicator

Indicates shipping method chosen for the transaction.

You must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not your general business.

If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.

01 Ship to cardholder's billing address
02 Ship to another verified address you hold on file
03 Ship to address that is different than the cardholder's billing address
04 Ship to Store / Pick-up at local store (Store address shall be populated in shipping address fields)
05 Digital goods (includes online services, electronic gift cards and redemption codes)
06 Travel and Event tickets, not shipped
07 Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)

Cardholder Contact Details

Send these fields when authenticating a credit card:

Field Notes
email The email address associated with the account that is either entered by the cardholder, or you have on file. Max 254 characters.
homePhone Optional. The home phone number provided by the Cardholder. Max 15 characters.
mobilePhone Optional. The mobile phone number provided by the Cardholder. Max 15 characters.
workPhone Optional. The work phone number provided by the Cardholder. Max 15 characters.

Use international format for phone numbers. e.g. +61499999999

Billing Address

These fields contain the billing address associated with the credit card. The billing address is required if you will use the token to conduct a payment, and recommended if you will use the token to store the card details.

Field Notes
billAddrLine1 First line of the street address or equivalent local portion. Max 50 characters.
billAddrLine2 Optional. Second line of the street address or equivalent local portion. Max 50 characters.
billAddrLine3 Optional. Third line of the street address or equivalent local portion. Max 50 characters.
billAddrCity The city of the billing address. Max 50 characters.
billAddrPostCode ZIP or other postal code of the billing address. Max 16 characters.
billAddrState The state or province. Max 3 characters. Use the ISO 3166-2 country subdivision code. e.g. NSW
billAddrCountry Use the ISO 3166-1 numeric three-digit country code. e.g. 036

Shipping Address

Send these fields if you will ship physical goods to the cardholder:

Field Notes
addrMatch Optional. Y if Shipping Address matches Billing Address, otherwise N
shipAddrLine1 First line of the street address or equivalent local portion. Max 50 characters.
shipAddrLine2 Optional. Second line of the street address or equivalent local portion. Max 50 characters.
shipAddrLine3 Optional. Third line of the street address or equivalent local portion. Max 50 characters.
shipAddrCity The city of the shipping address. Max 50 characters.
shipAddrPostCode ZIP or other postal code of the shipping address. Max 16 characters.
shipAddrState The state or province. Max 3 characters. Use the ISO 3166-2 country subdivision code. e.g. NSW
shipAddrCountry Use the ISO 3166-1 numeric three-digit country code. e.g. 036

Cardholder Account Information

These fields contain optional information about the Cardholder Account on your website. Fields used to define a time period can be included as either the specific date or an approximate indicator for when the action occurred. You can use either format.

If the cardholder has not signed in to your website, send these fields:

Field Notes
chAccAgeInd

Optional. Length of time that the cardholder has had the account with you

01 for No account (guest checkout)
paymentAccInd

Optional. Indicates the length of time that the payment account was enrolled in the cardholder's account with you.

01 for No account (guest checkout)

If the cardholder has signed in to your website, send these fields:

Field Notes
acctID Optional. Cardholder Account Identifier. Additional information about the account optionally provided by you. Max 64 characters.
chAccAgeInd

Optional. Length of time that the cardholder has had the account with you.

02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
chAccChange Optional. Date that the cardholder's account with you was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Format YYYYMMDD
chAccChangeInd

Optional. Length of time since the cardholder's account information with you was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

01 Changed during this transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days
chAccDate Optional. Date that the cardholder opened the account with you. Format YYYYMMDD
chAccPwChange Optional. Date that cardholder's account with you had a password change or account reset. Format YYYYMMDD
chAccPwChangeInd

Optional. Indicates the length of time since the cardholder's account with you had a password change or account reset.

01 No change
02 Changed during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
nbPurchaseAccount Optional. Number of purchases with this cardholder account during the previous six months. Max 9999.
paymentAccAge Optional. Date that the payment account was enrolled in the cardholder's account with you. Format YYYYMMDD
paymentAccInd

Optional. Indicates the length of time that the payment account was enrolled in the cardholder's account with you.

01 No account (guest check-out)
02 During this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
provisionAttemptsDay Optional. Number of Add Card attempts in the last 24 hours. Max 999.
shipAddressUsage Optional. Date when the shipping address used for this transaction was first used with you. Format YYYYMMDD.
shipAddressUsageInd

Optional. Indicates when the shipping address used for this transaction was first used with you.

01 This transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days
shipNameIndicator

Optional. Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

01 Account Name identical to Shipping Name
02 Account Name different than Shipping Name
suspiciousAccActivity

Optional. Indicates whether you have experienced suspicious activity (including previous fraud) on the cardholder account.

01 No suspicious activity has been observed
02 Suspicious activity has been observed
txnActivityDay

Optional. Number of transactions (successful and abandoned) for this cardholder account across all payment accounts in the previous 24 hours. Max 999.

txnActivityYear

Optional. Number of transactions (successful and abandoned) for this cardholder account across all payment accounts in the previous year. Max 999.

Authentication Response

The 3-D secure authentication response indicates the outcome of the authentication.

Example authentication JSON response

{
  "transStatus" : "R"
}

Example authentication XML response

<threeDS2Authentication>
  <transStatus>R</transStatus>
</threeDS2Authentication>

Use the transStatus to choose what to do next.

transStatus Notes
A Frictionless Flow
C Challenge Flow
N Authentication Failed
R Authentication Failed
U Authentication Failed
Y Frictionless Flow
Frictionless Flow (A or Y)

The Frictionless Flow does not require further Cardholder interaction to achieve a successful authentication and complete the 3-D Secure authentication process.

If you receive an A or Y response, you must send a request to:

Send parameter threeDS2 set to true.

Challenge Flow (C)

Further Cardholder interaction is required to complete the authentication.

If you receive a C response, you must display a web page containing a challenge iFrame. To do this, call the javascript function payway.createChallengeFrame.

After the challenge has been attempted, you will receive an updated transStatus or javascript callback to allow you to continue.

Authentication Failed (N, R or U)

If you receive a N or R or U response, you must display a web page indicating that authentication has failed.

Do not take a payment, create a customer or update a customer.

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 Receipts files formats. We recommend the RECall File format.

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

Download receipts files

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

To download a receipts file in your selected format:

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

To download a receipts file in PayWay CSV payments file format:

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

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:

  • Create a file in one of the Payment File Formats
  • Encode your POST as multipart/form-data using cUrl or a standard library
  • In the multipart request, send a field named file with a unique filename.

200 OK or 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.

The filename may contain ASCII letters, numbers, dashes, underscores, spaces and fullstops. Spaces are not recommended as they complicate shell scripts and introduce the need for URL encoding.

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-report

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:

If you use PayWay Batch, your system must meet Payment Card Industry Data Security Standard (PCI-DSS) requirements for storing credit card numbers.

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

Field Notes
merchantId Issued by us to uniquely identify a merchant facility
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.

Example merchant JSON response

{
  "merchantId": "4638116",
  "merchantName": "MEGS BEAUTY AND NAILS",
  "settlementBsb": "133-605",
  "settlementAccountNumber": "172174",
  "surchargeBsb": "133-606",
  "surchargeAccountNumber": "172131"
}

Example merchant XML response

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

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

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 Issued by us to uniquely identify a direct entry user. 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 Settings
  3. Click Bank Accounts.

Example your bank account JSON response

{
  "bankAccountId": "133605172174A",
  "remitterName": "MEGS BEAUTY AND NAILS",
  "accountName": "MEGAN ZUCKER",
  "settlementBsb": "133-605",
  "settlementAccountNumber": "172174",
  "surchargeBsb": "133-606",
  "surchargeAccountNumber": "172131"
}

Example your bank account XML response

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

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 Settings
  3. Click 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

Field Notes
payPalEmail Email address you used to register with PayPal
payPalName Name of this PayPal facility

Example PayPal JSON response

{
  "payPalEmail" : "test@example.com",
  "payPalName" : "Test PayPal"
}

Example PayPal XML response

<your-paypal>
  <payPalEmail>test@example.com</payPalEmail>
  <payPalName>Test PayPal</payPalName>
</your-paypal>

Subaccounts

Settlement is the process of paying you for transactions which have been processed. To settle to many different Westpac bank accounts, use subaccounts.

PayWay will use the start of the customer reference number to select the settlement account for each transaction.

This is useful if you collect payments on behalf of many different legal entities.

Customer reference number

If your bank account or merchant is set up to use subaccounts, you must generate your customer reference number in this format:

Digit Position Notes
1 to 6 6 digit prefix allocated by us, indicating the account to use for settlement
7 to 13 7 digits allocated by you, allowing you to reconcile transactions to your customers
14 Check digit calculated by you using Luhn algorithm, validated by us

To set up subaccounts, choose this option when you purchase PayWay.

Subaccounts are not available in PayWay test facilities.

List subaccounts

To list all of your subaccounts:

GET /subaccounts

This is a paginated resource.

Get a subaccount

To get details of a subaccount using a prefix:

GET /subaccounts/{prefix}

Subaccount model

Field Notes
prefix 6 digit number allocated by us, used as prefix of customer reference number
accountName Account holder's name
settlementBsb The BSB used for settlement of the principal amount
settlementAccountNumber The account number used for settlement of the principal amount
PayWay settles any surcharge amount to the BSB and account listed on your bank account or merchant ID.

Example subaccount JSON response

{
  "prefix": "172174",
  "accountName": "MEGAN ZUCKER",
  "settlementBsb": "133-605",
  "settlementAccountNumber": "172174"
}

Example subaccount XML response

<subaccount>
  <prefix>172174</prefix>
  <accountName>MEGAN ZUCKER</accountName>
  <settlementBsb>133-605</settlementBsb>
  <settlementAccountNumber>172174</settlementAccountNumber>
</subaccount>

Surcharges

PayWay can apply surcharges on your behalf. Credit card surcharges are percentage based. Direct debit surcharges are a flat amount.

To take payments, send the principal amount. PayWay calculates the surcharge amount. The response includes the principal, surcharge and total payment amount.

Each customer's payment setup includes the surcharge rate payable by that customer. Payments using a customer's stored payment setup use that rate. Otherwise, the facility surcharge rates are used.

When using trusted frames, to display the surcharge rate to the customer use the rate from the token callback.

For more information, including how to set rates, see Payment Surcharges in PayWay.

Get surcharges

To get the surcharge rates configured for your facility:

GET /surcharges

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

Surcharges model

Field Notes
visaMastercardPercentage For backwards compatibility only, do not use
visaCreditPercentage Percentage added to Visa Credit payments
visaDebitPercentage Percentage added to Visa Debit payments
mastercardCreditPercentage Percentage added to Mastercard Credit payments
mastercardDebitPercentage Percentage added to Mastercard Debit 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.

Example surcharges JSON response

{
  "visaMastercardPercentage" : 0.7,
  "visaCreditPercentage" : 1.1,
  "visaDebitPercentage" : 0.8,
  "mastercardCreditPercentage" : 1.2,
  "mastercardDebitPercentage" : 0.7,
  "unionPayPercentage" : 0.9,
  "americanExpressJcbPercentage" : 2.0,
  "dinersClubPercentage" : 1.777,
  "bankAccountAmount" : 2.00,
  "currency" : "aud"
}

Example surcharges XML response

<surcharges>
  <visaMastercardPercentage>0.7</visaMastercardPercentage>
  <visaCreditPercentage>1.1</visaCreditPercentage>
  <visaDebitPercentage>0.8</visaDebitPercentage>
  <mastercardCreditPercentage>1.2</mastercardCreditPercentage>
  <mastercardDebitPercentage>0.7</mastercardDebitPercentage>
  <unionPayPercentage>0.9</unionPayPercentage>
  <americanExpressJcbPercentage>2.0</americanExpressJcbPercentage>
  <dinersClubPercentage>1.777</dinersClubPercentage>
  <bankAccountAmount>2.00</bankAccountAmount>
  <currency>aud</currency>
</surcharges>

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 /users/{loginName}

User model

Field Notes
loginName Uniquely identifies a user. Used when logging in.
fullName The person's name.
phone
mobile
email
status enabled, locked or disabled

Example user JSON response

{
  "loginName" : "CODING1",
  "fullName" : "Joe King",
  "phone" : "0299999999",
  "mobile" : "0499999999",
  "email" : "joe.king@example.com",
  "status" : "enabled"
}

Example user XML response

<user>
  <loginName>DEMO</loginName>
  <fullName>Joe King</fullName>
  <phone>0299999999</phone>
  <mobile>0499999999</mobile>
  <email>joe.king@example.com</email>
  <status>enabled</status>
 </user>

Custom fields

Use custom fields to store extra information about your customers or transactions. 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 or conduct a transaction you can send values for your custom fields.

To set up custom fields:

  1. Sign in to PayWay
  2. Click Settings
  3. Click 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

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)

Example custom field JSON response

{
  "customFieldId" : 2,
  "fieldName" : "Membership Type",
  "help" : "e.g. junior, senior, social",
  "required" : true,
  "hidden" : false
}

Example custom field XML response

<customField>
  <customFieldId>2</customFieldId>
  <fieldName>Membership Type</fieldName>
  <help>e.g. junior, senior, social</help>
  <required>true</required>
  <hidden>false</hidden>
</customField>

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

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

Field Notes
keyName Use for logging.
key The secret API key.
Treat your secret API key like a password.

Example API key JSON response

{
  "keyName": "T10000_SEC...1A4",
  "key": "T10000_SEC_RANDOM_RANDOM_RANDOM_1A4"
}

Example API key XML response

<apiKey>
  <keyName>T10000_SEC...1A4</keyName>
  <key>T10000_SEC_RANDOM_RANDOM_RANDOM_1A4</key>
</apiKey>

Modules

PayWay is made up of modules which you can buy.

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

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

Example modules JSON response

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

Example modules XML response

<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>
            <fraudGuard>false</fraudGuard>
        </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/docs/rest.html#resources"/>
    </links>
</modules>

payway.js

To use payway.js, add this <script> at the end of the <body>.

<script src="https://api.payway.com.au/rest/v1/payway.js">
</script>

Use payway.js to add a PayWay iframe containing credit card or bank account fields to your page.

For step-by-step instructions, see Trusted Frame tutorial.

You must not host payway.js on your server.

payway.createCreditCardFrame

To create a PayWay iframe containing credit card fields:

payway.createCreditCardFrame( options, [createdCallback] )

options has these properties:

Property Notes
publishableApiKey Required. See API Keys
container The id of a <div> which will hold the PayWay iframe. Default is payway-credit-card
cvnRequired true if you will process a payment immediately. false if you will save the credit card
style Allows you to set CSS styles inside the iframe. See style.
layout Defines how the fields are arranged. 'wide' (the default) or 'narrow'. See layout.
height The height of the iframe in px. You may not specify a height if you have specified a layout.
width The width of the iframe in px. You may not specify a width if you have specified a layout.
tokenMode Defines how PayWay will pass the token to you. 'post' (the default) or 'callback'. See tokenMode.
onValid Function to be called when credit card fields become valid. See onValid Event.
onInvalid Function to be called when credit card fields are no longer valid. See onInvalid event.
threeDS2 true if you wish to use EMV 3-D Secure Version 2.

Example call to createCreditCardFrame for server rendered app

payway.createCreditCardFrame({
    publishableApiKey: '{publishableApiKey}',
    onValid: function() { console.log('valid'); },
    onInvalid: function() { console.log('invalid'); }
});

Example call to createCreditCardFrame for single page app

var createdCallback = function( err, frame ) {
      if ( !err ) {
        // TODO: Add event handler which calls frame.getToken
      }
};
payway.createCreditCardFrame({
    publishableApiKey: '{publishableApiKey}',
    onValid: function() { console.log('valid'); },
    onInvalid: function() { console.log('invalid'); },
    tokenMode: 'callback'
}, createdCallback );

style

To set CSS styles inside the iframe pass a style object as a property of options.

The properties of the style object are CSS selectors, for example:

Property (CSS Selector) Notes
div.payway-card Entire form
.payway-card label Input labels
.payway-card input Input fields
.payway-card legend Expiry label
.payway-card select Expiry select

Each property value is an object specifying one or more CSS styles as shown in the example.

Example of style object for credit card iframe

var style = {
    'div.payway-card' : { 'background-color': '#404040',
                          'border-radius': '0em' },
    '.payway-card label' : { 'color' : 'white' },
    '.payway-card legend': { 'color' : 'white' },
    '.payway-card input' : { 'color' : '#202020' },
    '.payway-card select': { 'color' : '#202020' }
};

layout

Defines how the fields are arranged.

Frame created with layout:'wide':

Screenshot of credit card form, using the wide format

Frame created with layout:'narrow':

Screenshot of credit card form, using the narrow format
layout Notes
wide Arrange the fields in a wide format. Sizes the frame at 370 x 226 px. Use this if your page does not need to fit on a mobile phone screen.
narrow Arrange the fields in a narrow format. Sizes the frame at 278 x 306 px. Use this if your page must fit on a mobile phone screen.

tokenMode

Defines how PayWay will pass the token to you.

tokenMode Notes
post PayWay will add an onSubmit event handler to the form containing the iframe. When the form is submitted PayWay will:
  • get the single use token representing the credit card details
  • add a hidden field named singleUseTokenId
  • POST the form to your server
callback You must write a createdCallback function to setup event handlers which call frame.getToken.

onValid event

This event occurs when fields in the iframe become valid.

Use this to enable submission of the form.

No arguments are passed to your function.

onInvalid event

This event occurs when fields in the iframe are no longer valid.

Use this to disable submission of the form.

No arguments are passed to your function.

payway.createBankAccountFrame

To create a PayWay iframe containing bank account fields:

payway.createBankAccountFrame( options, [createdCallback] )

options has these properties:

Property Notes
publishableApiKey Required. See API Keys
container The id of a <div> which will hold the PayWay iframe. Default is payway-bank-account
style Allows you to set CSS styles inside the iframe. See style.
height The height of the iframe in px.
width The width of the iframe in px.
tokenMode Defines how PayWay will pass the token to you. 'post' (the default) or 'callback'. See tokenMode.
onValid Function to be called when bank account fields become valid. See onValid Event.
onInvalid Function to be called when bank account fields are no longer valid. See onInvalid event.

Example call to createBankAccountFrame for server rendered app

payway.createBankAccountFrame({
    publishableApiKey: '{publishableApiKey}',
    onValid: function() { console.log('valid'); },
    onInvalid: function() { console.log('invalid'); }
});

Example call to createBankAccountFrame for single page app

var createdCallback = function( err, frame ) {
      if ( !err ) {
        // TODO: Add event handler which calls frame.getToken
      }
};
payway.createBankAccountFrame({
    publishableApiKey: '{publishableApiKey}',
    onValid: function() { console.log('valid'); },
    onInvalid: function() { console.log('invalid'); },
    tokenMode: 'callback'
}, createdCallback );

style

To set CSS styles inside the iframe pass a style object as a property of options.

The properties of the style object are CSS selectors, for example:

Property (CSS Selector) Notes
div.payway-account Entire form
.payway-account label Input labels
.payway-account input Input fields

Each property value is an object specifying one or more CSS styles as shown in the example.

Example of style object for bank account iframe

var style = {
    'div.payway-account' : { 'background-color': '#404040',
                             'border-radius': '0em' },
    '.payway-account label' : { 'color' : 'white' },
    '.payway-account input' : { 'color' : '#202020' }
};

createdCallback

To be notified when the iframe is ready and get a frame object, pass a callback function as the second argument to createCreditCardFrame or createBankAccountFrame.

Your callback function will be called with err and frame arguments.

err

undefined if no error occurred. Otherwise:

Property Notes
message Error message
status HTTP status code from attempt to contact PayWay server
statusText HTTP status text from attempt to contact PayWay server

frame

The second argument is a PayWay frame object. This indicates the iframe has been added to the DOM, contents loaded and is ready for user input. If you are using tokenMode: callback you should:

  • store the frame object
  • when the user submits the form, call frame.getToken( tokenCallback )
  • call frame.destroy() when you no longer need the frame

The frame object has these functions:

Function Notes
getToken Get a single use token representing the credit card or bank account details. See frame.getToken.
destroy Remove the PayWay iframe and event listeners. See frame.destroy.

frame.getToken

To get a single use token representing the credit card or bank account details in the PayWay iframe:

frame.getToken( tokenCallback )

When you call getToken( tokenCallback ):

  • the credit card or bank account details are sent directly to the PayWay server
  • tokenCallback is called with a single use token representing the credit card or bank account
  • if an error occurs, tokenCallback is passed details of the error
To get a frame object, write a createdCallback function.

Example frame.getToken( tokenCallback )

var tokenCallback = function( err, data ) {
  if ( err ) {
    console.log( 'error=' + err.message );
  } else {
    console.log( 'token=' + data.singleUseTokenId );
    // TODO: Send token to your server via AJAX
  }
};
// frame was second argument to createdCallback
frame.getToken( tokenCallback );

tokenCallback

To receive the single use token, pass a callback function as the first argument to getToken.

Your callback function will be called with err and data arguments.

err

undefined if no error occurred. Otherwise:

Property Notes
message Error message
status HTTP status code from attempt to contact PayWay server
statusText HTTP status text from attempt to contact PayWay server

data

These properties will be undefined if an error occurred.

Property Notes
singleUseTokenId A token issued by PayWay which holds credit card details.
paymentMethod creditCard or bankAccount
creditCard If creditCard, customer's credit card.
bankAccount If bankAccount, customer's direct debit bank account.

creditCard

These fields are returned under the creditCard field when the customer is paying by credit card:

Field Notes
maskedCardNumber Masked credit card number.
expiryDateMonth Two digit expiry month.
expiryDateYear Two digit expiry year.
cardScheme visa, mastercard, unionpay, amex, diners, eftpos or jcb.
cardType credit or debit if cardScheme is visa or mastercard.
cardholderName The name printed on the card.
surchargePercentage The percentage to be applied to principal amount to calculate payment amount.
threeDS2AuthRequired true if you are required to send 3-D Secure authentication details to PayWay.

bankAccount

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

Field Notes
maskedBsb The masked bank-state-branch holding their account.
maskedAccountNumber The masked account number at that branch.
accountName Name of account holder.
surchargeAmount Dollar amount added to principal amount to calculate payment amount.

payway.createChallengeFrame

To create a 3-D Secure Version 2 challenge frame:

payway.createChallengeFrame( options, createdChallengeCallback )

You should only create a challenge frame after you receive an authentication response with a transStatus of C.

options has these properties:

Property Notes
publishableApiKey Required. See API Keys
singleUseTokenId Required. This is the singleUseTokenId you used when performing 3-D Secure authentication.
container The id of a <div> which will hold the challenge iframe. Default is payway-challenge
challengeWindowSize The size of the iframe to be created, see challengeWindowSize. Default is full screen.
challengeMode Defines how PayWay will pass the token to you. 'post' (the default) or 'callback'. See challengeMode.
onSuccess Function to be called when the cardholder passes the challenge
onFailure Function to be called when the cardholder fails to pass the challenge

Example call to createChallengeFrame for server rendered app

<!DOCTYPE html>
<html>
  <body>
    <!-- This form will POST the transStatus (challenge outcome) to your server -->
    <form action="/challenge-result" method="post">
      <div id="payway-challenge"></div>
    </form>
    <script src="https://api.payway.com.au/rest/v1/payway.js">
    </script>
    <script type="text/javascript">
      payway.createChallengeFrame({
        publishableApiKey: '{publishableApiKey}',
        singleUseTokenId: '2bcec36f-7b02-43db-b3ec-bfb65acfe272',
        challengeWindowSize: '05'
      });
    </script>
  </body>
</html>

Example call to createChallengeFrame for single page app

var createdChallengeCallback = function( err, frame ) {
  if ( !err ) {
    // TODO: iframe has been created. Hide spinner, etc.
  }
};
payway.createChallengeFrame({
    publishableApiKey: '{publishableApiKey}',
    singleUseTokenId: '2bcec36f-7b02-43db-b3ec-bfb65acfe272',
    challengeWindowSize: '02',
    challengeMode: 'callback',
    onSuccess: function() { console.log('challenge success, process payment'); },
    onFailure: function() { console.log('challenge failure, show error message'); },
}, createdChallengeCallback );

challengeWindowSize

To set the size of the challenge window, pass challengeWindowSize as a String property of options.

challengeWindowSize Pixels
'01' 250 x 400
'02' 390 x 400
'03' 500 x 600
'04' 600 x 400
'05' Full screen

challengeMode

Defines how PayWay will pass the challenge result to you.

challengeMode Notes
post When the challenge is completed PayWay will:
  • add a hidden field named transStatus
  • POST the form to your server
callback When the challenge is complete, PayWay will call either onFailure or onSuccess callbacks.
post

When you receive the POST to your server, you should read the transStatus parameter

If transStatus is Y or A then the cardholder is authenticated, you should send a request to:

Send parameter threeDS2 set to true.

If transStatus is any other value, you should display a web page indicating that authentication has failed. Do not take a payment, create a customer or update a customer.

onSuccess

This event occurs when the cardholder passes the challenge.

You should:

  1. destroy the challenge frame
  2. Use the singleUseTokenId to take a payment or create a customer or update a customer

Send parameter threeDS2 set to true.

onFailure

This event occurs when the cardholder fails the challenge.

You should:

  1. destroy the challenge frame
  2. Display an error message to the cardholder and allow them to try a different credit card

frame.destroy

To remove the PayWay iframe and listener events:

frame.destroy()

Call this when the credit card, bank account or challenge iframe is no longer required by your single page application.

Example call to frame.destroy

// frame was second argument to `createdCallback`
frame.destroy();
frame = null;

payway.createPaymentRequestButton

To create an Apple Pay and/or Google Pay button:

payway.createPaymentRequestButton( options, [paymentSheetCompletedCallback] )

options has these properties:

Property Notes
publishableApiKey Required. See API Keys
container The id of a <div> which will hold the button(s). Default is payway-payment-request-button
googleMerchantId Required if you wish to create a Google Pay button. Your Google-provided Merchant ID, obtained from the Google Pay Business Console.
principalAmount Required. The amount of the payment before any surcharge is added.
currency aud
buttonMode Defines how PayWay will pass the token to you. post (the default) or callback.

Example call to createPaymentRequestButton for server rendered app

payway.createPaymentRequestButton({
    publishableApiKey: '{publishableApiKey}',
    googleMerchantId: '{googleMerchantId}',
    principalAmount: 100.00,
    currency: 'aud'
});

Example call to createPaymentRequestButton for single page app

var paymentSheetCompletedCallback = function( err, data ) {
  if ( !err ) {
    // TODO: Send data.singleUseTokenId to your server.
  }
};
payway.createPaymentRequestButton({
    publishableApiKey: '{publishableApiKey}',
    googleMerchantId: '{googleMerchantId}',
    principalAmount: 100.00,
    currency: 'aud',
    buttonMode: 'callback'
}, paymentSheetCompletedCallback);

paymentSheetCompletedCallback

To be notified when your customer has confirmed the payment with their wallet provider, pass a callback function as the second argument to createPaymentRequestButton.

Your callback function will be called with err and data arguments.

err

undefined if no error occurred. Otherwise:

Property Notes
message Error message
status HTTP status code from attempt to contact PayWay server
statusText HTTP status text from attempt to contact PayWay server

data

Property Notes
singleUseTokenId A single use token. Send this to your server.
walletType applePay or googlePay.

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.

Do not use in a live facility. Use only with merchantId of TEST.
Card Number Security Code Expiry Response
4564710000000004 847 02/29 08 Visa Credit Approved
4564030000000007 847 02/30 08 Visa Debit Approved
5163200000000008 070 08/30 08 Mastercard Credit Approved
5163610000000008 847 02/30 08 Mastercard Debit Approved
2221000000000009 009 01/30 08 Mastercard Approved
6226880000000000 453 11/25 08 UnionPay Approved
6226880000000018 453 11/25 05 UnionPay Declined
4564710000000012 963 02/25 54 Visa Expired
4564710000000020 234 05/30 51 Visa Low Funds ($10 credit limit)
5163200000000016 728 12/29 04 Mastercard Stolen
4564710000000046 123 06/25 08 Visa High Funds ($99,999,999.99 credit limit)
5163200000000040 321 09/25 08 MasterCard High Funds ($99,999,999.99 credit limit)
376000000000006 2349 06/30 08 American Express Approved
343400000000016 9023 01/29 62 American Express Declined
36430000000007 348 06/32 08 Diners Club Approved
36430000000015 988 08/31 43 Diners Club Stolen
3530000000000003 573 10/25 00 JCB Approved
3530000000000011 573 10/25 05 JCB Declined

Test bank accounts

Use the following bank accounts for testing.

The account name does not matter.

Do not use in a live facility. Use only with yourBankAccountId of 0000000A.
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 successful.

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.

Cross-Origin Resource Sharing

You may not call the PayWay REST API using Ajax.

To send credit card or bank account details from the browser to PayWay, implement the Trusted Frame solution. Using an iframe provides additional security and minimises your PCI-DSS scope.

If a resource requires your secret key, send the request from your server. For security, only your server is allowed to take payments, process refunds, download receipt files, etc.

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 process one-time payments using a single use token, you must have the PayWay Net module.

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.

You can contact us to add a 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

The server has not found anything matching the Request-URI.

The response body may contain more information.

Example 404 JSON response

{
  "data" : [ {
    "fieldName" : "transactionId",
    "message" : "Invalid transaction id.",
    "fieldValue" : "99999999"
  } ]
}

Example 404 XML response

<errors>
  <data>
    <error>
      <fieldName>transactionId</fieldName>
      <message>Invalid transaction id.</message>
      <fieldValue>99999999</fieldValue>
    </error>
  </data>
 </errors>

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.

410 Gone

The server no longer has the resource.

This occurs if you attempt to download a receipts file which is no longer available. For transactions older than 365 days sign in and download the Monthly Settlement or Yearly Settlement reports.

415 Unsupported media type

The server can not process the content type which was provided, or the request is not allowed to have any content.

See:

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.

You must not rely on specific wording. We may change the wording of error messages without notification.

Example 422 JSON response

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

Example 422 XML response

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

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

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:-

  • your client number
  • 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).
Never email your secret API key. Email is not secure.

Example 500 JSON response

{
  "errorNumber" : 1,
  "traceCode" : "403686"
}

Example 500 XML response

<error>
  <errorNumber>1</errorNumber>
  <traceCode>403686</traceCode>
</error>

501 Not implemented

The server does not recognise 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:-

  • your client number
  • 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.
Never email your secret API key. Email is not secure.

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 a list of common response codes see:

Contact us

For sales, help and technical support contact us.

Disclaimer

The information contained in this publication is provided for learning purposes only and is subject to change. Revisions may be issued from time to time that encompass changes or additions to this module.

This is a guide only and it is not comprehensive. It does not impinge on or overrule any formal arrangement you may enter into with the Bank. The Bank and its officers shall not have any liability for any losses of any kind incurred in connection with any action, inaction or decision taken in reliance on the information herein or for any inaccuracies, errors or omissions. In this publication references to the "Bank" are to Westpac Banking Corporation ABN 33 007 457 141 and to any of its operating Divisions, including BankSA and St.George.