Integrating with SecurePay

Getting started with SecurePay is quick and easy, and there are multiple ways you can integrate based on your needs. You also have the chance to test your integration after signing up for an account. SecurePay provides you with a sandbox version, allowing you to freely test SecurePay on your website for as long as you’d like before starting with a live account.
The methods in which you can integrate with SecurePay include SecurePay API, e-Commerce extensions and other methods such as XML, SecureFrame, SecureBill and more.
To find out more on each of the integration methods available, click on the links below.
SecurePay API
Other integration methods
e-Commerce extensions
SecurePay API

The SecurePay API allows you to take payments on your web site in a PCI DSS compliant manner whilst retaining a much greater degree of control over the look & feel than is possible with other payment integrations.
Getting started

Obtaining a SecurePay test account

To obtain your test credentials, you must first create an account with SecurePay. If you’d like to do this now, follow this link to the SecurePay home page and sign up for free.
After entering your details, you’ll be given a clientId , a clientSecret and a merchantCode .
These are your test credentials, which you can use to explore SecurePay API’s functionality and integration for free before you start trading.
Giving SecurePay API a test run

Along with your clientId and your clientSecret , you will also have been issued a merchantCode , which you will need to access the sandbox environment where SecurePay can be tested.
To test the SecurePay API and get a feel for how everything works, simply have your credentials ready and access the sandbox environment .
Setting up your live account

Once you’re ready, you can return to your SecurePay account and apply for your merchant account/facility.
After approval, you’ll receive a welcome email providing access to your merchant portal.
After logging in, you’ll notice an activated status letting you know that you’re all set up and ready to integrate our API onto your live site! You will also find your live clientSecret .
SecurePay will use this to confirm data exchanges (sensitive information) with you as a merchant, so keep it safe and secure!
Environment details

To consume SecurePay API you will need an accessToken to authenticate, refer to the authentication section for more information.
Environment Base URL Sandbox https://payments-stest.npe.auspost.zone https://payments.auspost.net.au
Authentication

Overview

SecurePay API uses the OAuth 2.0 protocol for authentication and authorization. Your client application requests an access token from the Authorization Server , and sends the token as part of the Authorization Header to the SecurePay API resource that you want to access.
OAuth 2.0 is used by the world’s largest digital organisations, and it is currently the most secure and technologically advanced protocol of its kind. It uses fast-expiring access tokens that can only be utilised for specific resources by applications. This greatly mitigates the risk of “man-in-the-middle” attack and data breaching.
Client Credentials

For security reasons, do not retrieve a new “access_token” for every API call. Any “access_token” granted as part of this API is valid for a duration of 24 hours. Refer to response field “expires_in” for more details.
Example code to obtain an access token:
curl -X POST \
  https://welcome.api2.sandbox.auspost.com.au/oauth/token \
  --header 'Authorization: Basic xxxxxxxx' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.payments.auspost.com.au'
    "access_token": "eyJraWQiOiJJTzdwOUxNcEd0NBlLLV80Q192SFUyaUFvcGJoMXNZQ0JCOTV5cEthVzBJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkFSdUVqbmdlcmJFWHZ1M1ZEMGMzZjNjWDM3OWJzZzhzeElmTmZXNUttSGsiLCJpc3MiOiJodHRwczovL2Rldi00MjQ4ODMub2t0YS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNTYwNDAyMjQ0LCJleHAiOjE1NjA0ODg2NDQsImNpZCI6IjBvYW9rYXp4eTB2OEs5UGRVMzU2Iiwic2NwIjpbImh0dHBzOi8vYXBpLnBheW1lbnRzLmF1c3Bvc3QuY29tLmF1L3BheWhpdmUvbWFuYWdlLWFjY291bnRzL3JlYWQiLCJodHRwczovL2FwaS5wYXltZW50cy5hdXNwb3N0LmNvbS5hdS9wYXloaXZlL21hbmFnZS1hY2NvdW50cy93cml0ZSJdLCJzdWIiOiIwb2Fva2F6eHkwdjhLOVBkVTM1NiJ9.Zsv-NGEIUOOucmFl4_a2-E_Kd9GrlRuWvzwwYoU2s8C84PE1dFUzAIoXAs29jPYL3Ceu4t_TtKbm92VG_Oyd85-_pk7nYIli-1SxNSHwIcF8bNMV-mNngXEhjLA_Qm6eT-Ydj6k8Ww47XiDa8fYz48FMmi6f4zU44sEPL3wbNsPTIYEcQxzyO8gPpiKHn-74Gc7XVmFRAKngHr-3WrySevS8CzTlxdk3YJG60LHaivsXoAQ0vaREe4SaTwjlIaxLqfqVihG0B4o4dOlI9pT8gfhTfyb2QnTcyD16uQlUJuXGzlTZmg57mTwNeKmyFAAsOqKTITie-arizOIAtXqb2Q",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "https://api.payments.auspost.com.au/payhive/payments/read https://api.payments.auspost.com.au/payhive/payments/write https://api.payments.auspost.com.au/payhive/payment-instruments/read https://api.payments.auspost.com.au/payhive/payment-instruments/write"
 Authentication URL 
Environment
Sandbox
https://welcome.api2.sandbox.auspost.com.au/oauth/token
https://welcome.api2.auspost.com.au/oauth/token
 Header Parameters 
Parameter
Required
Description
Authorization
Required
HTTP Basic Auth header containing your client id and client secret (issued during the on-boarding process). Refer to HTTP Basic Auth for more information.
Content-Type
Required
Should be set to application/x-www-form-urlencoded.
 Request Parameters 
Parameter
Required
Description
grant_type
String
Required
The grant_type parameter must be set to client_credentials.
audience
String
Required
The audience parameter must be set to https://api.payments.auspost.com.au.
Do not parse the response access_token (JWT) on your server side. This is in order to minimise impact should anything change inside the JWT.
 Response 
