PayWay REST API

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

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:

Quick start

• For test API keys get a free PayWay test facility
• This API is RESTful
• The base URL is https://api.payway.com.au/rest/v1
• Send your API key as the HTTP Basic Auth username. Leave the password blank.
• Send x-www-form-urlencoded parameters in PUT and POST requests
• You can request JSON or XML formatted responses
• Responses contain links to related resources, such as the next page of results
• Duplicate POSTs can be avoided using an Idempotency-Key header
• You must implement error handling based on HTTP response codes
• Transactions, customers and receipts files are the most important resources
• To avoid processing credit card details on your server, use single use tokens.
• CORS is not supported

Read next:

• Basics of sending requests and processing responses
• Trusted Frame tutorial or Trusted Frame (SPA) tutorial
• Resources.

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

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.

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:

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

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

If you receive any other response code, you should log the response code and response body. See: HTTP Response Codes.

Links and pagination

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.

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.

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.

Enter these card details:

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:

• Avoiding duplicates
• Handling errors
• Protecting your site from card testing

You may also wish to:

• Process payments using stored details
• Style the credit card frame
• Add bank accounts
• Update credit card or bank account for an existing customer.

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.

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.

Enter these card details:

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.

Step 6: Improve your solution

You must now improve your solution by:

• Avoiding duplicates
• Handling errors
• Protecting your site from card testing

You may also wish to:

• Process payments using stored details
• Style the credit card frame
• Add bank accounts
• Update credit card or bank account for an existing customer.

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.

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:

6. Press Send
7. 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:

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

2. Replace {secretApiKey} with your Secret API Key
3. Save the file as payway-curl-config.txt

Step 4: Download a receipts file

To download a receipts file:

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

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

Step 5: Download yesterday's receipts file

Linux

To download yesterday's receipts file using Linux:

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

Windows Powershell

To download yesterday's receipts file using Windows Powershell:

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

Step 6: Save a receipts file to the current folder

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

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

Step 7: Improve your solution

You may now improve your solution by:

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

• cURL Documentation

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

2. Replace {secretApiKey} with your Secret API Key
3. Save the file as payway-curl-config.txt

Step 4: Upload a payment file

To upload a payment file:

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

Step 5: Improve your solution

You may now improve your solution by:

• 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

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:

• take a one-time payment using credit card details entered into a PayWay trusted frame, your mobile app or provided by a third-party wallet provider
• take payments using the credit card or bank account stored against a customer
• reserve money on a credit card by processing a pre-authorisation and later process a capture to charge the credit card
• void a transaction to cancel it prior to settlement
• refund a credit card, bank account direct debit or direct credit payment
• search and get details of transactions, regardless of how they were originally processed.

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:

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

Avoid duplicate payments

To avoid processing duplicate payments:

• send a unique Idempotency-Key header
• if you receive a network error, resend the request with the same Idempotency-Key
• if you receive 500 Internal Server Error, contact Technical Support
• if you receive 503 Service Unavailable, the payment has not been processed. Wait 20 seconds and resend the request with a new idempotency key. Contact Technical Support if you continue to experience problems.

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:

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:

Verify a stored card

To verify a credit card stored against a customer:

POST /transactions

You must send:

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:

Process pre-authorisation

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

POST /transactions

You must send:

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:

Merchant ID

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

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:

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:

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:

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:

Get transaction details

To get details of a transaction:

GET /transactions/{transactionId}

Transactions model

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

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.

Credit card

These fields are returned under the creditCard field:

Customer bank account

These fields are returned under the bankAccount field:

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:

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:

Australia Post

This field is returned under the australiaPost field:

BPAY

This field is returned under the bpay field:

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:

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:

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:

In the same request, you may also send:

• regular schedule of payments
• contact details
• custom fields
• notes.

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:

In the same request, you may also send:

• contact details
• custom fields
• notes.

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:

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:

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:

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:

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:

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:

The response is the new virtual account.

Close a virtual account

To close a virtual account:

PATCH /customers/{customerNumber}/virtual-account

Send this field:

Update settlement for virtual account

To update the settlement account used for a virtual account:

PATCH /customers/{customerNumber}/virtual-account

Send this field:

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:

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.

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:

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

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

Customer contact details

The customer's contact details:

Customer custom fields

The customer may have values for custom fields:

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.

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:

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

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:

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

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:

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

Virtual account status

Single use tokens

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

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

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

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.

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.

Send these fields:

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:

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:

• Authentication Purpose: the reason for authenticating the card, and your merchant facility
• Purchase Information: the amount and frequency of intended payments
• Merchant Risk Indicator: fields to allow the risk of the transaction be to calculated
• Cardholder Contact Details: email and phone numbers for your customer
• Billing Address: your customer's billing address
• Shipping Address: the address where you will ship physical goods
• Cardholder Account: information about the cardholder's account on your website

Use your secret API key.

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

Authentication Purpose

Send these fields when authenticating a credit card:

Purchase Information

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

Merchant Risk Indicator

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

Cardholder Contact Details

Send these fields when authenticating a credit card:

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.

Shipping Address

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

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:

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

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.

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:

• take a payment or
• create a customer or
• update a customer

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:

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.

Get payment file

To get the status of a payment file:

GET /payment-files/{fileName}

The following fields are returned:

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:

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:

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:

Detail rows:

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:

• Westpac MTS
• Cardlink
• St.George IPG
• Batch Advantage Upload

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

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

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

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.

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:

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

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

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

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

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

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.

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

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.

payway.createCreditCardFrame

To create a PayWay iframe containing credit card fields:

payway.createCreditCardFrame( options, [createdCallback] )

options has these properties:

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:

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

Frame created with layout:'narrow':

tokenMode

Defines how PayWay will pass the token to you.

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:

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:

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:

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:

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

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:

data

These properties will be undefined if an error occurred.

creditCard

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

bankAccount

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

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:

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.

challengeMode

Defines how PayWay will pass the challenge result to you.

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:

• take a payment or
• create a customer or
• update a customer

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:

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:

data

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.

Test bank accounts

Use the following bank accounts for testing.

The account name does not matter.

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:

• Sending Fields for PUT, POST and PATCH
• Uploading Files.

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.

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

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.

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:

• Credit Card Response Codes
• Direct Debit Response Codes.

Contact us

For sales, help and technical support contact us.