Description
access_token
String
The access token string as issued by the server. Access_token issued will have permission to invoke all SecurePay API operations.
token_type
String
Type of token - bearer
expires_in
Integer
The duration of time in seconds the access token is granted for.
scope
String
The scopes assigned to the client
Card Payments
Overview
SecurePay API lives on your website as a customisable User Interface (UI) Component that securely captures customer card details so that payments can be made safely.
Unlike other payment services which will take customers off your website entirely, SecurePay provides a "UI Component" which is embedded on your web page.
While we do use a iframe to achieve this, our functionality is entirely customisable. 
The website owner still retains absolute control over the look and feel of the page.
This means that you can customise your payments page exactly how you wish, maintaining total control of your customer experience while leaving the card security (PCI-DSS) and complexity to us.
UI Component:
Your PCI footprint
Any business that deals with card information is subject to compliance obligations in order to maintain security to a universal standard. 
This universal standard is referred to as being PCI-DSS compliant. 
If your website hosts payment fields, you are within PCI scope. 
This has several implications for your business, but in summary, it means that you must continuously prove yourself PCI-DSS compliant and live up to a very high security standard.
However, by using the SecurePay integration method, you can minimize your PCI scope significantly. 
This is because customer card details never actually touch your system, absolving you of any security obligations that you would otherwise be subject to.
This integration method keeps your data secure, reducing your PCI scope without sacrificing the customer end-to-end experience.
Customer payment card data will be handled with consideration to the PCI DSS requirements applicable to SecurePay API as a service provider.
Adding the UI Component
<!-- Include the SecurePay UI Component. -->
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
<!-- Configure the UI component. -->
<script type="text/javascript">
      var mySecurePayUI = new securePayUI.init({
        containerId: 'securepay-ui-container',
        scriptId: 'securepay-ui-js',
        clientId: 'YOUR_CLIENT_ID',
        merchantCode: 'YOUR_MERCHANT_CODE',
        card: { // card specific config options / callbacks
            onTokeniseSuccess: function(tokenisedCard) {
              // card was successfully tokenised
              // here you could make a payment using the SecurePay API (via your application server)
            onTokeniseError: function(errors) {
              // error while tokenising card 
</script>
To add the SecurePay UI Component, include the JavaScript client library and configure the component as shown in the example code. 
The UI component will render a card capture form, which you can use capture the data from your users in a PCI DSS compliant way.
How it works
(1) The SecurePay UI Component should be initialised on the merchant website within the customer browser. See Javscript SDK - Configuration Object for more information on configuration options.
(2) Once the user has entered their card details, the UI Component's tokenise method needs to be called by the merchant website.
In ddc mode tokenise method should be called after onDCCQuoteSuccess was invoked and customer selected a payment option.
(3) Card information will be tokenised by the SecurePay API.
(4) Tokenised card response is returned to the SecurePay UI Component.    
(5) On successful tokenisation, the onTokeniseSuccess will be invoked which includes a token.
 Please note that the card token generated is temporary and expires after 30 minutes. This token is a once-off usage token for one successful payment. To make token reusable, please use the Store Payment Instrument endpoint.
(6) (Optional)  To utilise 3DS2, upon successful tokenisation, SecurePay's 3DS2 Javascript should be loaded and initialised and callbacks are configured. See 3DS2 Javascript - SDK
(7) (Optional) Trigger the 3DS2 Authentication process
(8) (Optional) Handle the authentication response. 
(9) Merchant server should make use of the token to make a payment to SecurePay API. You must make this payment request from your server. (Optional) For payment authenticated with 3DS2, pass the Order Id initiated in Step 6.
Send the following HTTP request to SecurePay API to make an anonymous payment:
POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST 
    -H "Content-Type: application/json"
    -H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "merchantCode": "YOUR_MERCHANT_CODE", 
          "amount": 10000, 
          "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
          "ip": "127.0.0.1"
A successful payment will receive a response similar to the following:
HTTP/1.1 201 Created
CORRELATION-ID: efa12a94-7dd6-4078-a033-7b47aa7dc616
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "amount": 1000,
    "status": "paid",
    "bankTransactionId": "7002157044",
    "customerCode": "anonymous",
    "merchantCode": "AAA000DM000",
    "ip": "127.0.0.1",
    "token": "994634932354242",
    "orderId": "efa12a94-7dd6-4078-a033-7b47aa7dc616"
(10) SecurePay API will process the anonymous payment and return a payment response
(11) Merchant server should proxy the payment response back to the merchant website so that an appropriate response can be returned to the customer browser. 
JavaScript SDK
Environment Details
Environment
SecurePay UI JavaScript SDK URL
Sandbox
https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js
https://payments.auspost.net.au/v3/ui/client/securepay-ui.min.js
Please note: Consumers of SecurePay UI must not host the script (SecurePay UI JavaScript SDK) themselves. 
How does it work?
<!doctype html>
    <form onsubmit="return false;">
      <div id="securepay-ui-container"></div>
      <button onclick="mySecurePayUI.tokenise();">Submit</button>
      <button onclick="mySecurePayUI.reset();">Reset</button>
    </form>
    <script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
    <script type="text/javascript">
      var mySecurePayUI = new securePayUI.init({
        containerId: 'securepay-ui-container',
        scriptId: 'securepay-ui-js',
        clientId: 'YOUR_CLIENT_ID',
        merchantCode: 'YOUR_MERCHANT_CODE',
        card: { // card specific config and callbacks
            onTokeniseSuccess: function(tokenisedCard) {
              // card was successfully tokenised
        onLoadComplete: function() {
            // the SecurePay UI Component has successfully loaded and is ready to be interacted with
    </script>
  </body>
</html>
To use the SecurePay UI JavaScript SDK, simply:




    

include the JavaScript client library
add a container element for the UI Component
configure the UI Component
The securepay-ui.min.js client library should be included in your HTML source as shown in the sample code:
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
The script adds a securePayUI object to the global scope.
Please note: the securepay-ui.min.js script should only be included once on your page. 
The SecurePayUI object has a single public function init which requires a UI Config object as its only argument:
var mySecurePayUI = new securePayUI.init({ ... });
This is where you pass your clientId and other configuration information. 
See UI Config Object for more information.
The SecurePay UI Component is inserted into the containerId DOM element when configured correctly.

An error message will be shown in the browser console if the configuration object is invalid.
Public Methods
  <button onclick="mySecurePayUI.tokenise();">Submit</button>
  <button onclick="mySecurePayUI.reset();">Reset</button>
Two functions are available on the CardPayment object after the UI Component has been created:
securePayUI.tokenise()
securePayUI.reset()
These commands are sent to the UI Component using the HTML5 window.postMessage API.
mySecurePayUI.tokenise() will the following action:
tokenise a new card
mySecurePayUI.reset() will clear the card form fields in Checkout and Add Card view modes.
UI Config Object
<!doctype html>
    <form onsubmit="return false;">
      <div id="securepay-ui-container"></div>
      <button onclick="mySecurePayUI.tokenise();">Submit</button>
      <button onclick="mySecurePayUI.reset();">Reset</button>
    </form>
    <script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
    <script type="text/javascript">
      var mySecurePayUI = new securePayUI.init({
        containerId: 'securepay-ui-container',
        scriptId: 'securepay-ui-js',
        clientId: 'YOUR_CLIENT_ID',
        merchantCode: 'YOUR_MERCHANT_CODE',
        card: {
            allowedCardTypes: ['visa', 'mastercard'],
            showCardIcons: false,
            onCardTypeChange: function(cardType) {
              // card type has changed
            onBINChange: function(cardBIN) {
              // card BIN has changed
            onFormValidityChange: function(valid) {
              // form validity has changed
            onTokeniseSuccess: function(tokenisedCard) {
              // card was successfully tokenised or saved card was successfully retrieved 
            onTokeniseError: function(errors) {
              // tokenization failed
        style: {
          backgroundColor: 'rgba(135, 206, 250, 0.1)',
          label: {
            font: {
                family: 'Arial, Helvetica, sans-serif',
                size: '1.1rem',
                color: 'darkblue'
          input: {
           font: {
               family: 'Arial, Helvetica, sans-serif',
               size: '1.1rem',
               color: 'darkblue'
        onLoadComplete: function () {
          // the UI Component has successfully loaded and is ready to be interacted with
    </script>
  </body>
</html>
Option
Required
Description
containerId
string
The HTML element id where the UI Component is to be inserted
string
Supported modes are checkout and dcc. 
Default mode is the checkout mode, it allows payment in AUD currency.
dcc mode provides customers with an option to pay in a currency of the card used for payment. Read more in about dcc mode in Dynamic Currency Conversion section.
scriptId
string
The HTML <script> element id which references securepay-ui.min.js
clientId
string
Your client id
merchantCode
string
Required if you have multiple merchant codes associated with your account
card-object
Specify card specific configuration options and callbacks
style
style-object
Override default styles (background-color, font-size, font-weight, color)
checkoutInfo
checkout-info-object
Conditional
Should be present for in dcc mode.
Card Object
Option
Required
Description
allowedCardTypes
string[]
Specify which card types are allowed e.g. [visa, mastercard, amex, diners]
showCardIcons
boolean
Whether card type icons should be shown (false by default)
Style Object
Option
Required
Description
backgroundColor
string
Configure the backgroundColor of the UI component. Eg: white #FFFFFF
label
style-element-object
Configure the fontFamily fontSize color of the label form fields.
input
style-element-object
Configure the fontFamily fontSize color of the input form fields.
Style Element Object
Option
Required
Description
font-object
Configure the styling for the fontobject of the element.
Font Object
Option
Required
Description
family
string
Configure the font-family of the font for the element. Eg: "Times New Roman", Times, serif
string
Configure the font-size of the font for the element. Eg: 1.25em 12px 10pt
color
string
Configure the color of the font for the element. Eg: white #FFFFFF
Checkout Info Object
Option
Required
Description
orderToken
string
Conditional
Should be present for in dcc mode. A JWT token from Order Details.
Dynamic Currency Conversion
Example of UI Component configured for dcc mode 
<!doctype html>
    <form onsubmit="return false;">
      <div id="securepay-ui-container"></div>
      <button onclick="mySecurePayUI.tokenise();">Submit</button>
      <button onclick="mySecurePayUI.reset();">Reset</button>
    </form>
    <script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
    <script type="text/javascript">
      var mySecurePayUI = new securePayUI.init({
        containerId: 'securepay-ui-container',
        scriptId: 'securepay-ui-js',
        mode: 'dcc',
        checkoutInfo: {
            orderToken: 'YOUR_JWT_TOKEN_FOR_THIS_ORDER'
        clientId: 'YOUR_CLIENT_ID',
        merchantCode: 'YOUR_MERCHANT_CODE',
        card: {
            allowedCardTypes: ['visa', 'mastercard'],
            showCardIcons: false,
            onCardTypeChange: function(cardType) {
              // card type has changed
            onBINChange: function(cardBIN) {
              // card BIN has changed
            onFormValidityChange: function(valid) {
              // form validity has changed
            onDCCQuoteSuccess: function(quote) {
              // dynamic currency conversion quote was retrieved 
            onDCCQuoteError: function(errors) {
              // quote retrieval failed  
            onTokeniseSuccess: function(tokenisedCard) {
              // card was successfully tokenised or saved card was successfully retrieved 
            onTokeniseError: function(errors) {
              // tokenization failed
        style: {
          backgroundColor: 'rgba(135, 206, 250, 0.1)',
          label: {
            font: {
                family: 'Arial, Helvetica, sans-serif',
                size: '1.1rem',
                color: 'darkblue'
          input: {
           font: {
               family: 'Arial, Helvetica, sans-serif',
               size: '1.1rem',
               color: 'darkblue'
        onLoadComplete: function () {
          // the UI Component has successfully loaded and is ready to be interacted with
    </script>
  </body>
</html>
Dynamic Currency Conversion (DCC) is a process in which your customers can make payments on their credit card in the card’s billing currency.




    

When your customers choose to pay in their own currency For security reasons, do not retrieve a new “access_token”, they lock in the exchange rate at the time of transaction and it remains the same for the lifecycle of the payment. 
Please note: to use the Dynamic currency conversion feature merchants must successfully enable this through their account.
Supported currencies are: USD, EUR, NZD, GBP, IDR, CRC, COP, BRL, JMD, ZAR, PHP, ARS, INR, AED, CLP, TTD, UYU, MXN, GYD, HKD, GTQ, JPY, SGD, CHF, NOK, MYR, BBD, TZS, QAR, CAD.
Supported card types are: Visa and Mastercard.
Once your customer enters ten digits of their card number, the dynamic currency conversion quote will be retrieved by the SecurePay UI Component. 
If a quote is available for the card currency, exchange rate details are displayed to the customer. 
Customer can choose whether to pay in AUD or in the card currency.
The view of UI Component is slightly different depending on card type, see the examples below.
Example for Visa card
Example for Mastercard card
Prior to loading the UIComponent, a payment order should be initiated by calling Initiate Payment Order from merchant server. 
orderToken should be passed from merchant server to merchant website and used to configure UI Config Object.
With DCC tokenise method should be called after onDCCQuoteSuccess was invoked
and Tokenised Card Object will always contain DCC Quote Object.
If your customer chooses to pay in their card’s issued currency which is not AUD, then the converted object in DCC Quote Object will contain foreign currency and amount to charge the customer.
If customer chooses option to pay in AUD, then base field will be present. In this case merchant should charge customer with AUD amount and currency. 
DCC receipt format
The DCC transaction receipt must adhere to the below requirements.
(1) Must say "Original Transaction Amount" and amount must have AUD prefix
(2) Must say "FX Rate 1 AUD" and show currency code and exchange rate that was returned in Tokenised Card Object in dccQuote.converted.currency and dccQuote.converted.exchangeRate.value fields respectively.
(3) Must say "Including X% margin", where X is taken from dccQuote.converted.exchangeRate.value field returned in Tokenised Card Object
(4) Must say "Final Transactional Amount". Must use foreign currency amount returned in amount field of Payment Object.
Must prefix the amount with foreign currency code, eg. USD taken from currency field of Payment Object.
(5) Must say verbatim "This currency conversion has been provided by Merchant Name. I have been offered a choice of currencies 
for payment including AUD and agree to pay in USD", using foreign currency code for this transaction (eg. USD). 
It is advised to develop this text as a parameter so it can easily be changed in the future.
Callbacks
...
onTokeniseSuccess: function(tokenisedCard) {
   console.log(tokenisedCard);
The UI Component sends messages to the client code when various events occur - such as a successful response being received
from a call to securePayUI.tokenise(). These events can be handled by adding callback handler functions to the UI Config object.
The following callbacks are available:
Global SDK Callbacks
Option
Description
onLoadComplete()
checkout, dcc
Invoked when the UI Component has loaded
onLoadError() - Deprecated
checkout, dcc
Invoked when the UI Component did not load successfully
Card SDK Callbacks
Option
Description
onCardTypeChange(cardType)
checkout, dcc
Invoked when card type changes. Returns the card type ('visa', 'mastercard', 'amex' or 'diners' or 'unknown' if type cannot be determined).
onCardBINChange(cardBIN)
checkout, dcc
Invoked when BIN changes. Returns the card BIN (Bank Identification Number).
onFormValidityChange(valid)
checkout, dcc
Invoked when card form validity state changes. Returns a boolean flag indicating form validity.
onDCCQuoteSuccess(dccQuoteDetails)
Could be invoked in dcc mode only. Invoked, when quote retrieval of dynamic currency conversion is successful. securePayUI.tokenise() should not be invoke prior receiving this callback, otherwise securePayUI.tokenise() call result in DCC_QUOTE_IN_PROGRESS error provided in onTokeniseError callback.
onDCCQuoteError(error)
Could be invoked in dcc mode only. Invoked, when quote retrieval fails, for instance when orderToken is invalid. securePayUI.tokenise() method should not be invoked until UI component is reinitialised with valid configuration details.
onTokeniseSuccess(tokenisedCard)
checkout, dcc
Invoked when card is successfully tokenised. Returns the Tokenised Card that was created.
onTokeniseError(error)
checkout, dcc
Invoked when card tokenization failed
Tokenised Card Object
Tokenise Card Object in checkout mode  
        "merchantCode": "YOUR_MERCHANT_CODE",
        "token": "520592516621111",
        "createdAt": "2021-07-23T13:00:53.128+10:00",
        "scheme": "visa",
        "bin": "411111",
        "last4": "111",
        "expiryMonth": "10",
        "expiryYear": "20"
Tokenise Card Object in dcc mode when customer chose to pay in card currency
        "merchantCode": "YOUR_MERCHANT_CODE",
        "token": "520592516621111",
        "createdAt": "2021-07-23T13:00:53.128+10:00",
        "scheme": "visa",
        "bin": "411111",
        "last4": "111",
        "expiryMonth": "10",
        "expiryYear": "20",
        "dccQuote": {
            "converted": {
                "currency": "USD",
                "amount": "1285",
                "exchangeRate": {
                    "value": "1.0946",
                    "markup": "3.50"
Tokenise Card Object in dcc mode when customer chose to pay in AUD
        "merchantCode": "YOUR_MERCHANT_CODE",
        "token": "520592516621111",
        "createdAt": "2021-07-23T13:00:53.128+10:00",
        "scheme": "visa",
        "bin": "411111",
        "last4": "111",
        "expiryMonth": "10",
        "expiryYear": "20",
        "dccQuote": {
            "base": {
                "currency": "AUD"
Description
merchantCode
If you're collecting payments on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant.
token
A tokenised payment instrument reference. Use this token in make payment call. Please note that the card token generated is temporary and expires after 30 minutes. This token is a once-off usage token for one successful payment. To make the token reusable, please use Store Payment Instrument endpoint.
createdAt
A timestamp when card was tokenised, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
scheme
A card scheme, e.g. visa, mastercard, diners, amex.
Bank identification number.
last4
The last 3 digits of the card number. (Please note the number of digits returned may vary due to the card scheme)
expiryMonth
Two digit number representing the card expiry month.
expiryYear
Two digit number representing the card expiry year.
dccQuote
Dynamic currency conversion quote, will be present in dcc mode only.
DCC Quote Object
Returned in dccQuote object in Tokenised Card Object
Description
base.currency
Present if customer chose to pay in AUD or conversion rate was unavailable. Supported value: AUD.
converted
Present if customer chose to pay in card currency which is not AUD, contains foreign currency and amount to charge the customer. Refer to Converted Object for field details.
DCC Quote Details Object
Returned on successful quote retrieval in onDCCQuoteSuccess callback
DCC quote details object 
       "base": {
           "currency": "AUD"
       "converted": {
           "currency": "USD",
           "amount": "1285",
           "exchangeRate": {
               "value": "1.0946",
               "markup": "3.50"
Description
base.currency
Contains the original currency for the order. Supported value: AUD.
converted
If present contains details of dynamic currency conversion rate that will be presented to the customer. See Converted Object for details.
Converted Object
Description
currency
Populated with card currency.
amount
Populated with converted amount in card currency in a lower denomination.
exchangeRate
Populated with Exchange rate.
Exchange rate object
Description
value
Exchange rate that was retrieved for a card currency.
markup
An agreed upon markup value added to the initial AUD amount before conversion, which is charged to the customer upon final payment.
Error Object
    {
      "errors": [
          "id": "1a909ec1-c96c-4ced-a471-d145a0e517ef",
          "code": "MIN_CONSTRAINT_VIOLATION",
          "detail": "must be greater than or equal to 1",
          "source": {
            "pointer": "amount"
Required
Description
Unique identifier for the error
Endpoint specific error code
detail
Detailed error description
source.pointer
If error is related to specific field in request this param will be populated with field name
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details. 
To make a payment, use this code:




    

POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST 
    -H "Content-Type: application/json"
    -H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
          "ip": "127.0.0.1", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "customerCode": "anonymous",
    "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "ip": "127.0.0.1",
    "amount": "10000",
    "currency": "AUD",
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Transaction successful"
Example of declined payment:
POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST 
    -H "Content-Type: application/json"
    -H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10051, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
          "ip": "127.0.0.1", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "amount": 10051,
    "currency": "AUD",
    "status": "failed",
    "bankTransactionId": "824565",
    "gatewayResponseCode": "51",
    "gatewayResponseMessage": "Not sufficient funds",
    "errorCode": "INSUFFICIENT_FUNDS",
    "customerCode": "anonymous",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "ip": "127.0.0.1",
    "token": "1117760467699043",
    "orderId": "6f3e0642-187d-46b3-9f9f-1af3d8e344a0"
Create Payment
Make a payment for a given card token.
Token for anonymous payments expires after 30 minutes.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Idempotency-Key
Optional
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, for AUD payments representing the total amount in cents to charge the provided (tokenised) payment instrument. For dynamic currency conversion payments this field should be set to the value of dccQuote.amount field provided in tokenise card object. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
currency
String
Optional
Payment currency. Default value is AUD. Non AUD payments are supported for dynamic currency conversion payments only. For dynamic currency conversion payments this field should be set to the value of dccQuote.currency field provided in tokenise card object.
orderId
String
Optional
A client order id, will be used as reference to the payment. If not provided, SecurePay API will assign a unique id for the order. Note: < > " characters are not allowed in orderId.
customerCode
String
Optional
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. This is used when you want to perform a payment against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used.
fraudCheckDetails
String
Optional
A payment fraud check details object.
dccDetails
Object
Optional
A dynamic currency conversion details object. Should be present for dynamic currency conversion payments.
threedSecureDetails
Object
Optional
A 3DS2 details Object. Required for payments authenticated with 3DS2.
Response
The Payment that was successfully created.
Refund Payment
Used to refund a previous payment. Can only be used for AUD transactions. 
For DCC transactions, only full refunds are supported and are only available via the SecurePay Merchant Portal.
To refund payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE",  
          "ip": "127.0.0.1"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "customerCode" : "anonymous",
    "amount": 10000,
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Approved"
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Path Variables 
Parameter
Description
orderId
A customer order id which was successfully processed previously and the merchant now wants to refund it.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to refund. The amount will be refunded to the same payment instrument from which the payment was made for the order. The amount value to be refunded should be less then or equal to the actual paid amount. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
 Response 
The Refund that was successfully created.
Create Account Verification Transaction
An account verification is a $0 transaction used to verify the card details and its validity without impacting the customer’s available funds.
To process an Account Verification transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/account-verification 
curl https://payments-stest.npe.auspost.zone/v2/payments/account-verification -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer XXXXXXXXXXXX"
    -D'{ "merchantCode": "YOUR_MERCHANT_CODE",
         "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
         "ip": "127.0.0.1",
         "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "ip": "127.0.0.1",
    "status": "success",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Transaction successful"
This transaction type is supported by Visa and Mastercard only and available on selected acquiring banks (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA). Refer to SecurePay’s website FAQs for more information.




    

 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/payments/account-verification
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the Account Verification transaction is processed against.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
orderId
String
Optional
A client order id, will be used as reference to the Account Verification. Note: < > " characters are not allowed in orderId.
fraudCheckDetails
Object
Optional
A account verification fraud check details object..
 Response 
The Account Verification that was successfully created.
Create PreAuth/InitialAuth Transaction
Used to pre-authorise a transaction against a token.
A pre-authorisation is used when wanting to reserve funds on a customer's credit card, which is generally held for five to ten business days. The time duration all depends on the cardholder's bank. During that time, you can “complete” the transaction to capture the funds. 
To perform a standard pre-authorisation where you will only have the option of capturing the funds, is by passing PRE_AUTH in the preAuthType parameter field of the request.
For merchants that do not know the final amount when the transaction begins, they can process an initial authorisation transaction. An initial authorisation transaction is a flexible pre-authorisation that allows you to increase or decrease the actual amount when it’s known. You can process an initial authorisation transaction by passing INITIAL_AUTH in the preAuthType parameter field of the request. Please note initial authorisation is supported by Visa and Mastercard only, available on selected acquiring banks (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA) and can be used by merchants in certain industry categories. Refer SecurePay’s website FAQs for more information.
To process a pre-auth/initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "preAuthType": "INITIAL_AUTH",
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
          "ip": "127.0.0.1", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "ip": "127.0.0.1",
    "amount": "10000",
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Transaction successful"    
To capture a standard pre-auth or initial-auth transaction please go to Capture PreAuth/InitialAuth Transaction.
If you would like to increase or cancel an approved initial-auth transaction, please go to Increase InitialAuth Transaction / Cancel InitialAuth Transaction
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
preAuthType
String
Optional
This parameter defines which type of pre-authorisation is performed. Supported types are PRE_AUTH and INITIAL_AUTH. Default value is PRE_AUTH.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
orderId
String
Optional
A client order id, will be used as reference to the payment.  Note: < > " characters are not allowed in orderId.
customerCode
String
Optional
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. This is used when you want to perform a pre-auth payment against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used.
fraudCheckDetails
Object
Optional
A preAuth fraud check details object.
threedSecureDetails
Object
Optional
A 3DS2 details Object. Required for payments authenticated with 3DS2.
 Response 
The PreAuth Payment that was successfully created.
Increase InitialAuth Transaction
Used to increase an initial-auth transaction, using its order id.
Increment can't occur after a capture or a full cancellation has already been made. 
To Increase an initial-auth  transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/increase
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/69d49ae5-a6f5-4627-8f7d-8f736011d028/increase -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1",
          "amount": 5000
     "createdAt": "2020-07-16T14:26:07.401+10:00",
     "amount": 5000,
     "status": "paid",
     "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
     "gatewayResponseCode": "00",
     "gatewayResponseMessage": "Transaction successful",
     "merchantCode": "YOUR_MERCHANT_CODE",
     "ip": "127.0.0.1",
     "orderId": "564966e8-2d7d-4bce-b0ed-33f26d751ba5"
Used to increase a pre-authorisation transaction of type INITIAL_AUTH only.
NOTE:
Preauth-Increments are only available on Visa or Mastercard and on selected (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA) acquiring banks and can be used by merchants in certain industry categories. Refer to the SecurePay website FAQs for more information.
For Visa transactions an Increase InitialAuth Transaction request will result in an amount increase only, it will not affect the validity period of the authorisation. The amount passed in an Increase InitialAuth Transaction request should be greater than zero for Visa transactions.
For Mastercard transactions an Increase InitialAuth Transaction request will result in an amount increase and extension of the validity period. To extend the validity period for Mastercard transactions only, you will have to pass a zero value in the amount field of the request.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/increase
Path Variables
Parameter
Description
orderId
The order id used for pre-auth payment.
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
merchantCode
String
Required
Merchant account for which the funds are collected.
amount
Integer
Required
An integer value greater than or equal to 0, representing the increase amount. Refer to note section for more details. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
Response
The Increase PreAuth Payment Object that was successfully increased.
Cancel InitialAuth Transaction
Used to cancel an initial-authorisation transaction using its order id. 
Cancellation is always for the full or partial amount. Also cancellation can't occur after a capture or a full amount has already been cancelled. 
To cancel an initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/cancel
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/69d49ae5-a6f5-4627-8f7d-8f736011d028/cancel -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1",
          "amount": 5000
     "merchantCode": "YOUR_MERCHANT_CODE",
     "ip": "127.0.0.1",
     "orderId": "d2b65e49-e163-43ca-bd72-78dafsfe79-78g1d4c23",
     "amount": 5000,
     "gatewayResponseCode": "00",
     "gatewayResponseMessage": "Transaction successful"
Used to cancel pre-authorisation payment of type INITIAL_AUTH only.
NOTE:
Preauth-Cancellations are only available on Visa or Mastercard and on selected (NAB, ANZ*, Westpac Qvalent and Fiserv FDMSA) acquiring banks and can be used by merchants in certain industry categories. Refer to the SecurePay website FAQs for more information.
* The ANZ acquirer doesn’t currently support partial cancellations, only full cancellations can be made.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/cancel
Path Variables
Parameter
Description
orderId
The order id used for pre-auth payment.
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
merchantCode
String
Required
Merchant account for which the funds are collected.
amount
Integer
Optional
An integer value greater than 0, representing an amount in cents to cancel. If the amount field is not present, the full amount that is left of the initial-authorisation will be cancelled.  Refer to note section for more details. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
Response
The Cancel InitialAuth Payment Object that was successfully cancelled.
Capture PreAuth/InitialAuth Transaction
Used to capture a pre-authorisation transaction using its order id. This is applicable for both pre-auth types: PRE_AUTH and INTIAL_AUTH




    

A capture must be completed for the full amount of the pre-auth, it can't be less (partial capture) or more (over capture). 
Also capture can only be done once and can't occur after a cancellation has been made.
To capture a pre-auth/initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1"
     "createdAt": "2021-07-23T13:00:53.128+10:00",
     "merchantCode": "YOUR_MERCHANT_CODE",
     "ip": "127.0.0.1",
     "amount": 1000,
     "status": "paid", 
     "orderId": "d2b65e49-e163-43ca-bd72-78dafsfe79-78g1d4c23",
     "bankTransactionId": "731627310",
     "gatewayResponseCode": "00",
     "gatewayResponseMessage": "Transaction successful"     
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture
 Path Variables 
Parameter
Description
orderId
The order id used for pre-auth payment.
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Note: The amount has to be equal to the pre-auth txn amount. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
 Response 
The Capture Payment Object that was successfully created.
Create Payment (Stored Payment Instrument)
To make payment for a customer, use this code:
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments -X POST
    -H "Content-Type: application/json"
    -H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
          "ip": "127.0.0.1", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "customerCode": "YOUR_CUSTOMER_CODE",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "amount": "10000",
    "currency": "AUD",
    "status": "paid",
    "ip": "127.0.0.1",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014"
Makes a payment for a logged in customer.
 HTTP Request 
Please note this endpoint is deprecated. You can now achieve the same functionality by passing the field `customerCode` in the create payment request endpoint. 
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments
 Path Variables  
Parameter
Description
customerCode
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Idempotency-Key
Optional
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key.
Content-Type
Required
Should be set to application/json.
 Request Parameters  
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
orderId
String
Optional
A client order id, will be used as reference to the payment.  Note: < > " characters are not allowed in orderId.
 Response 
The Payment that was successfully created.
Initiate Payment Order
Initiates a payment order. 
A Payment order has to be initiated prior making either a dynamic currency conversion (DCC) payment or a 3DS2 payment request.
The response from this request includes orderId required for Create Payment and orderToken required to retrieve a conversion rate by UI component (DCC) or to request 3DS2 authentication. The response for an 3DS2 order request will also include a threedSecureDetails object with fields required during 3DS2 Authentication i.e. providerClientId, sessionId & simpleToken.
Note that orderToken expires after 10 minutes.
To create a payment order, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate
curl https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer XXXXXXXXXXXX"
    -D'{ "merchantCode": "YOUR_MERCHANT_CODE",
         "amount": 10000, 
         "ip": "127.0.0.1",
         "orderReference": "Your reference for this order",
         "orderType": "DYNAMIC_CURRENCY_CONVERSION"
    "ip": "127.0.0.1",
    "orderReference": "Your reference for this order",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "orderType": "DYNAMIC_CURRENCY_CONVERSION",
    "amount": 10000,
    "orderId": "2551d30c-250c-4d9d-afe6-3b6f2cab1ccf",
    "orderToken": "YOUR_JWT_TOKEN_FOR_THIS_ORDER",
    "createdAt": "2021-02-04T14:01:54.839+11:00"
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0 in AUD, representing the total amount in cents. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
Please note, for 3DS2 authentication payment order, amount should match the amount during authorisation.
orderType
String
Required
A type of the order to create. Currently supported types: DYNAMIC_CURRENCY_CONVERSION or THREED_SECURE.
orderReference
String
Optional
A client order reference, could  be used as reference to the order.
 Response 
The Order Details that was successfully created.
Create Payment Instrument
Allows management of tokenised payment instruments against organisation's users. This service does not directly manage the users (i.e. there is no "user" resource), that is left up to the consuming application. 
To store payment instrument, use this code:
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token -X POST
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -H "token: de305d54-75b4-431b-adb2-eb6b9e546014"
    -H "ip: 127.0.0.1"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "customerCode": "YOUR_CUSTOMER_CODE",
    "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "scheme": "visa",
    "bin": "424242",
    "last4": "242",
    "expiryMonth": "01",
    "expiryYear": "19"
Stores a tokenised payment instrument against a customer identifier within the organisation (the organisation identifier is derived from authentication credentials).
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
  Path Variables 
Parameter
Description
customerCode
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
token
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
 Response 
The Payment Instrument Object that was successfully created.
Payment Instruments
To retrieve payment instruments, use this code:
GET https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments -X GET 
     -H "Content-Type: application/json"
     -H "Authorization: Bearer xxxxxxxx"
     -H "ip: 127.0.0.1"
  "paymentInstruments": [
        "createdAt": "2021-07-23T13:00:53.128+10:00",
        "customerCode": "YOUR_CUSTOMER_CODE",
        "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "scheme": "visa",
        "bin": "424242",
        "last4": "242",
        "expiryMonth": "01",
        "expiryYear": "19"
Retrieves stored payment instruments from the vault for an identified customer.




    

 HTTP Request 
GET https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments
If you currently have sub-accounts within your main account with SecurePay, please be aware that in the near future, this API will return stored instruments associated to the provided customerCode across all your sub-accounts.
We kindly advise you to adjust your integration plans accordingly.
 Path Variables 
Parameter
Description
customerCode
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
 Response 
The current list of Payment Instrument Object that exist.
Delete Payment Instrument
To delete payment instrument, use this code:
DELETE https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token -X DELETE
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -H "token: de305d54-75b4-431b-adb2-eb6b9e546014"
    -H "ip: 127.0.0.1"
  "customerCode": "DE8482",
  "token": "1da87a11-4242-4163-883b-cded6d839a44",
  "deleted": true
Deletes a previously stored payment instrument from the vault.
 HTTP Request 
DELETE https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
 Path Variables 
Parameter
Description
customerCode
A unique (within your organisation) identifier of your customer.  Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
 Response 
Description
customerCode
String
A unique (within your organisation) identifier of your customer. This value is used for security to validate that the logged in customer owns the payment instrument that is to be deleted.
token
String
A tokenised payment instrument reference. This value uniquely identifies a payment instrument in the vault.
deleted
Boolean
Status of deleted record. This should have a value of true if the record was found and deleted or false if no record matches the request parameters.
Payment Objects
Payment Fraud Check Details Object
If FraudGuard rules needs to be applied before attempting the payment, fraudCheckType should be populated with FRAUD_GUARD value and relevant order details could be passed in the request. 
If the fraud check has been performed via FraudGuard or ACI Red Shield Fraud detection endpoints, the provider reference number of the fraud check result could be passed as a part of payment request.
Required
Description
providerReferenceNumber
String
Conditional
The provider reference number returned by FraudGuard or ACI Red Shield Fraud Detection Endpoints can be found in FraudGuard or ACI Red Shield Check Result Objects.
fraudCheckType
String
Conditional
If FraudGuard rules needs to be applied before attempting the payment, fraudCheckType should be populated with FRAUD_GUARD value.
customerDetails
Object
Optional
The Customer Details Object.
shippingAddress
Object
Optional
The Shipping Address Object.
billingAddress
Object
Optional
The Billing Address Object.
Dynamic Currency Conversion Details Object
Used for dynamic currency conversion payments. Should be passed in dccDetails of Create Payment request. 
Required
Description
initiatedOrderId
String
Required
Should be passed for dynamic currency conversion payments. Should be populated with dynamic conversion orderId returned in Payment Order Object
3DS2 Details Object
Used for payments with 3DS2. Should be passed in threedSecureDetails of Create Payment request and Create PreAuth/InitialAuth Transaction requests. 
Required
Description
initiatedOrderId
String
Required
Should be passed for payments with 3DS2. Should be populated with 3DS2 orderId returned in Payment Order Object
liabilityShiftIndicator
String
Optional
Optional field in Authorisation and Preauthorisation requests that is matched against the Liability Shift Indicator which SecurePay has stored from 3DS2 Authentication Response. If you do not include an LSI value in the authorisation or preauthorisation request and the liability has not shifted (i.e., you are liable), the transaction will be declined. 
Please note the LiabilityShiftIndicator field will be released in July 2023. You can update your integration in the meantime to send the field and the transaction will be processed as normal
Liability Shift Indicator
The purpose of this optional field in the authorisation/preauthorisation request is to:
(1) Provide control (and explicit acceptance) of whether to proceed with payments even if the 3DS2
authentication did not pass.
(2) Ensure that there has been no modification to the Liability Shift Indicator you receive in the
authentication outcome, and your decision to continue with payment (or cease the payment flow) is based
on correct authentication information.
Example #1: Your customer completes the 3DS2 authentication process and the Liability was not shifted,
which means you are liable for fraudulent chargebacks. Based on your business reasoning you want to
proceed with the payment, you must place a ‘N’ in the liabilityShiftIndicator field in the authorisation request
to acknowledge and accept the liability has not been shifted to allow the payment to proceed.
Example #2: Your customer completes the 3DS2 authentication process and the Liability was not shifted.
However, a malicious customer modifies the authentication outcome, and you receive an indicator that the
liability was shifted to the issuer. You proceed with the payment as you understood it was shifted (but you
are still liable for fraudulent chargebacks). As you have sent no value in the liabilityShiftIndicator field, the
payment is rejected, protecting you and your customer.
The LSI value in the authorisation request must match the Liability Shift Indicator value we have stored for
the Authentication outcome. This gives control of proceeding or not proceeding with unauthenticated
transactions.
To see more details on how the field is sent, please refer to the integration guide for your integration in the
developer resources on the SecurePay website.
Please refer to the table below for the transaction flow scenarios relating to the liabilityShiftIndicator field:
SecurePay: Liability shift indicator from Authentication Outcome
Merchant: Liability Shift Indicator Sent in Authorisation Request ‘liabilityShiftIndicator’
Result
Payment continues for processing
Payment continues for processing
Not Provided
Payment continues for processing
3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator
3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator
Not Provided
3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator
PreAuth/Account Verification Fraud Check Details Object
If the fraud check has been performed via FraudGuard or ACI Red Shield Fraud detection endpoints, the provider reference number of the fraud check result could be passed as a part of payment request.
Required
Description
providerReferenceNumber
String
Conditional
The provider reference number returned by FraudGuard or ACI Red Shield Fraud Detection Endpoints can be found in FraudGuard or ACI Red Shield Check Result Objects.
Payment Object
A completed payment returned by Create Payment and Create Payment(Stored payment instrument) 
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
token
String
The tokenised payment instrument that was used.
String
Client IP address.
amount
String
Total amount in cents that was charged to the tokenised payment instrument.
currency
String
Payment currency.
status
String
The status of the payment. Valid values are paid failed unknown. If the payment was processed and succeeded the status field in payload response is set to paid. If payment was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If payment was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason.
orderId
String
A client order id, will be used as reference to the payment.  Note: < > " characters are not allowed in orderId.
bankTransactionId
String
The payment transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank or payment was declined due to results of requested FraudGuard check this field is populated with error code representing reason of failure.
fraudCheckType
String
If payment request included FraudGuard check this field is populated with FRAUD_GUARD value.
fraudCheckResult
Object
If payment request included FraudGuard check this field is populated fraud check result. Refer to Fraud Check Result for more details.
Account Verification Transaction Object
A completed Account Verification transaction returned by Create Account Verification Transaction
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the Account Verification transaction is processed against.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
token
String
The tokenised payment instrument that was used.
String
Client IP address.
orderId
String
A client order id, will be used as reference to the Account Verification.  Note: < > " characters are not allowed in orderId.
status
String
The status of the payment. Valid values are success or failed. 
 If the verification was processed and succeeded, the status field in payload resonse is set to success. If the verification was processed but was failed, the status is set to failed and errorCode field is populated with error code related to reason of failure.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
PreAuth Payment Object
A completed payment returned by Create PreAuth/InitialAuth Transaction
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
token
String
The tokenised payment instrument that was used.
String
Client IP address.
amount
String
Total amount in cents that was charged to the tokenised payment instrument.
status
String
The status of the pre-auth/initial-auth transaction. Valid values are paid failed unknown. If the pre-auth/ initial-auth transaction was processed and successful the status field in payload response is set to paid. If the pre-auth/initial-auth transaction was processed but was declined, the status is set to failed and errorCode field is populated with error code related to reason of decline. If the pre-auth/initial-auth transaction was processed with unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason.
orderId
String
A client order id, will be used as reference to the payment.  Note: < > " characters are not allowed in orderId.
bankTransactionId
String
The payment transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
Cancel InitialAuth Payment Object
A initial-authorisation that was cancelled by Cancel InitialAuth Transaction.




    

Description
merchantCode
String
Merchant account for which the funds are collected.
String
Client IP address that was used.
amount
String
Total amount in cents that was cancelled.
orderId
String
A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
Capture Payment Object
A completed pre-authorisation capture returned by Capture PreAuth/InitialAuth Transaction.
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
String
Client IP address that was used.
amount
String
Total amount in cents that was charged to the tokenised payment instrument.
status
String
The status of the pre-auth/initial-auth capture payment. Valid values are paid failed unknown. If the pre-auth/initial-auth capture payment was processed and successful the status field in the payload response is set to paid. If the pre-auth/initial-auth capture payment was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If the pre-auth/initial-auth capture payment was processed with an unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason.
orderId
String
A client order id, will be used as reference to the payment.  Note: < > " characters are not allowed in orderId.
bankTransactionId
String
The payment transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
Increase PreAuth Payment Object
A completed payment returned by Increase InitialAuth Transaction
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
amount
String
Total amount in cents that was increased to the tokenised payment instrument.
status
String
The status of the transaction. Valid values are paid failed unknown . If the increase initial-auth transaction was processed and successful the status field in the payload response is set to paid. If the increase initial-auth transaction was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If the increase initial-auth transaction was processed with an unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason.
bankTransactionId
String
The payment transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
merchantCode
String
Merchant account for which the funds are collected.
String
Client IP address.
orderId
String
A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
Payment Order Object
A completed payment returned by Initiate Payment Order 
Description
createdAt
String
A timestamp when order was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
String
Client IP address.
amount
String
Total amount in cents for this order.
orderType
String
Payment order type.
orderId
String
A payment order id. For orders created with intent of dynamic currency conversion payments or 3DS2 payments, the value of this field should be passed in Create Payment request in dynamic currency conversion details object or 3DS2 Details Object respectively.  Note: < > " characters are not allowed in orderId.
orderToken
String
JWT token associated with created order. For orders created with intent of dynamic currency conversion payments, this values should be passed by UI component to retrieve exchange rate details. For orders with intent of 3DS2 payments, this value should be passed to initialise the 3DS2 JS SDK library in order to authenticate the request.
threedSecureDetails
Object
Field present only if orderType is THREED_SECURE. The 3DS2 Order Details Object.
3DS2 Order Details Object
A response section for 3DS2 Order details in Payment Order Object
Description
providerClientId
String
The client Id assigned to the merchant by the 3DS2 provider.
sessionId
String
A unique session id for an order.
simpleToken
String
A shortened authentication token. The token is used to authenticate calls from browser.
Payment Instrument Object
A customer payment instrument object created by Create Payment Instrument, but also
returned by Payment Instruments.
Description
createdAt
String
A timestamp when payment instrument was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
customerCode
String
A unique (within your organisation) identifier of your customer.
token
String
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform transactions.  Note: The token is same as the one passed in the request header.
scheme
String
A card scheme. e.g. visa, mastercard, diners, amex.. If the card scheme card type is not known to SecurePay API unknown value will be returned.
String
Bank identification number. i.e. The first 6 digit numbers of the card.  Note: Currently not supported. The field was added for future use.
last4
String
The last 3 digits of the card number. (Please note the number of digits returned may vary due to the card scheme)
expiryMonth
String
Two digit number representing the card expiry month.
expiryYear
String
Two digit number representing the card expiry year.
Refund Object
A completed refund returned by Refund Payment.
Description
createdAt
String
A timestamp when refund was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
amount
String
Total amount in cents that was refunded to the tokenised payment instrument. The amount value cannot be greater than previously processed order amount.
status
String
The status of the payment. Valid values are paid failed unknown. If the refund was processed and succeeded the status field in payload response is set to paid. If refund was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If refund was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason.
orderId
String
A client order id which is refunded, will be used as reference number. Note: < > " characters are not allowed in orderId.
bankTransactionId
String
The payment transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
Error Codes
For card payments, testing different response codes is configured by payment gateway. Most of the card payment made with cent values (e.g. $1.50 - 150 cents) in Test environment will trigger negative scenario which will result in payment failure. The example cent amount mentioned in `Test Data` is subset of data to test negative scenarios.
Full dollar amount (e.g. `1000`) and cent values of `1008` and `1511` can be used to test successful payments.
Example of declined payment error response:
HTTP/1.1 201 Created
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "amount": 10051,
    "currency": "AUD",
    "status": "failed",
    "bankTransactionId": "824565",
    "gatewayResponseCode": "51",
    "gatewayResponseMessage": "Not sufficient funds",
    "errorCode": "INSUFFICIENT_FUNDS",
    "customerCode": "anonymous",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "ip": "127.0.0.1",
    "token": "1117760467699043",
    "orderId": "6f3e0642-187d-46b3-9f9f-1af3d8e344a0"
Example of INVALID_ORDER_ID error response:
HTTP/1.1 400 Bad Request
  "errors": [
      "id": "3d5fb6a1-6ca3-4499-b8bc-3898d20945a9",
      "code": "INVALID_ORDER_ID",
      "detail": "Invalid request data"
Example of INVALID_ORDER_ID_FORMAT error response:
HTTP/1.1 400 Bad Request
    "errors": [
            "id": "af026c1e-0730-4313-b26f-fa857d061ebe",
            "code": "INVALID_ORDER_ID_FORMAT",
            "detail": "Invalid OrderId Format",
            "source": {
                "pointer": "orderId"
Example of authorization error response:
HTTP/1.1 401 Unauthorized
  "message": "Unauthorized"
Example of internal error response:
HTTP/1.1 500 Internal Server Error
  "errors": [
      "id": "3d5fb6a1-6ca3-4499-b8bc-3898d20945a9",
      "code": "GATEWAY_ERROR",
      "detail": "Internal error"
Example of gateway timed out error response:
HTTP/1.1 504 Gateway Time-out
    "errors": [
            "id": "b5807f7e-4adc-11ee-be56-0242ac120002",
            "code": "TIMED_OUT",
            "detail": "The request timed out"
 Payment Error Codes 
Payments endpoints uses the following error codes:
Response Code
Error Code
Originating System
Testable
Test Data
PAYMENT_DECLINED -- Payment declined
Payment Gateway
1005 or 1031 cents in amount field 
*Certain scenarios are not testable such as non-retriable declines
INSUFFICIENT_FUNDS -- Insufficient funds on payment instrument
Payment Gateway
1051 cents in amount field
EXPIRED_CARD -- Payment Instrument is expired
Payment Gateway
1033 cents in amount field
WITHDRAWAL_LIMIT -- Exceeds withdrawal amount limit
Payment Gateway
1061 cents in amount field
UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported
Payment Gateway
INVALID_CVV -- Invalid CVV number
Payment Gateway
LOST_OR_STOLEN_CARD -- Lost or stolen card
Payment Gateway
1007 cents in amount field
ACCOUNT_LOCKED -- Account is locked
Payment Gateway
WITHDRAWAL_LIMIT -- Exceeds withdrawal frequency limit
Payment Gateway
1065 cents in amount field
GATEWAY_ERROR -- The payment gateway was not able to process the request due to an unexpected error
Payment Gateway
1009 cents in amount field
BAD_REQUEST -- Bad request data
SecurePay API
INVALID_ACCOUNT -- Account has not been configured for card payments or requested payment feature
SecurePay API
INVALID_ORDER_ID -- Order id has to be unique per merchant
SecurePay API
send payment with an order id that was used by a previous payment
INVALID_ORDER_ID_FORMAT -- OrderId contains characters which are not allowed
SecurePay API
send an order id which contains any of these < > “ characters
TOKEN_NOT_FOUND -- Token does not exist
SecurePay API
send payment using a token which does not exist or does not belong to the customer
INVALID_MERCHANT_CODE -- Merchant Code is not listed in client account
SecurePay API
send payment with merchant not listed in account
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
send payment with an IP address that does not conform to the IPv4 or IPv6 standard
INVALID_AMOUNT -- Invalid amount for a payment
SecurePay API
send an amount that does not match the business rules for a specific operation (Eg: Different amount for pre-auth and capture pre-auth)
EXCEEDED_PREAUTH_AMOUNT -- Exceeded preauthorised amount
SecurePay API
send a partial or full cancel amount that exceeds pre-auth amount
INVALID_DCC_DETAILS -- No matching dcc order could be found for a payment request
SecurePay API
send payment using using initaitedOrderId that does not exist or was used by a previous payment
UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information.
SecurePay API
GATEWAY_ERROR -- Unexpected error while processing the request
SecurePay API
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
INVALID_TOKEN -- Token provided in payload is either already stored against some customer or does not exist in the system.
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
GATEWAY_ERROR -- Error while deleting payment instrument
Payment Gateway
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
 Refund Error Codes 




    

Refund endpoints uses the following error codes:
Response Code
Error Code
Originating System
Testable
REFUND_NOT_ALLOWED -- If refund amount is more than the previous paid order amount
Payment Gateway
INVALID_ACCOUNT -- Account has not been configured for card payments
SecurePay API
TRANSACTION_NOT_FOUND -- OrderId passed in refund request does not exist
Payment Gateway
BAD_REQUEST -- Bad request data
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
GATEWAY_ERROR -- Error while doing refund
Payment Gateway
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
 Tokenise Instrument Error Codes 
Tokenise endpoints uses the following error codes:
Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Send malformed JSON in request
SecurePay API
INVALID_ACCOUNT -- Account has not been configured for card payments
SecurePay API
INVALID_CVV -- Invalid CVV details
Payment Gateway
INVALID_PIN -- Invalid PIN details
Payment Gateway
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
DCC_QUOTE_IN_PROGRESS -- Could happen in dcc mode only. When tokenise call is made prior onDCCQuoteSuccess was invoked
SecurePay API
INVALID_FORM_DETAILS -- Could happen in dcc mode only. When tokenise call is made prior user entered all required fields or selected the Currency option.
SecurePay API
INVALID_ORDER_TOKEN -- Could happen in dcc mode only. When tokenise call is made after onDCCQuoteError callback invoked
SecurePay API
SYSTEM_ERROR -- Tokenise error from SecurePay API
SecurePay API
GATEWAY_ERROR -- Tokenisation error from Payment Gateway
Payment Gateway
INVALID_CARD_DETAILS -- Invalid card details (could be number, cvv, expiry date, mismatch of cc details)
Payment Gateway
PRE_AUTH_FAILED -- Pre-auth failed (could be cvv or any other reason, e.g. card blocked)
Payment Gateway
INVALID_REQUEST_DATA -- Invalid request data (e.g. Invalid IP address)
Payment Gateway
INVALID_ACCOUNT_DETAILS -- Invalid bank account details (bsb, account number, account name)
Payment Gateway
INSUFFICIENT_FUNDS -- Insufficient funds
Payment Gateway
EXPIRY_DATE -- Invalid expiry date
Payment Gateway
UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported
Payment Gateway
RESTRICTED_CARD_OR_ACCOUNT -- Restricted card or account
Payment Gateway
LOST_OR_STOLEN_CARD -- Lost or stolen card
Payment Gateway
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
Testing
You can use the following test card numbers in our sandbox environment.
Card Type
Card Number
4111111111111111
4242424242424242
MasterCard
5555555555554444
American Express
378282246310005
For dynamic currency conversion payments you can use card numbers starting with the BIN below numbers in our sandbox environment.
A DCC Quote retrieved only after 10 digits are typed in.
Currency
4242424242424242
triggers scenario when card currency is not in the list of supported currencies or AUD, results in payment in AUD currency.
4314261614350081
5139006234627198
5432500000000006
5253030000000000
4472010000000000
5303990000000005
5306950000000006
4073440000000002
4106750000000005
4600050000000001
5440140000000001
4196070000000009
4030860000000003
5486530000000008
4147900000000007
4406960000000007
5579050000000005
4791320000000007
4006700000000001
4518770000000005
5248050000000006
5240400000000001
5500180000000004
5269480000000009
4365110000000008
5476640000000007
4107340000000004
4301980000000001
5192900000000008
4757700000000002
3DS2 Testing
To test 3DS2 in the Sandbox environment, use Merchant Code of 5AR0055 when creating the 3DS2 payment order. You are not able to use your own Merchant Code and must use the Sandbox Test Merchant Code: 5AR0055. Please contact support at [email protected] if you need an alternate testing set up.
To use the test cards below you must use:
Merchant Code: 5AR0055 and associated credentials for authentication, as well as using 5AR0055 when creating a 3DS2 payment order
Card Holder Name: Test Card or an empty value
Expiry date (YYMM): value must either be 2508 or an empty value
The Merchant ID, cardholder name, and expiry date must be set as above otherwise the authentication will fail.
Test Cards:
Authentication Outcome
transStatus
Card Type
Card Number
Challenge password
Frictionless
4100000000000100
Frictionless
MasterCard
5100000000000107
Frictionless
340000000000108
Challenge
4100000000005000
123456
Challenge
MasterCard
5100000000005007
123456
Challenge
340000000005008
123456
Challenge failed
4100000000300005
111111
Per card scheme
Challenge failed
MasterCard
5100000000300002
111111
Per card scheme
Challenge failed
340000000300003
111111
Per card scheme
Unavailable
4100000000400003
Per card scheme
Unavailable
MasterCard
5100000000400000
Per card scheme
Unavailable
340000000400001
Per card scheme
Rejected
4100000000500000
Per card scheme
Rejected
MasterCard
5100000000500007
Per card scheme
Rejected
340000000500008
Per card scheme
Attempted
4100000000100009
Attempted
MasterCard
5100000000100006
Attempted
340000000100007
Apple Pay Payments
Overview
Apple Pay is a simple and secure way for your customers to pay with their Apple Wallet on SecurePay. It allows your customers to quickly pay you using their credit or debit card that is stored on their Apple device, eliminating the need to enter card details.  Each transaction is secured with Face ID, Touch ID or passcode.
Click here to learn more about Apple Pay.
Apple Pay is available on NAB, ANZ and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
Before implementing Apple Pay, please see the below links:
Acceptable Use Guidelines for Apple Pay on the web link.
Non Profit donation guidelines link.
How it works
Customers select Apple Pay when they want to check out. A payment sheet is shown to the customer, and they then authenticate using Face ID, Touch ID or passcode. The payment is then authorised by the card issuer.
On Apple Device
Initialise Session
1.1. Customer chooses to pay with Apple Pay by clicking Buy with Apple Pay button, then the browser makes Initiate Session call to your (merchant's) server.
1.2. Your server then sends the Initiate Session request to SecurePay API to initialise the Apple Pay session.
1.3. SecurePay API sends initialise session request to Apple Pay server.
1.4. Initialise session response returned to the customer browser.
Payment Authorisation
2.1. When customer authorises the Payment with Touch ID, Face ID or Passcode, encrypted payment data request is sent to Apple Pay from a device.
2.2. Apple Pay returns encrypted Payment Data.
2.3. Apple Device sends Payment Request with encrypted payment data to your server.
2.4. Your server sends Apple Pay Payment Request to SecurePay API.
2.5. Once the SecurePay API Processes the payment, response is sent back to your server.
Integration with Apple Pay
Integrating Apple Pay on your website is simple. You'll need to follow the instructions on using the Apple Pay JS API. 
You'll need to make sure you follow Apple's marketing guidelines found here.
Apple Pay Account setup
Your website must be using HTTPS. 
Integration of ApplePay and SecurePay does not require an Apple developer account.
You will, however need the Apple developer account to test your Apple wallet.
For more details please refer to the Testing section 
Note: An additional fee may be incurred for the enrolment and the use of an Apple developer account. This is charged directly to you via Apple.
Before you can start integrating with Apple Pay, you will need to register the domains you would like to use for Apple Pay. This can be done by logging in to your SecurePay Account.
Firstly, for your live account, you will need to complete domain verification. Apple requires you to verify that you own the domains you are registering to use with Apple Pay. You will have to host the  Domain Verification  file at this location https://{domain-name}/.well-known/apple-developer-merchantid-domain-association (where {domain-name} is your domain) and make sure the file is accessible over the internet.
For Sandbox account, you can skip above step and simply register the domains.
For Sandbox
To test your integration, you will need to log in to your SecurePay Account to generate and obtain your Apple Pay specific credentials.
In the test credentials section of SecurePay Account, select Sandbox Credentials - Apple Pay and follow on-screen instructions to configure Apple Pay in sandbox environment. Please note, your Sandbox Credentials - Apple Pay credentials are different to your existing test credentials and are unique to your Merchant Code. 
You must register the domains you would like to use for sandbox testing by selecting Configure Apple Pay Sandbox.
Later you will need these registered domains for Initiate Session Request.
For Live
You can activate Apple Pay from the Payment features tab by completing the instant application. 
In the application, follow the steps to verify ownership of your domains. You must register the domains you would like to use for your live payments.
Later you will need these registered domains for Initiate Session Request.
Your live credentials are the same as your existing live credentials.
On Safari Browser
This integration guide will help to integrate Apple Pay JS API
with your (merchant's) website.
Pre-requisite
Apple Pay Account setup, please follow the instructions here.
Your customer must have an Apple device with a supported iOS/macOS/iPadOS version and use the Safari browser. For more details please visit Apple Pay Availability by Region and Platform.
In order to use Apple Pay, a user also must first add a credit or debit card to their Apple wallet.
Technical Details
Initiate Session
Apple Pay Button on web
    <style type="text/css">
    /* CSS */
    .title {
        color: blue;
        text-decoration: bold;
        text-size: 1em;
    .author {
        color: gray;
    .apple-pay-button {
        display: inline-block;
        -webkit-appearance: -apple-pay-button;
        -apple-pay-button-type: buy; /* Use any supported button type like donate, plain. Refer https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons */
    .apple-pay-button-black {
        -apple-pay-button-style: black;
    .applePayButtonContainer {
      width: auto;
      height: auto;
      padding: 0;
      margin: 0;
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
    </style>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script>
    $(document).ready(() => {
        //1.1
        /*Check that the window.ApplePaySession class exists to ensure Apple Pay is supported and available in the browser.
        Then, call supportsVersion with the ApplePaySession that will be used (link in description for more details on supportVersion).
        Finally, call canMakePayments to ensure that the device is capable of making Apple Pay payments */
        //ApplePaySession.canMakePayments() this works only when https is enabled in server, please enable https in local server for development.
        if (ApplePaySession && ApplePaySession.canMakePayments()) {
            $('.unsupportedBrowserMessage').css('display', 'none');
            $('.apple-pay-button').css('display', 'block');
            console.log('Startup Check: Device is capable of making Apple Pay payments');
    function onApplePayButtonClicked() {
      console.log('Clicked Buy with Apple Pay');
    </script>
</head>
    <div class="unsupportedBrowserMessage" style="display: block;">
                    Your browser does not support Apple&nbsp;Pay on the web.<br>
                    To try this demo, open this page in Safari.<br>
                    (See <a href="#requirements">Requirements</a>.)
    <div class="applePayButtonContainer">
                    <a lang="us" id="overviewApplePayButton" class="apple-pay-button apple-pay-button-black" onclick="onApplePayButtonClicked()" title="Start Apple Pay"
                    role="link" tabindex="0" style="display: none;"></a>
</body>
</html>
Sample code for Apple Pay web integration




    

function onApplePayButtonClicked() {
        //1.1 session.begin() is called at last after initialising required callbacks
        //ref.1.2
        const paymentRequest = generatePaymentRequest();
        const session = new ApplePaySession(APPLE_PAY_VERSION, paymentRequest)
        //ref.1.3
        session.onvalidatemerchant = function (event) {
          //here you will be making a call to SecurePay API Initialise Session 
          const promise = requestApplePaySession();
          promise.then(function (session) {
            //ref.1.4
            session.completeMerchantValidation(session.sessionObject);
          }).catch(function (error) {
            //abort() will trigger oncancel handler where you can handle error
            session.abort();
            //here you can handle error
            return;
        //oncancel handler is called when UI is dismissed
        session.oncancel = (event) => {
          console.log("Session canceled called when UI is dismissed" + JSON.stringify(event))
        //ref.2.1/2.2
        session.onpaymentauthorized = function (event) {
            //ref.2.3 here you will be making a call to SecurePay API Payment Request
            mercahntApi.payment({
              //The event parameter contains the ApplePayPayment attribute.
              //Ref. https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypayment
              //Also, map this object with SecurePay Apple Pay Payment Api
              token: event.payment
            }, function (err, paymentResponse) {
              if (err) {
                //ref.2.5
                session.completePayment(session.STATUS_FAILURE);
                return;
                //ref.2.4
              session.completePayment(session.STATUS_SUCCESS);
              //Send payment data details to your server.
        //ref.1.1 This is important call to begin the session initialisation process
        session.begin();
        function generatePaymentRequest() {
              const  request = {
                countryCode: "AU",
                currencyCode: "AUD",
                merchantCapabilities: ["supports3DS"],
                supportedNetworks: ["masterCard", "visa"],
                total: {
                  amount: 100.00,
                  label: "The Cake Store",
                  type: "final"
              return request;
1.1. Before displaying Apple Pay as a payment option in your website, determine if the user’s device supports Apple Pay and respective version.
If it does then show Apple Pay Button.
Reference Links for integration of Apple Pay Button
Apple Pay Button 
Customising and styling the Apple Pay Button
Apple Pay Supported Version on the web
1.2. When the user taps the Apple Pay button, you need to call a JS function which will create a session object with PaymentRequest.
Here, you can set PaymentRequest to display your business name and the total amount. You can also collect information like billing details or shipping information.
See Apple’s documentation for full guidance on how to customize the payment request of ApplePaySession.
1.3. Then call session.begin() which 
will initiate Apple JS API Merchant Validation process.
1.3. Once you do call session.begin(), the browser will invoke session.onvalidatemerchant handler,
which must create a merchant session from your server by calling Initiate Session to SecurePay API.
For security reasons, your server must do this call, not your browser client code.
1.4. After the successful session response comes back, use response.sessionObject on completeMerchantValidation(sessionObject) 
to complete session.onvalidatemerchant() handler. 
1.5. The browser will then display the payment sheet where your customer needs to authorise the payment.
Initiate Payment after Authorisation
2.1. Next when your customer authorised the payment with Touch ID, Face ID or Passcode, onpaymentauthorized event handler is called on session object.
2.2. Here, you must implement the session.onpaymentauthorized handler,
that will be responsible for processing the payment transaction. Please follow the Apple Pay guidelines on the usage of onpaymentauthorized handler.
2.3. Your server then sends the Apple Pay Payment Request to SecurePay API.
Again for security reasons, your server must do this call, not your browser client code.
2.4. And lastly, after getting a Payment Response, call session.completePayment(..) with appropriate Status Code from ApplePaySession.
2.5. In case of error response, use STATUS_FAILURE with an array of associated ApplePayError objects.
Testing
Before you start, use merchant’s own credential by logging in to your SecurePay account. Please see these are separate clientId and secret from other Playground test credentials you might have.
Test Credit Cards are available at Apple Pay - Sandbox Testing - Apple Developer for testing. Also, SecurePay only supports Visa and Mastercard cards as of now.
The Apple Developer website provides the tools and information you need to make great apps for Apple platforms. If you’re new to development on Apple platforms, you can get started for free. Apple may charge additional fees for the developer account.
The steps to create the developer account are as follow:
You first have to accept this developer agreement by clicking this link accept the Apple Developer Agreement.
If you do not already have an Apple ID, click the link to create one.
You have successfully created an Apple developer account!
Please refer to Account - Help - Apple Developer for the complete guide to create an Apple developer account
Once developer account is created then apple developer account can be used to login to app store and connect to create your test account for ApplePay wallet - Sandbox Testing - Apple Pay.
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Initiate Session
Initiate Session API:
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate
Request:
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
      "domain": "cakebaking.com",
      "displayName": "Cake Store",
      "merchantCode": "MERCHANT_CODE",
      "ip": "127.0.0.1"
Response:
    "merchantCode": "MERCHANT_CODE",
    "ip": "127.0.0.1",
    "sessionObject": {...}
SecurePay initiates a session with Apple Pay. 
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
domain
String
Required
The merchant domain registered with Apple Pay and it must be the domain where customer is making a payment . Must not be longer than 255 characters.
displayName
String
Required
The merchant name that will be displayed to customer while authorising the payment. Must not be longer than 64 characters.
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
Response
Description
merchantCode
String
Merchant account for which the funds are collected.
String
A customer IP address. Must be a valid IPv4 or IPv6.
sessionObject
Object
Contains the object that was returned by Apple Pay. Should be passed by merchant to device as it is.
Apple Pay Payment
Apple Pay Payment API:




    

POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments
Request:
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
      "amount": 10000,
      "currrency": "AUD", 
      "merchantCode": "YOUR_MERCHANT_CODE", 
      "ip": "127.0.0.1", 
      "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
      "paymentData": {
        "encryptedData": "Szv0rBU1zE1cwbszivpKrWx...",
        "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQE",
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEJJak7jaMn7vzU...",
        "publicKeyHash": "7zbHcn1VIPU/+gfdlnglvsvnvfvscsd=",
        "transactionId": "1f2239b7ce042f736c5c9829f115ff2fc87a4b3dd518bfd83cadd6b765c785ac",
        "applicationData": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
Response:
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "amount": "10000",
    "currency": "AUD",
    "status": "paid",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Transaction successful",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "ip": "127.0.0.1",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
SecurePay supports only Visa and Mastercard cards as of now.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Idempotency-Key
Optional
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions within 12 hours. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key.
Request Parameters
Parameter
Required
Description
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
currency
String
Optional
Payment currency. Default value is AUD. If value is set, then it must be AUD.
orderId
String
Optional
A client order id, will be used as reference to the payment. Must be unique and no longer than 60 characters.
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
paymentData
Object
Required
Refer to PaymentData object details for more details.
Apple Pay Payment Data Object
Use event.payment.token.paymentData  of onpaymentauthorized Apple JS callback event to populate Payment Data object fields.
Parameter
Required
Description
encryptedData
String
Required
Encrypted payment data, set as paymentData.data.
signature
String
Required
Signature of the payment and header data, set as paymentData.signature
version
String
Required
Version information about the payment token, set as paymentData.version
ephemeralPublicKey
String
Required
Ephemeral public key bytes, set as paymentData.header.ephemeralPublicKey
publicKeyHash
String
Required
Hash of the X.509 merchant’s certificate, set as paymentData.header.publicKeyHash.
transactionId
String
Required
Transaction identifier, generated on the device. Set as paymentData.header.transactionId.
applicationData
String
Conditional
Set as paymentData.header.applicationData. Check if applicationData is being set, ref.1.2 of Session's Payment Request, if it is then this must be passed in Payment Request Api.
Response
Description
createdAt
String
A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
amount
Integer
An integer value greater than 0, representing the total amount in cents.
currency
String
Payment currency.
status
String
The status of the payment. Valid values are paid, failed, unknown. Refer to Payment transaction status for details.
bankTransactionId
String
The reference number to the order, issued by provider.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for Apple Pay payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
merchantCode
String
Merchant account for which the funds are collected.
String
Client IP address.
orderId
String
A client order id, will be used as reference to the payment.
Refund Apple Pay Payment
Used to refund a previous Apple Pay payment. Can only be used for AUD transactions. 
To refund Apple Pay payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE",  
          "ip": "127.0.0.1"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "amount": 10000,
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Approved"
 HTTP Request 
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Path Variables 
Parameter
Description
orderId
A customer order id which was successfully processed previously and the merchant now wants to refund it.
 Request Parameters 
Parameter
Required
Description
merchantCode
String
Required
Merchant account for which the funds are collected.
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to refund. The amount will be refunded to the same payment instrument from which the payment was made for the order. The amount value to be refunded should be less then or equal to the actual paid amount. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
 Response 
Description
createdAt
String
A timestamp when refund was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
String
Merchant account for which the funds are collected.
amount
String
Total amount in cents that was refunded to the payment instrument. The amount value cannot be greater than previously processed order amount.
status
String
The status of the refund. Valid values are paid failed unknown. If the refund was processed and succeeded the status field in payload response is set to paid. If refund was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If refund was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason.
orderId
String
A client order id which is refunded, will be used as reference number.
bankTransactionId
String
The refund transaction reference from the payment gateway.
gatewayResponseCode
String
Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments.
gatewayResponseMessage
String
Detailed message of the bank response code.
errorCode
String
If transaction was processed but declined by the bank this field is populated with error code representing reason of failure.
Payment Transaction Status
Status
Description
The payment has been successful.
failed
The payment has been failed.
unknown
The result of execution is not determined(e.g. due to connectivity issues).
Error Codes
SecurePay Apple Pay endpoints uses the following error codes:
Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Bad request data
SecurePay API
INVALID_REQUEST_DATA -- Invalid request data
SecurePay API
INVALID_REQUEST_DATA -- Unable to decrypt Payment Data
SecurePay API
INVALID_REQUEST_DATA -- Amount and Currency mismatch
SecurePay API
INVALID_APPLE_PAY_DETAILS -- DomainName is not registered with Apple Pay
SecurePay API
INVALID_ORDER_ID -- Order id has to be unique per merchant and must be no longer than 49 characters
SecurePay API
INVALID_ACCOUNT -- Account has not been configured for Apple Pay payments
SecurePay API
GATEWAY_ERROR -- Refund failure from Payment provider
Provider
UNAUTHORIZED -- Provided invalid Http access token. Refer to client credentials for more information.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
TRANSACTION_NOT_FOUND -- Order doesn't exist or not paid
SecurePay API
Direct Entry Payments
Overview
Direct Entry payments includes both direct debit and direct credit functionality. 
These transactions use the BSB and account number to charge a customer’s bank account (direct debit) or to send funds to a customer's bank account (direct credit). 
To be eligible to use direct debit, you must have an active direct debit or direct credit account with SecurePay.
Direct entry payments are not processed in real time; they are stored in SecurePay’s database and processed daily. 
Direct entry transactions can be viewed in the merchant portal.
Please note: SecurePay API Direct Entry endpoints can only be used for customer initiated payments. Direct Entry schedule payments can be created & managed in the merchant portal.
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Create Direct Entry Payment
Used to make direct debit and credit payments. 
To do direct entry payment, use this code:




    

POST https://payments-stest.npe.auspost.zone/v2/direct-entry
curl https://payments-stest.npe.auspost.zone/v2/direct-entry -X POST
    -H "Content-Type: application/json"
    -H "Authorisation: Bearer xxxxxxxx"
    -d '{ 
          "ip": "127.0.0.1",
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "orderId": "9fe4b0a848ac",
          "amount": 10000,  
          "paymentMethod": "DirectCredit",
          "bsb": "013457",
          "accountNumber": "123456789",
          "accountName": "Jane Doe",
    "orderId": "9fe4b0a848ac",
    "transactionId": "848403",
    "settlementDate": "2020-08-03",
    "amount": 10000,
    "merchantCode": "YOUR_MERCHANT_CODE",
    "paymentMethod": "DirectCredit",
    "bsb": "013457",
    "accountNumber": "123456789",
    "accountName": "Jane Doe",
    "ip": "127.0.0.1"
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/direct-entry
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4.
merchantCode
String
Required
Merchant account code for which payment is performed.
orderId
String
Required
A client order id, will be used as reference to the payment. Should not be longer than 18 characters. Supported characters are alphanumeric, ' '(blank space) and special characters: / - & . * ' .
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the account. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
String
Required
6-digit Australian bank-state-branch (BSB) number.
accountNumber
String
Required
The account number for the bank account. Should not be longer than 9 characters.
accountName
String
Required
The name of the person or business that owns the bank account. Should not be longer than 32 characters.
paymentMethod
String
Required
The type of payment. Supported values are DirectDebit and DirectCredit.
Response
Description
String
Client IP address.
merchantCode
String
Merchant account for which the funds are collected.
orderId
String
A client order id, will be used as reference to the payment.
transactionId
String
The payment transaction reference from the payment gateway.
amount
String
Total amount in cents that was charged to the account.
settlementDate
String
The settlement date of a successful payment.
paymentMethod
String
The type of payment performed. Values are DirectDebit and DirectCredit
String
6-digit Australian bank-state-branch (BSB) number.
accountNumber
String
The account number for the bank account.
accountName
String
The name of the person or business that owns the bank account.
Error Codes
Direct Entry endpoint uses the following error codes:
Response Code
Error Code
Originating System
Testable
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
DDA_NOT_FOUND -- The DDA was not found
Payment Gateway
BELOW_DDA_MIN_AMOUNT -- Amount is lower than the DDA min limit
Payment Gateway
EXCEEDED_DDA_MAX_AMOUNT -- Amount is higher than the DDA max limit
Payment Gateway
EXPIRED_DDA -- The DDA has expired
Payment Gateway
INVALID_ACCOUNT -- Account has not been configured for direct entry payments
Payment Gateway
UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
GATEWAY_ERROR -- Error while processing the request
Payment Gateway
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
PayPal Payments
How it works
Please note, this service is in alpha and not publicly available.
To include the PayPal button please refer to the PayPal Checkout Button Integration example.
1.1. When the user clicks on the PayPal button, it triggers the payment() callback function from the PayPal Button. In that method, you make a call to your server to make an Initiate PayPal Txn.
1.2. Your server then proxies the request to perform the Initiate PayPal Txn to SecurePay API.
2.1. Your server receives the Initiate PayPal Txn Response from SecurePay API which contains the paymentId.
2.2. Your app/web then receives the response in the payment() callback function, which then return the paymentId.
3.1. PayPal script loads the PayPal LightBox, where the user login and authorize the payment.
4.1. Once the user authorize the payment, the onAuthorize() callback function is called. You now have access to the payerId which is required for the next step. 
5.1. In the onAuthorize() function, you make a call to your server to make an Execute PayPal Txn to perform the payment. 
5.2. Your server then proxies the request to perform the Execute PayPal Txn. 
6.1. Your server receives the Execute PayPal Txn Response from SecurePay API.
6.2. Your app/web then receives the response in the onAuthorize().
7.1 PayPal will render the success/failure page based on the following callbacks onAuthorize,onCancel and onError. 
Sample code
Sample code for PayPal button web integration:
paypal.Button.render({
  env: 'sandbox',
  locale: 'en_AU',
  style: { size: 'responsive', color: 'silver', shape: 'pill', label: 'pay' },
  commit: true,
  payment: function() { // initiate payment
    return getPaymentId().then(function(paymentId) {
      console.log('SecurePay API responded with paymentId:', paymentId);
      return paymentId;
  onAuthorize: function(data, actions) { // execute payment
    console.log('Sending authorization request to SecurePay API with payerID:', data.payerID);
    return authorizePayment(data.payerID).then(function(response) {
      console.log('SecurePay API responded with data:', response);
}, '#paypal-button'); // element where paypal button will be injected
var amount = 5075;
var merchantCode = 'XXXXXXXXXXX';
var orderId = Date.now();
var ip = '127.0.0.1';
function getPaymentId() {
  return new Promise(function (resolve, reject) {
    var xhttp = new XMLHttpRequest();
    //Important this call is to the merchant server not SecurePay API 
    xhttp.open('POST', '/your-backend-api/paypal/initiate', true); // API proxies request through to SecurePay API: /v1/wallets/paypal/payments/initiate
    xhttp.setRequestHeader('content-type', 'application/json');
    xhttp.onload = function () {
      if (this.status == 200) {
        resolve(JSON.parse(xhttp.response).paymentId);
    xhttp.send(JSON.stringify({
      amount: amount,
      merchantCode: merchantCode,
      ip: ip,
      orderId: orderId
function authorizePayment(payerId) {
  return new Promise(function (resolve, reject) {
    var xhttp = new XMLHttpRequest();
    //Important this call is to the client server not SecurePay API
    xhttp.open('POST', '/your-backend-api/paypal/execute', true); // API proxies request through to SecurePay API: '/v1/wallets/paypal/payments/orders/orderId/execute'
    xhttp.setRequestHeader('content-type', 'application/json');
    xhttp.onload = function () {
      if (this.status == 200) {
        resolve(JSON.parse(xhttp.response));
    xhttp.send(JSON.stringify({
      amount: amount,
      merchantCode: merchantCode,
      ip: ip,
      orderId: orderId,
      payerId: payerId
This method adds a Paypal button to the client website, which when clicked, opens a PayPal lightbox overlaying the current webpage. It utilises PayPal's standard express checkout flow and code.
To implement this method, the client should:




    

1 - add the following PayPal script to their page:
<script src="https://www.paypalobjects.com/api/checkout.js"></script>
2 - add a div where the paypal button will be inserted:
<div id="paypal-button"></div>
3 - add the PayPal paypal.Button.render code snippet (as shown opposite).
The PayPal code snippet inserts the PayPal button into the DOM within the element specified. When the user clicks on this button, it triggers the payment() callback function to be called. 
This function expects a PayPal paymentId to be returned via a promise.
The paymentID is obtained via a call to SecurePay API's Initiate PayPal Transaction service API. 
The code example opposite: getPaymentId() provides an example of how this API call could be implemented using a Promise.
When the promise is resolved, and paymentId returned, the PayPal script loads the lightbox, where the user can login 
and authorise the payment.
Once the user is done, the onAuthorize() callback function is called automatically. 
Within this function a call should be made to SecurePay API's Execute PayPal Transaction 
service API to execute the payment.
The code example opposite: authorizePayment() provides an example of how this API call could be implemented 
using a Promise. 
Note: the payerID is obtained from the input parameter to onAuthorize() and sent in the POST request to the SecurePay API.
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Initiate PayPal Transaction
To initiate PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate
curl https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
          "paymentType": "sale",
          "noShipping": true,
          "billingDescription": "text displayed to buyer",
          "redirectUrls": {
            "successUrl": "http://<success url>",
            "cancelUrl": "http://<cancel url>"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "customerCode": "anonymous",
    "ip": "127.0.0.1",
    "amount": "10000",
    "paymentUrl": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-2B968028MX02434E",
    "paymentId": "EC-2B968028MX02434E",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "paymentType": "sale",
    "noShipping": true
Initiates a PayPal express checkout transaction. 
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate
 Header Parameters 
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
merchantCode
Required
Merchant account for which the funds are collected.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Required
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
orderId
Optional
A client order id, will be used as reference to the payment.
paymentType
Optional
This parameter defines what kind of PayPal transaction you are initiating. Supported type is sale. sale is used for a once-off payment. Default is set to sale.
noShipping
Optional
Defines if shipping address will be made visible when customer logs into PayPal account to authorise the transaction. Set it to true if you don't want to make shipping address visible to customer - in case of digital goods. Default value is false.
billingDescription
Optional
The text will appear on customer's PayPal account, as they will login to there PayPal account to authorise the transaction. Note: This feature is currently supported only for paymentType recurring only.
redirectUrls
Required
Refer to Redirect URLs  for more details.
Redirect URLs
Parameter
Required
Description
successUrl
Required
The URL to which the client will be redirected to after successful PayPal authorisation.
cancelUrl
Required
The URL to which the client will be redirected to in case of failure or cancellation of PayPal authorisation.
Response
Description
createdAt
A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
Merchant account for which the funds are collected.
customerCode
The identifier for the customer. In case of anonymous payment it is always anonymous.
Client IP address.
amount
An integer value greater than 0, representing the total amount in cents.
orderId
A client order id, will be used as reference to the payment.
paymentId
The token id issued by PayPal to initiate the transaction. Token will expire after 3 hours.
paymentUrl
The URL issued by PayPal to initiate the transaction.
paymentType
This parameter defines what kind of PayPal transaction you are initiating. Following types are supported sale. sale is used for a once-off payment.  Default is set to sale.
noShipping
Defines if shipping address will be made visible when customer logs into PayPal account to authorise the transaction. Set it to true if you don't want to make shipping address visible to customer - in case of digital goods.
errorCode
If transaction was having some issues and field is populated with error code representing reason of failure.
Execute PayPal Transaction
To execute PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/orders/{orderId}/execute
curl https://payments-stest.npe.auspost.zone/v1/wallets/paypal/payments/orders/{orderId}/execute -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1", 
          "payerId": "1234"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "customerCode": "anonymous",
    "ip": "127.0.0.1",
    "amount": "10000",
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "providerReferenceNumber": "7LT4359579269504C"
Executes a PayPal express checkout transaction after the customer has logged into PayPal and accepted it.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/orders/{orderId}/execute
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
 Path Variables 
Parameter
Description
orderId
A client's order id received after successful processing of Initiate PayPal Transaction.
Request Parameters
Parameter
Required
Description
merchantCode
Required
Merchant account for which the funds are collected.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Required
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
payerId
Required
The payer id returned from PayPal after customer has completed authorisation.
Response
Description
createdAt
A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
Merchant account for which the funds are collected.
customerCode
The identifier for the customer. In case of anonymous payment it is always anonymous.
Client IP address.
amount
An integer value greater than 0, representing the total amount in cents.
orderId
A client order id, will be used as reference to the payment.
providerReferenceNumber
The transaction id returned from PayPal. Will be empty if no response has been received back from PayPal.
providerDetails
The PayPal Provider Details associated with the transaction. Please note this field will only be returned if PayPal Gateway return those details.
status
The status of the payment. Valid values are paid, failed, inprogress and unknown. Refer to the table below for details:
PayPal Express checkout transaction statuses
Status
Description
inprogress
The transaction is in pending state or it has not terminated, e.g. an authorisation may be awaiting completion.
The payment has been captured.
failed
The payment has failed.
unknown
The result of execution is not determined(e.g. due to connectivity issues). To verify the status in this case use retrieve PayPal order details endpoint.
Refund PayPal Transaction
To refund PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{ "amount": 10000, 
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "ip": "127.0.0.1"
    "createdAt": "2021-07-23T13:00:53.128+10:00",
    "merchantCode": "YOUR_MERCHANT_CODE",
    "customerCode": "anonymous",
    "ip": "127.0.0.1",
    "amount": "10000",
    "status": "paid",
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "providerReferenceNumber": "7LT4359579269504C"
Refunds a previously executed PayPal transaction.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Path Variables
Parameter
Description
orderId
A customer order id which was successfully processed previously which the merchant now wants to refund.
Request Parameters
Parameter
Required
Description
merchantCode
Required
Merchant account for which the funds are collected.
Required
A customer IP address. Must be a valid IPv4 or IPv6.
amount
Required
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
Response
Description
createdAt
A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00.
merchantCode
Merchant account for which the funds are collected.
customerCode
The identifier for the customer. In case of anonymous payment it is always anonymous.
Client IP address.
amount
An integer value greater than 0, representing the total amount in cents.
status
The status of the payment. Valid values are paid failed.
orderId
A client order id, will be used as reference to the payment.
providerReferenceNumber
The transaction id returned from paypal.
errorCode
If transaction was having some issues and field is populated with error code representing reason of failure.
Retrieve PayPal order details
To retrieve status, billing & shipping details of PayPal payment by order id:




    

GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
curl -X GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
   "orderId": "01cce4c5-3cf3-4fb5-81ea-2425e6c532d8",
   "paymentId": "PAYID-LWCHDSY21197268NE401560F",
   "status": "paid",
   "amount": "10000",
   "payerDetails": {
      "firstName": "Joe",
      "lastName": "Smith",
      "email": "[email protected]"
   "shippingAddress": {
      "name": "Joe Smith",
      "streetLine1": "111 Bourke St",
      "city": "Melbourne",
      "stateCode": "VIC",
      "postcode": "3000",
      "countryCode": "AU"
Retrieves billing & shipping details for a customer that has previously initiated/executed a PayPal transaction.
HTTP Request
GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
Path Variables
Parameter
Description
orderId
A client order id, which is used as reference to the payment.
Request Parameters
Parameter
Required
Description
merchantCode
Required
Merchant account for which the funds are collected.
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Response
Description
orderId
The order id for the PayPal transaction.
paymentId
The payment id which was issued by PayPal to initiate/execute the transaction.
status
The transaction status for the order. Valid values are created, paid, failed,unknown. Once transaction is initiated the status is set to created. If the payment was processed and succeeded the status is set to paid. If payment was processed but was declined the status is set to failed. If the request was processed with unexpected status from gateway the status is set to unknown
amount
An integer value greater than 0, representing the total amount in cents.
payerDetails
The PayPal Payer details associated with the PayPal transaction.
shippingAddress
The PayPal Shipping Address associated with the PayPal transaction.
PayPal Objects
PayPal Shipping Address Object
PayPal account owner shipping address returned as part of the response to a Retrieve PayPal order details request.
Description
The name of the person associated with the shipping address.
streetLine1
The first line of the street address.
streetLine2
The second line of the street address (if there is one).
The name of the city.
stateCode
The name abbreviation of the state. Eg: (Victoria = VIC)
postcode
The postal or zip code.
countryCode
The code of the country. Eg: (Australia = AU)
PayPal Payer Details Object
PayPal account owner details returned as part of the response to a Retrieve PayPal order details request.
Description
firstName
The payer's first name.
lastName
The payer's last name.
email
The payer's email address.
PayPal Provider Details Object
PayPal Provider details returned as part of the response to a Execute PayPal Transaction request.
Description
reasonCode
Describes why the order status is inprogress. Possible values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, VERIFICATION_REQUIRED, TRANSACTION_APPROVED_AWAITING_FUNDING.
Error Codes
PayPal endpoints uses the following error codes:
Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Bad request data
SecurePay API
INVALID_REQUEST_DATA -- Invalid request data
SecurePay API
INVALID_ACCOUNT -- Account has not been configured for PayPal payments
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
INVALID_ORDER_ID -- Order id has to be unique per merchant
SecurePay API
UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
PAYPAL_ERROR -- Error happened on PayPal end while processing request
SecurePay API
Yes - talk to SecurePay API team
3D Secure 2
Overview
3D Secure 2 (3DS2) is an additional layer of security that aids fraud prevention. 3DS2 is a protocol managed by EMVCo used to authenticate the identity of the person making the payment to ensure that they are the legitimate cardholder even before the payment is done.
This is done by providing the card issuer with a high volume of contextual data to aid in the decision on which authentication flow to be used. The card issuer checks whether the payment being requested is from the legitimate cardholder. This results to a more frictionless experience where customers are verified, and payment then proceeds. In cases where the issuer identifies that the transaction is high risk, they can prompt challenge questions for the customer to answer as an additional verification.
With SecurePay 3DS2 which currently supports protocol version 2.1.0, you will be able to authenticate before submitting payment authorisation requests. Depending on the result of authentication, merchants or issuers can bear responsibility during chargebacks when the payment authorised is found to be fraudulent and not authorised by the cardholder.
By utilising SecurePay’s 3DS2 Javascript, you will be able to send an authentication request for which you will receive the authentication result that includes the liability shift information. Depending on the authentication result, you will have the flexibility to decide whether to proceed or not with the payment authorisation.
SecurePay 3DS2 is supported for the following categories:
Payment Types: Create Payment and PreAuth/InitialAuth
Currencies: AUD
Acquiring Bank with corresponding Card Types:
Please note: to use the 3DS2 feature:
If you are a Gateway merchant, you must contact your acquirer to enable 3DS2 for the card types you support
You must complete the application steps via their SecurePay account or contacting our support team
Please note: 3DS2 is currently also available for Magento and WooCommerce e-commerce extensions.
3DS2 Javascript SDK
How does it work?
3DS2 authentication should be done before a payment authorisation request is sent. Authentication can be accomplished by using the 3DS2 JavaScript SDK, following either of the two methods below:
Recommended method:
Initiate a 3DS2 Payment Order.
Load the SecurePay 3DS2 Javascript client library.
Initialise the 3D Secure script and configure the callback methods required during the checkout page load.
Trigger the 3DS2 Authentication process when ready (i.e. Payment or checkout commenced).
Handle the authentication outcome.
Alternate method:
This may increase in load time. Also, this can only be done once you have filled all the 3DS2 required fields.
Initiate a 3DS2 Payment Order.
Load the SecurePay 3DS2 Javascript client library.
Initialise and trigger 3DS2 authentication together using the method initAndStartThreeDS.
Handle the authentication outcome.
Please note: After authentication, the 3DS2 Payment Order should be passed into your Create Payment request and Create PreAuth/InitialAuth Transaction requests using `threedSecureDetails` request field.
Environment Details
Environment
SecurePay 3DS2 JavaScript SDK URL
Sandbox
https://test.api.securepay.com.au/threeds-js/securepay-threeds.js
https://api.securepay.com.au/threeds-js/securepay-threeds.js
Please note: Consumers of SecurePay UI must not host the script (3DS2 Javascript SDK) themselves. 
Initiate A 3DS2 Payment Order
Initiate a Payment order of order type THREED_SECURE.
The following fields from the Initiate Payment Order response will be used for 3DS authentication process: orderToken, threedSecureDetails.providerClientId, threedSecureDetails.sessionId and threedSecureDetails.simpleToken
Please note: 3DS2 Payment Order can be reused for a maximum of 3 authentication attempts for the same payment request.
Load SecurePay 3DS2 JavaScript SDK
The securepay-threeds.js client library should be included in your HTML source as shown in the sample code:
Live Environment: 
<script th:id="sp-threeds-js" th:src="https://api.securepay.com.au/threeds-js/securepay-threeds.js" type="text/javascript"></script>


Sandbox Environment: 
<script th:id="sp-threeds-js" th:src="https://test.api.securepay.com.au/threeds-js/securepay-threeds.js" type="text/javascript"></script>
Initialise the 3D Secure JS
Add an iframe element for the Challenge Form
The 3DS2 will need a challenge window for some calls to get customer's input for the challenge. Hence create an element for this window to be published when required.
<iframe id="3ds-v2-challenge-iframe" name="3ds-v2-challenge-iframe" style="width: 500px; height: 500px; ;">
Once loaded, the script can be initialised with the following parameters.
var sp3dsConfig = {
    clientId: providerClientId,
    iframe: iframeElement,
    token: orderToken,
    simpleToken: simpleToken,
    threeDSSessionId: sessionId,
    onRequestInputData: onRequestInputDataCallback,
    onThreeDSResultsResponse: onThreeDSResultsResponseCallback,
    onThreeDSError: onThreeDSErrorCallback
var securePayThreedsUI = new window.SecurePayThreedsUI();
window.securePayThreedsUI = securePayThreedsUI;
securePayThreedsUI.initThreeDS(sp3dsConfig);
Parameter
Description
clientId
3DS2 Client Id of the merchant.
The value can be obtained from Initiate Payment order response, threedSecureDetails.providerClientId.
iframe
The iframe element that can be used to display 3DS2 challenge form.
Iframe element should be defined in checkout/payment page and passed into the Java Script during initialisation.
 For example: In Add an iframe element, value will be:
document.getElementById(“3ds-v2-challenge-iframe”)
token
An order token that was returned from Initiate Payment order response, orderToken
simpleToken
A simple authentication token that was returned from Initiate Payment order response, threedSecureDetails.simpleToken
threeDSSessionId
A unique session id (sessionId) that was returned from Initiate Payment order response. threedSecureDetails.sessionId
onRequestInputData
See onRequestInputData callback section
onThreeDSResultsResponse
See onThreeDSResultsResponse callback section
onThreeDSError
See onThreeDSResultsResponse callback section
If any of the config objects are missing, error VALIDATION_ERROR - missing mandatory config will be received.
If the clientID provided is incorrect, error INITIALISATION_ERROR - JavaScript initialisation error will be received.
If invalid type of iframe is used, then WRONG_CONFIG_TYPE_ERROR - config is not in expected format will be received.
Configure the callbacks required for the script
onRequestInputData callback
onRequestInputData callback will collect relevant information from customer to be used in an 3DS2 Authentication request. onRequestInputData callback is executed prior to an HTTP request initiated by 3DS2 javascript. The callback should return an object with the following details.




    

  "cardTokenInfo":{
    "cardholderName":"John More Doe",
    "cardToken":"6326270000000000"
  "accountData":{
    "emailAddress":"[email protected]",
    "mobilePhone":{
      "cc":"+61",
      "subscriber":"400000000"
    "workPhone":{
      "cc":"+61",
      "subscriber":"400000000"
    "homePhone":{
      "cc":"+61",
      "subscriber":"400000000"
  "billingAddress":{
    "city":"Suburb",
    "state":"NSW",
    "country":"AU",
    "zipCode":"2000",
    "streetAddress":"Unit 1",
    "detailedStreetAddress":"123 Street Suburb",
    "detailedStreetAddressAdditional":"123 Street Suburb"
  "shippingAddress":{
    "city":"Suburb",
    "state":"NSW",
    "country":"AU",
    "zipCode":"2000",
    "streetAddress":"Unit 1",
    "detailedStreetAddress":"123 Street Suburb",
    "detailedStreetAddressAdditional":"123 Street Suburb"
  "merchantRiskData":{
    "deliveryTimeframeType":"01",
    "reOrderType":"01",
    "shippingMethodType":"01"
  "threeDSInfo":{
    "threeDSReqAuthMethodInd":"02"
Parameter
Required
Description
cardTokenInfo
required
Card holder details associated with the issued card used for the purchase.
See CardTokenInfo Object
accountData
required
Additional Information related to the card holder.
See AccountData Object
billingAddress
required
Cardholder billing address associated with the card used for this purchase.
See Address Object
shippingAddress
optional
Shipping address requested by the Cardholder.
See Address Object
threeDSInfo
optional
Additional information associated with the Authentication request as required by different card schemes (e.g. visa, mastercard, diners, amex).
Required for Visa Cards Only. Card scheme can be found in the onTokeniseSuccess callback response TokenisedCard
See ThreeDSInfo Object
merchantRiskData
optional
The Merchant Risk Data contains optional information about the specific purchase by the Cardholder.
 Card scheme can be found in the onTokeniseSuccess callback response TokenisedCard
See MerchantRiskData Object
CardTokenInfo Object
Parameter
Required
Description
cardholderName
required
String
Name of the cardholder.
Alphanumeric characters including blank space ' '.
Minimum length of 2.
Maximum length of 45.
cardToken
required
String
A tokenised payment instrument reference.
This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction.
AccountData Object
Parameter
Required
Description
mobilePhone
optional
ContactNumber
The mobile phone number provided by the cardholder.
workPhone
optional
ContactNumber
The work phone number provided by the cardholder
homePhone
optional
ContactNumber
The home phone number provided by the cardholder
emailAddress
required
String
The email address associated with the cardholder in string format.
Max length of 254.
ContactNumber Object
Parameter
Required
Description
required
String
Country code of the contact number.
A prefix of '+' followed by 1 to 3 numeric country code.
subscriber
required
Integer
Subscriber number.
Maximum length of 15 numeric characters.
Mandatory if cc is provided and should follow string length according to country code.
Address Object
Parameter
Required
Description
streetAddress
required
String
First Line of the street address.
Maximum length of 50 characters.
detailedStreetAddress
optional
String
Second line of the street address.
Maximum length of 50 characters.
detailedStreetAddressAdditional
optional
String
Third line of the street address.
Maximum length of 50 characters.
required
String
Name of the City.
Maximum length of 50 characters.
state
required
String
The state or province following ISO 3166-2.
country
required
String
Country. Can contain the 3-digit numeric ISO code or the 2 or 3 alpha character ISO code.
zipcode
required
String
ZIP or postal code. Maximum length of 16 characters.
ThreeDSInfo Object
Parameter
Required
Description
threeDSReqAuthMethodInd
required
String
Method used to authenticate the user with the client web application. Accepted Values:
01: No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)
02: Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials
03: Login to the cardholder account at the 3DS Requestor system using federated ID
04: Login to the cardholder account at the 3DS Requestor system using issuer credentials
05: Login to the cardholder account at the 3DS Requestor system using third-party authentication
06: Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
MerchantRiskData Object
Parameter
Required
Description
deliveryTimeframeType
Optional
String
The merchandise delivery timeframe. Accepted values:
01: Electronic Delivery
02: Same day shipping
03: Overnight shipping
04: Two-day or more shipping
reOrderType
Optional
String
Indicates whether the cardholder is reordering previously purchased merchandise. Accepted values:
01: First time ordered
02: Reordered
shippingMethodType
Optional
String
Indicates shipping method chosen for the transaction.
Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their 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.
Accepted values: 
01: Ship to cardholder’s billing address
02: Ship to another verified address on file with merchant
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, emedia subscriptions, etc.)
deliveryEmailAddress
conditional
String
For Electronic delivery, the email address to which the merchandise was delivered. 
Mandatory for Amex Card when shippingMethodType = 05. 
Max length of 254.
onThreeDSResultsResponse callback
The onThreeDSResultsResponse callback provides the outcome of the 3DS2 authentication process. When 3DS2 authentication process has finished, this callback provides a liability shift indicator and other supporting parameters.
Parameter
Description
liabilityShiftIndicator
String
Liability Shift Indicator.
This indicates whether the chargeback liability is shifted to the issuer
Possible values:
Y: Liability for relevant Chargeback reason codes is shifted to the issuer.
N: Liability for relevant Chargeback reason codes Is not shifted to the issuer.
 Refer to Liability Shift Indicator Matrix for more information
transStatus
String
Transaction Status.
This value indicates whether a transaction qualifies as an authenticated transaction. It is received from the 3DS2 server and follows the EMVCo specification for 3DS2 data elements.
transStatusReason
String
Transaction Status Reason.
It provides additional information to support the transStatus. It is received from the 3DS2 server and follows the EMVCo specification for 3DS2 data elements. Refer to Transaction Status Reason Codes for more information.
String
E-Commerce Indicator/Security Level Indicator(SLI)
This is a two-digit value returned by the Directory Server that indicates the result of the authentication.
authenticationValue
String
Authentication Value. Also known as Cardholder Authentication Verification Value(CAVV).
This is a value returned by the Issuer ACS that performed the authentication.
cardDescription
String
Card Brand Description used during authentication.
onThreeDSError callback
The onThreeDSError callback is used when there is a failure during the 3DS2 authentication process. Callback will be executed with a javascript array that contains one or more javascript objects, each object contains the following information. See Error codes for more information.
// Sample format for Error Object
    id: 'b7e41d4f-0dc5-45ae-b5f3-c73f6e2943c9',
    code: '180',
    detail: 'Unable to perform 3DS Authentication'
Parameter
Description
String
A unique error id which can be used for troubleshooting.
Integer
An error code indicating the error
detail
String
Error details.
Trigger the 3DS2 Authentication
Once the script is initialised and all the callbacks configured correctly, the authentication process can be triggered. Example to Trigger 3DS2 authentication process
var spThreedsUI = window.securePayThreedsUI;
spThreedsUI.startThreeDS();
During this step, onRequestInputData callback will be used to collect necessary information to prepare an 3DS2 authentication request.
If 3ds authentication process is triggered before the initialisation has completed, then error GENERIC_THREEDS_START_ERROR - Failed to start Threeds Authentication will be received.
Initialise and start 3DS
This is an alternate approach where we initialise and trigger the 3DS2 authentication in a single call. Please note that this call can only be done once we have all the callbacks configured correctly.
var sp3dsConfig = {
    clientId: providerClientId,
    iframe: iframeElement,
    token: orderToken,
    simpleToken: simpleToken,
    threeDSSessionId: sessionId,
    onRequestInputData: onRequestInputDataCallback,
    onThreeDSResultsResponse: onThreeDSResultsResponseCallback,
    onThreeDSError: onThreeDSErrorCallback
var securePayThreedsUI = new window.SecurePayThreedsUI();
window.securePayThreedsUI = securePayThreedsUI;
securePayThreedsUI.initAndStartThreeDS(sp3dsConfig);
Please note: After authentication, the 3DS2 Payment Order should be passed into your Create Payment request and Create PreAuth/InitialAuth Transaction requests using `threedSecureDetails` request field.
Handle the Authentication Outcome
Once the 3DS2 authentication process has finished, a callback will be done via onThreeDSResultsResponse callback to notify the authentication outcome.
This callback includes a Liability Shift Indicator and other supporting parameters.




    

If an error has occurred during the authentication process, a callback will be done via onThreeDSError callback.
Liability Shift Indicator
SecurePay receives eci (SLI) and authentication value (CAVV) from the 3D Secure server as part of the authentication process.
SecurePay uses the value of these parameters along with the card brand used during authentication to determine if the chargeback liability shifts to the issuer or stays with the merchant.
The shift indicates who will be responsible for relevant fraudulent chargebacks.
Along with the transStatus, transStatusReason, eci and authentication value, the Liability Shift Indicator is included in the response callback for merchant visibility as a guide, allowing the flexibility to decide whether to proceed with the payment or not.
Please note that the Liability Shift is applicable only to relevant fraud related chargebacks and is governed by individual scheme rules.
Liability Shift Indicator Matrix Object
Card Brand
Authentication Value Presence
Trans Status
Authentication Result
Liability Shift Indicator
MasterCard
Fully Authenticated
Y (Liability shifts to Issuer)
MasterCard
Attempted Authentication
Y (Liability shifts to Issuer)
MasterCard
Not Authenticated
N (Liability stays with Merchant)
MasterCard
Unable to authenticate.
N (Liability stays with Merchant)
MasterCard
Rejected
N (Liability stays with Merchant)
MasterCard
Fully Authenticated
Y (Liability shifts to Issuer)
Fully Authenticated
Y (Liability shifts to Issuer)
Attempted Authentication
Y (Liability shifts to Issuer)
Attempted Authentication
N (Liability stays with Merchant)
Not Authenticated
N (Liability stays with Merchant)
Rejected
N (Liability stays with Merchant)
Fully Authenticated
N (Liability stays with Merchant)
Fully Authenticated
Y (Liability shifts to Issuer)
Attempted Authentication
Y (Liability shifts to Issuer)
Not Authenticated
N (Liability stays with Merchant)
Rejected
N (Liability stays with Merchant)
Unable to authenticate.
N (Liability stays with Merchant)
Transaction Status Reason Codes
Reason code
Detail
Description
Card authentication failed
If this occurs multiple times for the same card, contact your Acquirer.
Unknown Device
The device the cardholder used for authentication is not the same as the registered device. The cardholder needs to use the same device. If this information is not known, then the cardholder will need to contact their card issuer.
Unsupported Device
The cardholder used a device that the ACS does not support e.g., unsupported OS, device not considered secure.
Exceeds authentication frequency limit
The maximum limit of authentications has been exceeded. Wait to try again or try a different card. If issue persists, then the cardholder will need to contact the card Issuer.
Expired card
Please check the expiry date of your card and try again.
Invalid card number
The card number is invalid. Please check and re-enter the details or try a different card.
Invalid transaction
There is an issue with the transaction. The cardholder will need to contact their card Issuer.
No Card record
The card does not support 3DS or is not enrolled in 3DS from the Issuer. Please try a different card.
Security failure
There is a security failure on this card. Please try a different card.
Stolen card
Records show that the card used has been flagged as stolen. The cardholder will need to contact their card Issuer.
Suspected fraud
Suspected fraudulent activity has been detected. The cardholder will need to contact their card Issuer.
Transaction not permitted to cardholder
This type of transaction is not permitted. The cardholder will need to contact their card Issuer.
Cardholder not enrolled in service
The card used is currently not enrolled for 3DS.
Transaction timed out at the ACS
An authentication response has not been received within a given time, please try again shortly. If the problem persists, the cardholder will need to contact their card issuer.
Low confidence
Medium confidence
High confidence
Very High confidence
Exceeds ACS maximum challenges
Number of failed challenges exceeded the maximum set by the ACS. Please wait and try again or try a different card.
Non-Payment transaction not supported
ACS does not allow/support payment transactions (if received on a PA - Payment transaction) OR ACS does not allow/support non-payment transactions (if received on a NPA - Non Payment transaction).
3RI transaction not supported
ACS does not allow/support merchant-initiated transactions.
22–79
Reserved for EMVCo future use (values invalid until defined by EMVCo)
80–99
Reserved for DS use
Error Codes
Detail
Originating System
Invalid Merchant ID.
The provided clientID is incorrect.
SecurePay API
Invalid ISO Currency Code.
SecurePay API
Merchant Not Enrolled in 3D Secure.
SecurePay API
Unable to perform 3DS Authentication.
Might be due to:
Card brand used is not supported for 3DS2.
Connection issue between 3DS server and Directory Server.
Mandatory field is incorrectly provided.
SecurePay API
Card Unsupported for 3D Secure.
SecurePay API
3D Secure Configuration Error.
Internal Error occurred preventing 3DS2 process to proceed.
SecurePay API
Invalid value for <field>.
SecurePay API
Unable to process the request.
Invalid Token is used or Token is expired.
SecurePay API
Unable to process your request.
Timeout or internal connectivity errors.
SecurePay API
Acquirer not configured for 3DS2 for used card type.
SecurePay API
Liability Shift indicator error.
SecurePay API
Unexpected value for <field>.
SecurePay API
<field> must not be Null.
SecurePay API
Order not in valid state.
SecurePay API
Order intent used is invalid.
SecurePay API
Invalid or Duplicate Request.
SecurePay API
Invalid Origin.
SecurePay API
3DS2 Testing
Full testing scenarios and information can be found here: Card Testing 3DS2
Fraud detection - FraudGuard
Overview
Fraud detection - FraudGuard is a tool for transaction fraud detection and prevention. Developed by SecurePay, this tool reduces your exposure to fraudulent transactions by detecting fraud before it occurs. You can customise your fraud settings by establishing your own rules within a points system, so you’re always in control.
The Fraud Detection API performs a fraud check, and returns back its fraud risk assessment.  Based on this assessment, you are able to decide on whether to go ahead with the transaction (by using the Payment API), or to stop the order from proceeding. You enjoy this flexibility with our fraud solution. 
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Perform Fraud Detection
Performs fraud detection, given the following details.
To do fraud detection, use this code:
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
curl https://payments-stest.npe.auspost.zone/v2/antifraud/check -X POST
    -H "Content-Type: application/json"
    -H "Authorisation: Bearer xxxxxxxx"
    -d '{ "fraudCheckType": "FRAUD_GUARD",
          "ip": "127.0.0.1",
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
          "paymentDetails": {
            "amount": 10000,  
            "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "paymentMethod": "PAYMENT_CARD"
    "orderId": "17df5bdb-f17a-48d7-99f9-ff2d9660db97",
    "fraudCheckType": "FRAUD_GUARD",
    "fraudCheckResult": {
        "providerReferenceNumber": "0bde9e63-d41a-4e4a-be7f-3949411f1f2e",
        "score": 0,
        "providerResponseMessage": "Fraud check passed"
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4.
orderId
String
Optional
A client order id, which will be used as reference to fraud check. If not provided, SecurePay API will assign a unique id for the order.
merchantCode
String
Required
Merchant account code for which fraud check is performed.
fraudCheckType
String
Required
This parameter defines which type of fraud check is used. Supported type is FRAUD_GUARD.
paymentDetails
Object
Required
The Payment Details Object.
customerDetails
Object
Optional
The Customer Details Object.
shippingAddress
Object
Optional
The Shipping Address Object.
billingAddress
Object
Optional
The Billing Address Object.
customerCode
String
Optional
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. This is used when you want to perform a fraud request against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used.
Response
Description
orderId
String
A client order id, which will used as reference to fraud check.
fraudCheckType
String
Returns type of fraud check performed. Values could be FRAUD_GUARD.
fraudCheckResult
Object
Fraud check result. Refer to Fraud Check Result for more details.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
Fraud Objects
Payment Details Object
Payment details to include as part of a Perform Fraud Detection request.
Required
Description
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
paymentMethod
String
Required
The payment method used by the customer. Supported value is PAYMENT_CARD.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information for paymentMethod PAYMENT_CARD.
Customer Details Object
Customer details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
emailAddress
String
Optional
Customer email
Should contain @ character and at least one preceding and following character, up to 60 characters
Shipping Address Object
Customer shipping address details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
firstName
String
Optional
Customer shipping first name
Should not be longer than 30 characters
lastName
String
Optional
Customer shipping last name
Should not be longer than 30 characters
String
Optional
Customer shipping city
Should not be longer than 20 characters
postcode
String
Optional
Customer shipping postcode
Should not be longer than 4 characters
countryCode
String
Optional
Customer shipping country code
3 characters long country code in ISO 3166-1
Billing Address Object
Customer billing address details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
countryCode
String
Optional
Customer billing country code
3 characters long country code in ISO 3166-1
Fraud Check Result Object
Detailed part of the response to a Perform Fraud Detection request.
Description
providerReferenceNumber
String
The fraud check reference number.
score
Integer
The result of the fraud check.
providerResponseMessage
String
This field contains details of the result.
Fraud Error Codes
Fraud endpoint uses the following error codes:




    

Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Send malformed JSON in request
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
INVALID_ACCOUNT -- Account is not configured for fraud check type provided in request
Payment Gateway
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway
Payment Gateway
Fraud detection - ACI ReD Shield
Overview
Fraud detection – ACI ReD Shield is another tool for transaction fraud detection and prevention. This tool is provided by a third party, ACI Worldwide.
The Fraud Detection API performs a fraud check, and returns back its fraud risk assessment. Based on this assessment, you are able to decide on whether to go ahead with the transaction (by using the Payment API), or to stop the order from proceeding. You enjoy this flexibility with our fraud solution.
Please note, this service is in alpha and not publicly available.
Fraud Javascript SDK
Fraud integration JS SDK integration:
<script>
    var io_install_flash = false;
    var io_install_stm = false;
</script>
<script type="text/javascript" src="https://mpsnare.iesnare.com/snare.js"></script>
<script>
    function io_bb_callback(bb, complete) {
      console.log("Blackbox: " + bb,complete);
</script>
The fraud detection with ACI ReD endpoint requires device fingerprint field to be included as part of the customer-object.
The device fingerprint generation and validation is provided by Iovation ReputationManager 360 (Iovation Javascript SDK).
The snare.js script should be included in your HTML source as shown in the sample code:
The callback function "io_bb_callback" will be called with two arguments.
bb: blackbox (The device fingerprint)
complete : true/false flag to denote the process completion.
See the Iovation Integration Guide for more info:
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Perform Fraud Detection
Performs fraud detection, given the following details.
To do fraud detection, use this code:
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
curl https://payments-stest.npe.auspost.zone/v2/antifraud/check -X POST
    -H "Content-Type: application/json"
    -H "Authorisation: Bearer xxxxxxxx"
    -d '{ "fraudCheckType": "ACI_FRAUD_CHECK",
          "ip": "127.0.0.1",
          "merchantCode": "YOUR_MERCHANT_CODE", 
          "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
          "paymentDetails": {
            "amount": 10000,  
            "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "paymentMethod": "PAYMENT_CARD"
    "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
    "fraudCheckType": "ACI_FRAUD_CHECK",
    "fraudCheckResult": {
      "providerReferenceNumber": "70113",
      "result": "PASSED",
      "providerResponseMessage": "Transaction accepted"
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4.
orderId
String
Optional
A client order id, which will be used as reference to fraud check. If not provided, SecurePay API will assign a unique id for the order.
merchantCode
String
Required
Merchant account code for which fraud check is performed.
fraudCheckType
String
Required
This parameter defines which type of fraud check is used. Supported type is ACI_FRAUD_CHECK.
paymentDetails
Object
Required
The Payment Details Object.
merchantWebsite
String
Optional
Merchant website url.
productDetails
Object
Optional
The list of Product Details Objects.
customerDetails
Object
Optional
The Customer Details Object.
shippingAddress
Object
Optional
The Shipping Address Object.
billingAddress
Object
Optional
The Billing Address Object.
customFields
Object
Optional
The Custom fields Object.
customerCode
String
Optional
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. This is used when you want to perform a fraud request against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used.
Response
Description
orderId
String
A client order id, which will used as reference to fraud check.
fraudCheckType
String
Returns type of fraud check performed. Values could be ACI_FRAUD_CHECK.
fraudCheckResult
String
Fraud check result. Refer to Fraud Check Result for more details.
customerCode
String
The identifier for the customer. In case of anonymous payment it is always anonymous.
Fraud Objects
Payment Details Object
Payment details to include as part of a Perform Fraud Detection request.
Required
Description
amount
Integer
Required
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
paymentMethod
String
Required
The payment method used by the customer. Supported value is PAYMENT_CARD.
token
String
Required
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information for paymentMethod PAYMENT_CARD.
Product Details Object
Product details to include as part of a Perform Fraud Detection request.
Product details should be passed as a list of Product details objects.
Required
Description
Validation rule
String
Optional
Product identifier
Should not be longer than 12 characters
itemQuantity
Integer
Optional
Product quantity
An integer value greater than 0 and up to 12 digits long.
itemDescription
String
Optional
Product description
Should not be longer than 127 characters
itemUnitPrice
Integer
Optional
Product unit price
An integer value greater than 0 and up to 12 digits long, representing the unit price in cents.
itemPartNumber
String
Optional
Product part number
Should not be longer than 30 characters
itemShippingComment
String
Optional
Product shipping comment
Should not be longer than 160 characters
itemGiftMessage
String
Optional
Product gift message
Should not be longer than 160 characters
Customer Details Object
Customer details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
emailAddress
String
Optional
Customer email
Should contain @ character and at least one preceding and following character, up to 60 characters
phoneNumber
String
Optional
Customer phone number
Should contain digits only, up to 19 digits
deviceFingerprint
String
Optional
Customer device fingerprint - Refer to fraud_integration to get this field
Should contain less than or equal to 6000 characters
Shipping Address Object
Customer shipping address details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
firstName
String
Optional
Customer shipping first name
Should not be longer than 30 characters
lastName
String
Optional
Customer shipping last name
Should not be longer than 30 characters
streetLine1
String
Optional
Customer shipping street name
Should not be longer than 30 characters
streetLine2
String
Optional
Customer shipping street name
Should not be longer than 30 characters
String
Optional
Customer shipping city
Should not be longer than 20 characters
postcode
String
Optional
Customer shipping postcode
Should not be longer than 4 characters
stateCode
String
Optional
Customer shipping state code
Should not be longer than 10 characters
countryCode
String
Optional
Customer shipping country code
3 characters long country code in ISO 3166-1
Billing Address Object
Customer billing address details to include as part of a Perform Fraud Detection request.
Required
Description
Validation rule
firstName
String
Optional
Customer billing first name
Should not be longer than 30 characters
lastName
String
Optional
Customer billing last name
Should not be longer than 30 characters
streetLine1
String
Optional
Customer billing street name
Should not be longer than 30 characters
streetLine2
String
Optional
Customer billing street name
Should not be longer than 30 characters
String
Optional
Customer billing city
Should not be longer than 20 characters
postcode
String
Optional
Customer billing postcode
Should not be longer than 4 characters
stateCode
String
Optional
Customer billing state code
Should not be longer than 10 characters
countryCode
String
Optional
Customer billing country code
3 characters long country code in ISO 3166-1
Custom Fields Object
Custom fields to include as part of a Perform Fraud Detection request.
If fraud check provider has capability to allow merchant to configure custom rules, merchant can use Custom Fields.
Once custom rules are configured on fraud provider portal (e.g. ACI Fraud Check), merchant could use the Custom Fields to trigger specific rules.
At the moment custom rules are supported only for ACI_FRAUD_CHECK.
Required
Description
Validation rule
customField1
String
Optional
Custom fraud check rules
Should not be longer than 256 characters
customField2
String
Optional
Custom fraud check rules
Should not be longer than 256 characters
customField3
String
Optional
Custom fraud check rules
Should not be longer than 256 characters
customField4
String
Optional
Custom fraud check rules
Should not be longer than 256 characters
customField5
String
Optional
Custom fraud check rules
Should not be longer than 256 characters
Fraud Check Result Object
Detailed part of the response to a Perform Fraud Detection request.
Description
providerReferenceNumber
String
The fraud check reference number.
result
String
The result of the fraud check. Valid values are PASSED, SUSPECTED or BLOCKED.
providerResponseMessage
String
This field contains details of the result.
Fraud Error Codes
Fraud endpoint uses the following error codes:
Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Send malformed JSON in request
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway
Payment Gateway
Scheduled Payments
Overview
Scheduling API provide merchant capability to create once off payment on specified date or recurring payments.
Note, that a card token needs to be stored against customer through Create payment instrument endpoint prior of creating a schedule.
The period of recurring payments could be custom day interval or calendar intervals such as weekly, fortnightly, monthly, quarterly, half yearly or annually.  
Rest API
Please note that for all requests timeout is 30 seconds.
The URLs mentioned throughout the Rest API documentation and in the code samples are for the sandbox environment.
To ensure you're using the correct URL please refer to Environment details.
Create a once off payment on specified date
To create a once off payment on specified date:
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{
           "ip": "127.0.0.1",
           "referenceNumber": "Invoice 123",
           "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
           "merchantCode": "YOUR_MERCHANT_CODE",
           "customerCode": "YOUR_CUSTOMER_CODE",
           "amount": 10000,
           "payDate": "2019-12-03"
  "ip": "127.0.0.1",
  "scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4",
  "referenceNumber": "Invoice 123",
  "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "merchantCode": "YOUR_MERCHANT_CODE",
  "customerCode": "YOUR_CUSTOMER_CODE",
  "amount": 10000,
  "payDate": "2019-12-03"
Creates once off payment on specified date in the future.




    

HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
referenceNumber
String
Required
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. Should not be longer than 30 characters.
merchantCode
String
Required
Merchant account for which the funds are collected.
customerCode
String
Required
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
amount
Number
Required
An integer value greater than 0, representing the amount in cents. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
token
String
Required
A tokenised payment instrument reference.
payDate
String
Required
The date in ISO 8601 format when the payment should be made, for example 2020-01-13. Should be not earlier than the next day.
Response
Description
String
Client IP address.
scheduleId
String
A unique schedule id, will be used as reference to the schedule.
referenceNumber
String
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number.
merchantCode
String
Merchant account for which the funds are collected.
customerCode
String
A unique (within your organisation) identifier of your customer.
amount
Number
An integer value greater than 0, representing the  amount in cents.
token
String
A tokenised payment instrument reference.
payDate
String
The date in ISO 8601 format when the payment should be made, for example 2020-01-13.
Create a payment schedule
To create a recurring scheduled payment:
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring -X POST 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{
           "ip": "127.0.0.1",
           "referenceNumber": "Invoice 123",
           "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
           "merchantCode": "YOUR_MERCHANT_CODE",
           "customerCode": "YOUR_CUSTOMER_CODE",
           "amount": 1000,
           "recurringTransaction": true,
           "scheduleDetails": {
              "paymentIntervalType": "DAILY_INTERVAL",
              "intervalLength": 10,
              "startDate": "2019-12-03",
              "endDate": "2020-04-23"           
  "ip": "127.0.0.1",
  "scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4",
  "referenceNumber": "Invoice 123",
  "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "merchantCode": "YOUR_MERCHANT_CODE",
  "customerCode": "YOUR_CUSTOMER_CODE",
  "amount": 10000,
  "recurringTransaction": true,
  "scheduleDetails": {
     "paymentIntervalType": "DAILY_INTERVAL",
     "intervalLength": 10,
     "startDate": "2019-12-03",
     "endDate": "2020-04-23", 
     "lastPaymentDate": "2020-04-21"
Creates a payment schedule.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
referenceNumber
String
Required
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. Should not be longer than 30 characters.
merchantCode
String
Required
Merchant account for which the funds are collected.
customerCode
String
Required
A unique (within your organisation) identifier of your customer. Should not be longer than 30 characters. Please note anonymous is a reserved keyword and must not be used.
amount
Number
Required
An integer value greater than 0, representing the amount in cents. Please note the amount field must be sent in cents i.e. if you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
token
String
Required
A tokenised payment instrument reference.
recurringTransaction
Boolean
Required
Whether a Merchant has agreement with a Cardholder, whereby the Cardholder authorizes the Merchant to store and use the Cardholder's credit card data periodically and on an ongoing basis. For a recurring payment transaction expiry date and CVV in most cases are ignored by the bank.
scheduleDetails
Object
Required
A schedule details request object.
Response
Description
String
Client IP address.
scheduleId
String
A unique schedule id, will be used as reference to the schedule.
referenceNumber
String
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number.
merchantCode
String
Merchant account for which the funds are collected.
customerCode
String
A unique (within your organisation) identifier of your customer.
amount
Number
An integer value greater than 0, representing the  amount in cents.
token
String
A tokenised payment instrument reference.
recurringTransaction
Boolean
Whether a Merchant has agreement with a Cardholder, whereby the Cardholder authorizes the Merchant to store and use the Cardholder's credit card data periodically and on an ongoing basis. For a recurring payment transaction expiry date and CVV in most cases are ignored by the bank.
scheduleDetails
Object
A schedule details response object.
Delete a payment schedule or a once off payment on specified date
To delete a payment schedule or a once off payment on specified date:
DELETE https://payments-stest.npe.auspost.zone/v2/payments/schedules/559d4616-ff9c-4ce2-ad6f-93983ff69ee4
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/559d4616-ff9c-4ce2-ad6f-93983ff69ee4 -X DELETE 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx"
    -d '{
           "ip": "127.0.0.1",
           "merchantCode": "YOUR_MERCHANT_CODE"
  "ip": "127.0.0.1",
  "merchantCode": "YOUR_MERCHANT_CODE",
  "scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4"
Deletes an existing payment schedule or a once off payment on specified date in the future. Use scheduleId value returned by Create a payment schedule endpoint or Create a once off payment on specified date endpoint.
HTTP Request
DELETE https://payments-stest.npe.auspost.zone/v2/payments/schedules/{scheduleId}
Header Parameters
Parameter
Required
Description
Authorization
Required
Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
Content-Type
Required
Should be set to application/json.
Request Parameters
Parameter
Required
Description
String
Required
A customer IP address. Must be a valid IPv4 or IPv6.
scheduleId
String
Required
A unique schedule id returned by Create a payment schedule endpoint or Create a once off payment on specified date endpoint.
Response
Description
String
Client IP address.
scheduleId
String
The schedule id that has been deleted.
merchantCode
String
Merchant account for which the funds are collected.
Scheduling Objects
Schedule Details Object Request
Schedule details to include as part of a Create schedule request.
Required
Description
paymentIntervalType
String
Required
Type of scheduling, possible values are DAILY_INTERVAL, WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY, HALF_YEARLY, ANNUALLY. If schedulingType is set to DAILY_INTERVAL, a length in days should be provided in intervalLength field.
intervalLength
Number
Conditional
Required when schedulingType is DAILY_INTERVAL, specifies the number of days between payments. Must be positive number.
startDate
String
Required
The date in ISO 8601 format when the first payment should be made, for example 2020-01-13. Should be not earlier than the next day.
endDate
String
Optional
The date in ISO 8601 format when the last payment should be made, for example 2020-04-13. Should be later than startDate field. If the endDate is not specified, payments will occur indefinitely until schedule is deleted.
Schedule Details Object Response
Schedule details in Create schedule response.
Required
Description
paymentIntervalType
String
Required
Type of scheduling, possible values are DAILY_INTERVAL, WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY, HALF_YEARLY, ANNUALLY. If schedulingType is set to DAILY_INTERVAL, a length in days should be provided in intervalLength field.
intervalLength
Number
Conditional
Required when paymentIntervalType is DAILY_INTERVAL, specifies length of scheduling interval. Must be positive number.
startDate
String
Required
The date in ISO 8601 format when the first payment should be made, for example 2020-01-13. Should be not earlier than the next day.
endDate
String
Optional
The date in ISO 8601 format when the last payment should be made, for example 2020-04-13. Should be later than startDate field. If the endDate is not specified, payments will occur indefinitely until schedule is deleted.
lastPaymentDate
String
Conditional
If endDate if provided in create schedule request, lastPaymentDate will provide actual last payment date based on startDate and paymentIntervalType provided, could be differ from endDate provided in request.
Error Codes
Response Code
Error Code
Originating System
Testable
BAD_REQUEST -- Bad request data
SecurePay API
INVALID_REQUEST_DATA -- Invalid request data
SecurePay API
INVALID_ACCOUNT -- Account has not been configured for credit card payments
SecurePay API
INVALID_IP_ADDRESS -- Invalid IP address
SecurePay API
UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token.
SecurePay API
SYSTEM_ERROR -- Error happened in SecurePay API while processing request
SecurePay API
GATEWAY_ERROR -- Error from Payment Gateway
Payment Gateway
TIMED_OUT -- Payment Gateway took too long to respond
Payment Gateway
Errors
Overview
{
  "errors": [
      "id": "1a909ec1-c96c-4ced-a471-d145a0e517ef",
      "code": "MIN_CONSTRAINT_VIOLATION",
      "detail": "must be greater than or equal to 1",
      "source": {
        "pointer": "amount"
In case of an error from SecurePay API, the following response is returned. 
Response
Required
Description
errors
List of error objects
Error
Error
Required
Description
Unique identifier for the error
Endpoint specific error code
detail
Detailed error description
source.pointer
If error is related to specific field in request, this param will be populated with the field name
Other Integration methods
Overview
SecurePay offers other integration methods to accept payments through your website or handle bill payments.
To find out more about services or obtain credentials to use these services, contact the team here.
Integration guides
    XML API Integration
    The XML API ts transaction information to SecurePay for processing. It also supports Fraud Guard.
    Hosted Payment Pages - SecureFrame
    SecureFrame offers a secure and flexible hosted service that helps you meet your PCI DSS obligations. It also supports Fraud Guard.
    Hosted Payment Pages - Direct Post
    Direct Post is a payment service that accepts customer data posted directly from a form on your website. It also supports Fraud Guard.
    Online Bill Payment – SecureBill Hosted Payment Page
    A hosted payment page tailored to bill payments, SecureBill is suitable for government and organisations that render invoices. It also supports Fraud Guard.
    XML API – Card Storage and Scheduled Payments
    Secure XML API – Card Storage and Scheduled Payments transmits information to SecurePay to securely store customer details.
    SecurePay Batch
    SecurePay Batch is a method for uploading transactions in a file for processing once daily.
    SecurePay Merchant Portal User Guide
    This guide provides an overview of how to use the Merchant Portal. The portal offers payment tools and reporting features to help manage your account.
    SecurePay Response Codes
    Bank and SecurePay Response Codes.
    SecurePay 3D Secure 2
    3D Secure 2 is our solution to help ensure cardholder authentication and protection against fraudulent transactions.
e-Commerce extensions
Overview
SecurePay offer a smooth integration with the most popular e-Commerce extensions, and we maintain the latest selection.
eCommerce compatibility of payment features
Apple Pay is available on NAB, ANZ and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
You must be using SecurePay API to use the payment features
Gateway or SecurePay Online Payments accounts are supported
To use the payment features you need to sign up and enable through SecurePay here
Magento
See compatibility of e-Commerce extensions in overview here
SecurePay API Magento Install Instructions
This guide outlines the download and install instructions for the SecurePay API Magento extension.
The current version of the SecurePay API Magento extension is 2.0.1
        Latest version
            Version 2.0.1, 20th June 2023
                Updated to be compatible with php8.2
Part 2 - Install the extension
Upload the extension file to the Magento2_root/app/code folder of your Magento installation using FTP, SFTP or SSH - depending on your server setup
Unzip the extension
Connect into php the server (via SSH) and execute the following commands:
bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:clean
php bin/magento cache:flush
Part 3 - Configure the SecurePay extension
Enable and configure SecurePay API in Magento Admin under Stores > Configuration > Sales -> Payment Methods > SecurePay Payment
Find the SecurePay API payment method and open to view the configuration options 

Edit options where required
Clear Magento cache
OpenCart
See compatibility of e-Commerce extensions in overview here
SecurePay API OpenCart Install Instructions
This guide outlines the download and install instructions for the SecurePay API OpenCart extension.
The current version of the SecurePay API OpenCart extension is 1.3.0
        Latest version
            Version 1.3.0, 4th August 2022
                General fix
Login to your OpenCart admin interface
Navigate to Extensions > Installer
Click on the  button
Browse your computer to find the downloaded extension (with .ocmod.zip extension), and upload the extension
Navigate to Extensions > Modifications
Click on the  button
Part 3 - Configure the SecurePay extension
Navigate to Extensions > Extensions
Select Payments in Choose the extension type dropdown 

Click the Plus sign on the right of SecurePay Payment method to enable it 

After the payment method has been enabled, click the Pen button to open the configuration options. Fill the form with required information and click the Save button on the top right. 

WooCommerce
See compatibility of e-Commerce extensions in overview here
SecurePay API WooCommerce Install Instructions
This guide outlines the download and install instructions for the SecurePay API WooCommerce extension.
The current version of the SecurePay API WooCommerce extension is 2.0.3
        Latest version
            Version 2.0.3, 25th July 2023
                Updated: Ensure that card token is always present before making payment call
Login to your Wordpress admin interface
Navigate to Plugins > Add New
Click on the Upload Plugin button at the top of the page
Browse your computer to find the downloaded extension, and upload the extension
Click the Activate button to activate the extension
Part 3 - Configure the SecurePay extension
Click on WooCommerce > Settings then click on the Payments tab
Find the SecurePay API payment method and click on the Manage button to open the configuration options 

Edit options where required and save
PrestaShop
See compatibility of e-Commerce extensions in overview here
SecurePay API PrestaShop Install Instructions
This guide outlines the download and install instructions for the SecurePay API PrestaShop extension.
The current version of the SecurePay API PrestaShop extension is 1.4.0
        Latest version
            Version 1.4.0, 4th August 2022
                General fix
Login to your PrestaShop admin interface
Navigate to Modules > Module manager
Click on the Upload a module button at the top of the page
Browse your computer to find the downloaded extension, and upload the extension
Part 3 - Configure the SecurePay extension
Click on Modules > Module manager
Find the SecurePay API payment method and click on the Configure button to open the configuration options 

Edit options where required and save
Troubleshooting Guide
This troubleshooting guide provides information regarding common issues and mistakes with regard to merchant's Apple Pay setup, payment token expired or incorrect input format. It also provides information about fixes, knowledge bases, and support for those issues.
List of supported issues
 Apple Pay Domain Verification Failed 
Possible cause and solution: 
                 Domain Verification
              file hosted on your domain is not correct or not accessible over internet as Apple needs to access the file for verification purpose.
Path to the 
                             Domain Verification
                          file is not correct according to the guidelines, please follow the instructions here for Apple Pay Account setup.
                         Expected URL for Domain Verification file is https://{domain-name}/.well-known/apple-developer-merchantid-domain-association.
 Mismatch in Amount being settled 
Possible cause and solution: 
 Amount sent in request is not in the expected format.
If you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent). 
Please refer please follow the instructions here for expected input formats.
Support
Contact Us
Our support email address is [email protected]
System status
GET https://payments-stest.npe.auspost.zone/v2/health
curl https://api.payments-stest.npe.auspost.zone/v2/health -X GET 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer xxxxxxxx
    "status": "UP"
To check the system / health status of the SecurePay API, make the following request.
HTTP Request
Please note that request timeout is 30 seconds.
GET https://payments-stest.npe.auspost.zone/v2/health
Header Parameters 
Parameter
Required
Description
Authorization
Required
Refer to client credentials for more information on obtaining an access token.
Response
Description
status
The health status of SecurePay API. Status could be UP or DOWN.