Navbar
  • Integrating with SecurePay
  • SecurePay API
  • Other Integration methods
  • e-Commerce extensions
  • Troubleshooting Guide
  • Support

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

    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 URL
    Sandbox https://welcome.api2.sandbox.auspost.com.au/oauth/token
    Live 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 Type 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.

    Response

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

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

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

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

    Merchant Initiated Transactions

    The Payment Intention Type (paymentIntentionType) is used for Merchant Initiated Transactions (MIT) which are initiated by the merchant based on a pre-existing agreement with the cardholder. The paymentIntentionType (also known as standingInstructionType) is used by SecurePay to identify a transaction as recurring, installment, UCOF (Unscheduled Credential on File) or CIT (Customer Initiated). paymentIntentionType supports Visa & Mastercard Scheme Mandates and allows SecurePay to provide the required parameters to the acquirer/scheme. When performing a payment with paymentIntentionType and then storing the payment instrument, the payment will act as the account verification and a Standing Instruction ID (SIID) will be returned.

    PaymentIntentionType Definitions
    Value Description
    UCOF Unscheduled Card On File. Used for adhoc payments triggered using a stored card.
    e.g. an auto-top of an account whenever the amount drops below a certain threshold
    Recurring When the card is being used for fixed, regular intervals for an ongoing service.
    e.g. fortnightly gym membership
    Installments When the card is being used to pay instalments on a single purchase.
    e.g. pay four $100 monthly payments for a $400 sofa
    CIT Customer Initiated Transaction. When the consumer is present and provides their payment credentials
    Standing Instruction ID

    The Standing Instruction ID (SIID) is a unique identifier provided by a card scheme that links the payment history between the customer and merchant. Send this value when storing the payment instrument and when making subsequent transactions using a stored credential to link to the previous account verification. Subsequent transactions will be linked to the initial transaction when viewed in Merchant Portal.

    When to send paymentIntentionType and SIID

    paymentIntentionType and SIID are optional fields, however the below is recommended.

    Scenario Request to SecurePay API Returned in response
    Create Payment - Not storing payment instrument No change required No change
    Create Payment - With intention to Store payment instrument paymentIntentionType paymentIntentionType
    SIID
    Store Instrument - After Payment paymentIntentionType
    SIID from Create Payment response    		 paymentIntentionType and SIID from request
    Store Instrument - no previous payment paymentIntentionType paymentIntentionType from Request
    SIID
    Create Payment using stored instrument paymentIntentionType

    If paymentIntentionType is Installments or Recurring send SIID of Stored Instrument (otherwise new SIID may be generated), optional for UCOF    		 paymentIntentionType from Request

    SIID from request or from Stored Instrument if not in request
    Create Payment Schedule paymentIntentionType paymentIntentionType
    SIID

    JavaScript SDK

    Environment Details

    Environment SecurePay UI JavaScript SDK URL
    Sandbox https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js
    Live https://payments.auspost.net.au/v3/ui/client/securepay-ui.min.js

    How does it work?

    <!doctype html>
<html>
  <body>
    <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:

    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.

    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:

    These commands are sent to the UI Component using the HTML5 window.postMessage API.

    mySecurePayUI.tokenise() will the following action:

    mySecurePayUI.reset() will clear the card form fields in Checkout and Add Card view modes.

    UI Config Object

    <!doctype html>
<html>
  <body>
    <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 Type Required Description
    containerId string Yes The HTML element id where the UI Component is to be inserted
    mode string No 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 Yes The HTML <script> element id which references securepay-ui.min.js
    clientId string Yes Your client id
    merchantCode string Required if you have multiple merchant codes associated with your account
    card card-object Yes 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 Type 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 Type 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 Type Required Description
    font font-object Configure the styling for the fontobject of the element.
    Font Object
    Option Type Required Description
    family string Configure the font-family of the font for the element. Eg: "Times New Roman", Times, serif
    size 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 Type 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>
<html>
  <body>
    <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.

    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

    (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 Mode 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 Mode 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) dcc 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) dcc 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"
            }
        } 
    }
    Name 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.
    bin 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

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

    Name 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

    Name 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"
          }
        }
      ]
    }
    Name Required Description
    id Yes Unique identifier for the error
    code Yes Endpoint specific error code
    detail Yes Detailed error description
    source.pointer No If error is related to specific field in request this param will be populated with field name

    Rest API

    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 Type 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.
    ip 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.
    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. 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. Should not be longer than 30 characters including - alphanumeric and _
    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.
    paymentIntentionType String Optional Also known as Standing Instruction Type. Specifies the intention of the payment. Valid values are CIT, UCOF, Recurring, Installments see PaymentIntentionType Definitions.
    • Send if intending to store the payment instrument via a Store Instrument request so that an SIID can be returned.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    • A Standing Instruction ID (SIID) will be returned if UCOF, Recurring, Installments provided.

    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 Type Required Description
    merchantCode String Required Merchant account for which the funds are collected.
    ip 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.

    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 Type 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.
    ip 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 Type 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.
    ip 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.
    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. 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. Should not be longer than 30 characters including - alphanumeric and _
    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:

    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 Type Required Description
    ip 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.

    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 Type Required Description
    ip 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.

    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 Type Required Description
    merchantCode String Required Merchant account for which the funds are collected.
    ip 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.

    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

    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. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _

    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 Type 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.
    ip 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.
    orderId String Optional A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId.
    paymentIntentionType String Optional Also known as Standing Instruction Type. Specifies the intention of the payment. Valid values are UCOF, Recurring, Installments see PaymentIntentionType Definitions.
    • Send if intending to store the payment instrument via a Store Instrument request so that an SIID can be returned.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    • A Standing Instruction ID (SIID) will be returned if UCOF, Recurring, Installments provided.
    SIID String Optional SIID (Standing Instruction ID) is a unique identifier provided by a card scheme that links to the payment history between the customer and merchant.
    • When making a payment for merchant-managed stored cards and schedules, send the SIID along with the paymentIntentionType in the request when performing subsequent transactions, to ensure the transaction is treated as a subsequent transaction.
    • If a card is stored in SecurePay and has an SIID, and SIID is not sent, the SIID stored on the Payor will be used.
    • If the SIID is provided in request, it will be used over the SIID stored on the payor. Subsequent transactions will be linked to the initial transaction when viewed in Merchant Portal.
    • Applies to Visa and Mastercard cards only and is available on selected NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.

    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 Type Required Description
    merchantCode String Required Merchant account for which the funds are collected.
    ip 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.
    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. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _

    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.
    ip Required A customer IP address. Must be a valid IPv4 or IPv6.

    Request Parameters

    Parameter Type Required Description
    paymentIntentionType String Optional Also known as Standing Instruction Type. Specifies the intention of the payment. Valid values are UCOF, Recurring, Installments see PaymentIntentionType Definitions.
    • If paymentIntentionType is not sent, paymentIntentionType will be defaulted to UCOF to ensure compliance with VISA and Mastercard regarding stored card details.
    • A Standing Instruction ID (SIID) will be returned if UCOF, Recurring, Installments provided.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    SIID String Optional SIID (Standing Instruction ID) is a unique identifier provided by a card scheme that links to the payment history between the customer and merchant.
    • If making a payment and then creating payment instrument, SIID is recommended to ensure a new Account verification is not triggered. During Create Payment when paymentIntentionType is sent, an SIID will be returned in the response. Send the SIID during Create Payment Instrument (this request) to ensure the original transaction acts as the account verification. If the SIID from the Create Payment is not sent, an account verification may be performed and a new SIID will be returned.
    • Applies to Visa and Mastercard cards only and is available on selected NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.

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

    Path Variables

    Parameter Description
    customerCode A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _

    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.
    ip 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. Deleting a stored payment instrument will also suspend any associated schedules.

    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. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _

    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.
    ip Required A customer IP address. Must be a valid IPv4 or IPv6.

    Response

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

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

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

    Name Type 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.
    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
    Y Y Payment continues for processing
    N N Payment continues for processing
    Y Not Provided Payment continues for processing
    N Y 3DS2 Payment is declined with
    Response Code: 517 Response Text:Liability Shift Indicator
    Y N 3DS2 Payment is declined with
    Response Code: 517 Response Text:Liability Shift Indicator
    N Not Provided 3DS2 Payment is declined with
    Response 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.

    Name Type 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)

    Name Type 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.
    ip 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.
    paymentIntentionType String The paymentIntentionType provided in the request.
    SIID String Returned in request if paymentIntentionType is provided.
    • SIID (Standing Instruction ID) is a unique identifier provided by a card scheme that links to the payment history between the customer and merchant.
    • For merchant-managed stored cards and schedules, the SIID along with the paymentIntentionType should be sent in the request when performing subsequent transactions, to ensure the transaction is treated as a subsequent transaction.
    • Send this value when storing the payment instrument and when making subsequent transactions using a stored credential to link to the previous account verification.
    • If a card is stored in SecurePay and has an SIID, and SIID is not sent, the SIID stored on the Payor will be used. If the SIID is provided in request, it will be used over the SIID stored on the payor.
    • Subsequent transactions will be linked to the initial transaction when viewed in Merchant Portal.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    Account Verification Transaction Object

    A completed Account Verification transaction returned by Create Account Verification Transaction

    Name Type 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.
    ip 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

    Name Type 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.
    ip 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.

    Name Type Description
    merchantCode String Merchant account for which the funds are collected.
    ip 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.

    Name Type 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.
    ip 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

    Name Type 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.
    ip 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

    Name Type 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.
    ip 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

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

    Name Type 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.
    bin 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.
    paymentIntentionType String The paymentIntentionType provided in the request.
    SIID String SIID (Standing Instruction ID) is a unique identifier provided by a card scheme that links to the payment history between the customer and merchant.
    • Returned in request if paymentIntentionType is provided.
    • Send this value when storing the payment instrument and when making subsequent transactions using a stored credential to link to the previous account verification.
    • Subsequent transactions will be linked to the initial transaction when viewed in Merchant Portal.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    Refund Object

    A completed refund returned by Refund Payment.

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

    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
    201 PAYMENT_DECLINED -- Payment declined Payment Gateway Yes 1005 or 1031 cents in amount field
    *Certain scenarios are not testable such as non-retriable declines
    201 INSUFFICIENT_FUNDS -- Insufficient funds on payment instrument Payment Gateway Yes 1051 cents in amount field
    201 EXPIRED_CARD -- Payment Instrument is expired Payment Gateway Yes 1033 cents in amount field
    201 WITHDRAWAL_LIMIT -- Exceeds withdrawal amount limit Payment Gateway Yes 1061 cents in amount field
    201 UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported Payment Gateway No
    201 INVALID_CVV -- Invalid CVV number Payment Gateway No
    201 LOST_OR_STOLEN_CARD -- Lost or stolen card Payment Gateway Yes 1007 cents in amount field
    201 ACCOUNT_LOCKED -- Account is locked Payment Gateway No
    201 WITHDRAWAL_LIMIT -- Exceeds withdrawal frequency limit Payment Gateway Yes 1065 cents in amount field
    201 GATEWAY_ERROR -- The payment gateway was not able to process the request due to an unexpected error Payment Gateway Yes 1009 cents in amount field
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for card payments or requested payment feature SecurePay API Yes
    400 INVALID_ORDER_ID -- Order id has to be unique per merchant SecurePay API Yes send payment with an order id that was used by a previous payment
    400 INVALID_ORDER_ID_FORMAT -- OrderId contains characters which are not allowed SecurePay API Yes send an order id which contains any of these < > “ characters
    400 TOKEN_NOT_FOUND -- Token does not exist SecurePay API Yes send payment using a token which does not exist or does not belong to the customer
    400 INVALID_MERCHANT_CODE -- Merchant Code is not listed in client account SecurePay API Yes send payment with merchant not listed in account
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes send payment with an IP address that does not conform to the IPv4 or IPv6 standard
    400 INVALID_AMOUNT -- Invalid amount for a payment SecurePay API Yes send an amount that does not match the business rules for a specific operation (Eg: Different amount for pre-auth and capture pre-auth)
    400 EXCEEDED_PREAUTH_AMOUNT -- Exceeded preauthorised amount SecurePay API Yes send a partial or full cancel amount that exceeds pre-auth amount
    400 INVALID_DCC_DETAILS -- No matching dcc order could be found for a payment request SecurePay API Yes send payment using using initaitedOrderId that does not exist or was used by a previous payment
    400 INVALID_DCC_DETAILS - DCC Payment with Stored payment instrument attempted SecurePay API Yes Attempt a DCC payment with a stored instrument
    400 INVALID_DCC_DETAILS - DCC payment with SIID and paymentIntentionType attempted SecurePay API Yes Attempt a DCC payment with SIID or paymentIntentionType
    401 UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. SecurePay API Yes
    500 GATEWAY_ERROR -- Unexpected error while processing the request SecurePay API No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    Payment Instrument Error Codes

    Payments instruments endpoints uses the following error codes:

    Response Code Error Code Originating System Testable
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for card payments SecurePay API Yes
    400 INVALID_TOKEN -- Token provided in payload is either already stored against some customer or does not exist in the system. SecurePay API Yes
    400 INVALID_TOKEN_SIID_COMBINATION -- Standing Instruction ID (SIID) and Token combination provided in payload does not exist in the system. SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    401 UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 GATEWAY_ERROR -- Error while deleting payment instrument Payment Gateway No
    500 GATEWAY_ERROR_RETRY -- Timeout while storing the instrument, please retry Payment Gateway No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    Refund Error Codes

    Refund endpoints uses the following error codes:

    Response Code Error Code Originating System Testable
    201 REFUND_NOT_ALLOWED -- If refund amount is more than the previous paid order amount Payment Gateway Yes
    400 INVALID_ACCOUNT -- Account has not been configured for card payments SecurePay API Yes
    400 TRANSACTION_NOT_FOUND -- OrderId passed in refund request does not exist Payment Gateway Yes
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    401 UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 GATEWAY_ERROR -- Error while doing refund Payment Gateway No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    Tokenise Instrument Error Codes

    Tokenise endpoints uses the following error codes:

    Response Code Error Code Originating System Testable
    400 BAD_REQUEST -- Send malformed JSON in request SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for card payments SecurePay API Yes
    400 INVALID_CVV -- Invalid CVV details Payment Gateway Yes
    400 INVALID_PIN -- Invalid PIN details Payment Gateway Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    400 DCC_QUOTE_IN_PROGRESS -- Could happen in dcc mode only. When tokenise call is made prior onDCCQuoteSuccess was invoked SecurePay API Yes
    400 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 Yes
    400 INVALID_ORDER_TOKEN -- Could happen in dcc mode only. When tokenise call is made after onDCCQuoteError callback invoked SecurePay API Yes
    500 SYSTEM_ERROR -- Tokenise error from SecurePay API SecurePay API Yes
    500 GATEWAY_ERROR -- Tokenisation error from Payment Gateway Payment Gateway No
    500 INVALID_CARD_DETAILS -- Invalid card details (could be number, cvv, expiry date, mismatch of cc details) Payment Gateway Yes
    500 PRE_AUTH_FAILED -- Pre-auth failed (could be cvv or any other reason, e.g. card blocked) Payment Gateway Yes
    500 INVALID_REQUEST_DATA -- Invalid request data (e.g. Invalid IP address) Payment Gateway Yes
    500 INVALID_ACCOUNT_DETAILS -- Invalid bank account details (bsb, account number, account name) Payment Gateway No
    500 INSUFFICIENT_FUNDS -- Insufficient funds Payment Gateway Yes
    500 EXPIRY_DATE -- Invalid expiry date Payment Gateway No
    500 UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported Payment Gateway No
    500 RESTRICTED_CARD_OR_ACCOUNT -- Restricted card or account Payment Gateway No
    500 LOST_OR_STOLEN_CARD -- Lost or stolen card Payment Gateway No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    Testing

    You can use the following test card numbers in our sandbox environment.

    Card Type Card Number
    Visa 4111111111111111
    Visa 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.

    BIN Currency
    4242424242424242 triggers scenario when card currency is not in the list of supported currencies or AUD, results in payment in AUD currency.
    4314261614350081 USD
    5139006234627198 EUR
    5432500000000006 NZD
    5253030000000000 GBP
    4472010000000000 IDR
    5303990000000005 CRC
    5306950000000006 COP
    4073440000000002 JMD
    4106750000000005 ZAR
    4600050000000001 PHP
    5440140000000001 ARS
    4196070000000009 INR
    4030860000000003 AED
    5486530000000008 CLP
    4147900000000007 TTD
    4406960000000007 UYU
    5579050000000005 MXN
    4791320000000007 GYD
    4006700000000001 HKD
    4518770000000005 GTQ
    5248050000000006 JPY
    5240400000000001 SGD
    5500180000000004 CHF
    5269480000000009 NOK
    4365110000000008 MYR
    5476640000000007 BBD
    4107340000000004 TZS
    4301980000000001 QAR
    5192900000000008 CAD
    4757700000000002 BRL

    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 support@securepay.com.au if you need an alternate testing set up.

    To use the test cards below you must use:

    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 ECI
    Frictionless Y VISA 4100000000000100 N/A 05
    Frictionless Y MasterCard 5100000000000107 N/A 02
    Frictionless Y AMEX 340000000000108 N/A 05
    Challenge Y VISA 4100000000005000 123456 05
    Challenge Y MasterCard 5100000000005007 123456 02
    Challenge Y AMEX 340000000005008 123456 05
    Challenge failed N VISA 4100000000300005 111111 Per card scheme
    Challenge failed N MasterCard 5100000000300002 111111 Per card scheme
    Challenge failed N AMEX 340000000300003 111111 Per card scheme
    Unavailable U VISA 4100000000400003 N/A Per card scheme
    Unavailable U MasterCard 5100000000400000 N/A Per card scheme
    Unavailable U AMEX 340000000400001 N/A Per card scheme
    Rejected R VISA 4100000000500000 N/A Per card scheme
    Rejected R MasterCard 5100000000500007 N/A Per card scheme
    Rejected R AMEX 340000000500008 N/A Per card scheme
    Attempted A VISA 4100000000100009 N/A 06
    Attempted A MasterCard 5100000000100006 N/A 01
    Attempted A AMEX 340000000100007 N/A 06

    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:

    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

    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 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
    Technical Details
    Initiate Session

    Apple Pay Button on web

    <html>
<head>
    <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>
<body>
    <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>

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

    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

    1. 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.
    2. 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.
    3. 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

    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 Type 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.
    ip String Required A customer IP address. Must be a valid IPv4 or IPv6.
    Response
    Name Type Description
    merchantCode String Merchant account for which the funds are collected.
    ip 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 Type Required Description
    amount Integer Required An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated.
    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.
    ip 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 Type 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
    Name Type 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.
    ip 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 Type Required Description
    merchantCode String Required Merchant account for which the funds are collected.
    ip 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.

    Response

    Name Type 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
    paid 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
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_REQUEST_DATA -- Invalid request data SecurePay API Yes
    400 INVALID_REQUEST_DATA -- Unable to decrypt Payment Data SecurePay API Yes
    400 INVALID_REQUEST_DATA -- Amount and Currency mismatch SecurePay API Yes
    400 INVALID_APPLE_PAY_DETAILS -- DomainName is not registered with Apple Pay SecurePay API Yes
    400 INVALID_ORDER_ID -- Order id has to be unique per merchant and must be no longer than 49 characters SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for Apple Pay payments SecurePay API Yes
    500 GATEWAY_ERROR -- Refund failure from Payment provider Provider No
    401 UNAUTHORIZED -- Provided invalid Http access token. Refer to client credentials for more information. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    400 TRANSACTION_NOT_FOUND -- Order doesn't exist or not paid SecurePay API Yes

    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.

    Rest API

    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 Type Required Description
    ip 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.
    bsb 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
    Name Type Description
    ip 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
    bsb 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
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    400 DDA_NOT_FOUND -- The DDA was not found Payment Gateway No
    400 BELOW_DDA_MIN_AMOUNT -- Amount is lower than the DDA min limit Payment Gateway No
    400 EXCEEDED_DDA_MAX_AMOUNT -- Amount is higher than the DDA max limit Payment Gateway No
    400 EXPIRED_DDA -- The DDA has expired Payment Gateway No
    400 INVALID_ACCOUNT -- Account has not been configured for direct entry payments Payment Gateway No
    401 UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API No
    500 GATEWAY_ERROR -- Error while processing the request Payment Gateway No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    PayPal Payments

    How it works

    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

    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.
    ip 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.
    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
    Name 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.
    ip 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.
    ip 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.
    payerId Required The payer id returned from PayPal after customer has completed authorisation.
    Response
    Name 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.
    ip 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.
    paid 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.
    ip 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.
    Response
    Name 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.
    ip 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": "joe.smith@some-email-address.com"
   },
   "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
    Name 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.

    Name Description
    name 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).
    city 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.

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

    Name 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
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_REQUEST_DATA -- Invalid request data SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for PayPal payments SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    400 INVALID_ORDER_ID -- Order id has to be unique per merchant SecurePay API Yes
    401 UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 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:

    Acquiring Bank Visa Mastercard Amex
    NAB ✓ ✓
    Westpac ✓ ✓ ✓
    ANZ ✓ ✓
    CBA ✓ ✓ ✓
    Fiserv FDMSA ✓ ✓ ✓

    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:

    Alternate method: This may increase in load time. Also, this can only be done once you have filled all the 3DS2 required fields.

    Environment Details

    Environment SecurePay 3DS2 JavaScript SDK URL
    Sandbox https://test.api.securepay.com.au/threeds-js/securepay-threeds.js
    Live https://api.securepay.com.au/threeds-js/securepay-threeds.js

    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

    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; visibility:hidden;">

    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

    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":"john.doe@test.com",
    "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 Type 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 Type 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 Type Description
    cc 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 Type 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.
    city required String Name of the City.
    Maximum length of 50 characters.
    state conditional String The state or province as per Country subdivision code defined in ISO 3166-2. Required unless State is not applicable for this country i.e. Aruba.
    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 Type 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 Type 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 Type 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.
    eci 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 Type Description
    id String A unique error id which can be used for troubleshooting.
    code 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.

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

    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 eci Trans Status Authentication Result Liability Shift Indicator
    MasterCard Yes 02 Y Fully Authenticated Y (Liability shifts to Issuer)
    MasterCard Yes 01 A Attempted Authentication Y (Liability shifts to Issuer)
    MasterCard No 00 N Not Authenticated N (Liability stays with Merchant)
    MasterCard No 00 U Unable to authenticate. N (Liability stays with Merchant)
    MasterCard No 00 R Rejected N (Liability stays with Merchant)
    MasterCard Yes 07 Y Fully Authenticated Y (Liability shifts to Issuer)
    Visa Yes 05 Y Fully Authenticated Y (Liability shifts to Issuer)
    Visa Yes 06 A Attempted Authentication Y (Liability shifts to Issuer)
    Visa No 06 A Attempted Authentication N (Liability stays with Merchant)
    Visa No 07 N Not Authenticated N (Liability stays with Merchant)
    Visa No 07 R Rejected N (Liability stays with Merchant)
    Visa Yes 07 Y Fully Authenticated N (Liability stays with Merchant)
    Amex Yes 05 Y Fully Authenticated Y (Liability shifts to Issuer)
    Amex Yes 06 A Attempted Authentication Y (Liability shifts to Issuer)
    Amex No N Not Authenticated N (Liability stays with Merchant)
    Amex No R Rejected N (Liability stays with Merchant)
    Amex No 07 U Unable to authenticate. N (Liability stays with Merchant)

    Transaction Status Reason Codes

    Reason code Detail Description
    01 Card authentication failed If this occurs multiple times for the same card, contact your Acquirer.
    02 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.
    03 Unsupported Device The cardholder used a device that the ACS does not support e.g., unsupported OS, device not considered secure.
    04 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.
    05 Expired card Please check the expiry date of your card and try again.
    06 Invalid card number The card number is invalid. Please check and re-enter the details or try a different card.
    07 Invalid transaction There is an issue with the transaction. The cardholder will need to contact their card Issuer.
    08 No Card record The card does not support 3DS or is not enrolled in 3DS from the Issuer. Please try a different card.
    09 Security failure There is a security failure on this card. Please try a different card.
    10 Stolen card Records show that the card used has been flagged as stolen. The cardholder will need to contact their card Issuer.
    11 Suspected fraud Suspected fraudulent activity has been detected. The cardholder will need to contact their card Issuer.
    12 Transaction not permitted to cardholder This type of transaction is not permitted. The cardholder will need to contact their card Issuer.
    13 Cardholder not enrolled in service The card used is currently not enrolled for 3DS.
    14 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.
    15 Low confidence
    16 Medium confidence
    17 High confidence
    18 Very High confidence
    19 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.
    20 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).
    21 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

    Code Detail Originating System
    104 Invalid Merchant ID.
    The provided clientID is incorrect.    		 SecurePay API
    151 Invalid ISO Currency Code. SecurePay API
    176 Merchant Not Enrolled in 3D Secure. SecurePay API
    180 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
    181 Card Unsupported for 3D Secure. SecurePay API
    182 3D Secure Configuration Error.
    Internal Error occurred preventing 3DS2 process to proceed.    		 SecurePay API
    183 Invalid value for <field>. SecurePay API
    504 Unable to process the request.
    Invalid Token is used or Token is expired.    		 SecurePay API
    515 Unable to process your request.
    Timeout or internal connectivity errors.    		 SecurePay API
    517 Acquirer not configured for 3DS2 for used card type. SecurePay API
    517 Liability Shift indicator error. SecurePay API
    517 Unexpected value for <field>. SecurePay API
    517 <field> must not be Null. SecurePay API
    517 Order not in valid state. SecurePay API
    517 Order intent used is invalid. SecurePay API
    517 Invalid or Duplicate Request. SecurePay API
    517 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

    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 Type Required Description
    ip 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. 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. Should not be longer than 30 characters including - alphanumeric and _
    Response
    Name Type 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.

    Name Type Required Description
    amount Integer Required An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument.
    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.

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

    Name Type 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
    city 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.

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

    Name Type 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
    400 BAD_REQUEST -- Send malformed JSON in request SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    400 INVALID_ACCOUNT -- Account is not configured for fraud check type provided in request Payment Gateway No
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway Payment Gateway No

    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.

    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.

    1. bb: blackbox (The device fingerprint)
    2. complete : true/false flag to denote the process completion.

    See the Iovation Integration Guide for more info:

    Rest API

    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 Type Required Description
    ip 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. 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. Should not be longer than 30 characters including - alphanumeric and _
    Response
    Name Type 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.

    Name Type Required Description
    amount Integer Required An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument.
    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.

    Name Type Required Description Validation rule
    sku 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.

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

    Name Type 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
    city 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.

    Name Type 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
    city 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.

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

    Name Type 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
    400 BAD_REQUEST -- Send malformed JSON in request SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway Payment Gateway No

    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

    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 Type Required Description
    ip 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. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _
    amount Number Required An integer value greater than 0, representing the amount in cents.
    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
    Name Type Description
    ip 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 Type Required Description
    ip 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. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _
    amount Number Required An integer value greater than 0, representing the amount in cents.
    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.
    paymentIntentionType String Optional Also known as Standing Instruction Type. Specifies the intention of the payment. Valid values are Recurring, Installments see PaymentIntentionType Definitions.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
    • A Standing Instruction ID (SIID) will be returned if paymentIntentionType is provided.
    • Payment Intention Type and SIID are optional fields, however please see PaymentIntentionType Definitions for how it is recommended for schedules.
    Response
    Name Type Description
    ip 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.
    paymentIntentionType String The paymentIntentionType provided in the request.
    SIID String SIID (Standing Instruction ID) is a unique identifier provided by a card scheme that links to the payment history between the customer and merchant.
    • Returned in request if paymentIntentionType is provided.
    • Applies to Visa and Mastercard cards only and is available on NAB and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.

    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 Type Required Description
    ip 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
    Name Type Description
    ip 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.

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

    Name Type 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
    400 BAD_REQUEST -- Bad request data SecurePay API Yes
    400 INVALID_REQUEST_DATA -- Invalid request data SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for credit card payments SecurePay API Yes
    400 INVALID_IP_ADDRESS -- Invalid IP address SecurePay API Yes
    401 UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token. SecurePay API Yes
    500 SYSTEM_ERROR -- Error happened in SecurePay API while processing request SecurePay API Yes
    500 GATEWAY_ERROR -- Error from Payment Gateway Payment Gateway No
    504 TIMED_OUT -- Payment Gateway took too long to respond Payment Gateway No

    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

    Name Required Description Type
    errors Yes List of error objects Error

    Error

    Name Required Description
    id Yes Unique identifier for the error
    code Yes Endpoint specific error code
    detail Yes Detailed error description
    source.pointer No 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

    The XML API ts transaction information to SecurePay for processing. It also supports Fraud Guard. SecureFrame offers a secure and flexible hosted service that helps you meet your PCI DSS obligations. It also supports Fraud Guard. Direct Post is a payment service that accepts customer data posted directly from a form on your website. It also supports Fraud Guard. A hosted payment page tailored to bill payments, SecureBill is suitable for government and organisations that render invoices. It also supports Fraud Guard. Secure XML API – Card Storage and Scheduled Payments transmits information to SecurePay to securely store customer details. SecurePay Batch is a method for uploading transactions in a file for processing once daily. 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. Bank and SecurePay Response Codes. 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

    Magento WooCommerce PrestaShop Opencart
    Card Payments / Refunds ✓ ✓ ✓ ✓
    Apple Pay ✓ ✓
    Fraudguard ✓ ✓
    Dynamic Currency Conversion ✓ ✓
    3DS2 ✓ ✓

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

    For previous versions please refer changelog.txt

    Part 1 - Download the extension

    Download the extension to get started:

    Download

    Part 2 - Install the extension

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

    2. Unzip the extension

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

    1. Enable and configure SecurePay API in Magento Admin under Stores > Configuration > Sales -> Payment Methods > SecurePay Payment

    2. Find the SecurePay API payment method and open to view the configuration options

    3. Edit options where required

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

    Part 1 - Download the extension

    Download the extension to get started:

    Download

    Part 2 - Install the extension

    1. Login to your OpenCart admin interface

    2. Navigate to Extensions > Installer

    3. Click on the upload button

    4. Browse your computer to find the downloaded extension (with .ocmod.zip extension), and upload the extension

    5. Navigate to Extensions > Modifications

    6. Click on the refresh button

    Part 3 - Configure the SecurePay extension

    1. Navigate to Extensions > Extensions

    2. Select Payments in Choose the extension type dropdown

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

    4. 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
    Version history

    For previous versions please refer changelog.txt

    Part 1 - Download the extension

    Download the extension to get started:

    Download

    Part 2 - Install the extension

    1. Login to your Wordpress admin interface

    2. Navigate to Plugins > Add New

    3. Click on the Upload Plugin button at the top of the page

    4. Browse your computer to find the downloaded extension, and upload the extension

    5. Click the Activate button to activate the extension

    Part 3 - Configure the SecurePay extension

    1. Click on WooCommerce > Settings then click on the Payments tab

    2. Find the SecurePay API payment method and click on the Manage button to open the configuration options

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

    Part 1 - Download the extension

    Download the extension to get started:

    Download

    Part 2 - Install the extension

    1. Login to your PrestaShop admin interface

    2. Navigate to Modules > Module manager

    3. Click on the Upload a module button at the top of the page

    4. Browse your computer to find the downloaded extension, and upload the extension

    Part 3 - Configure the SecurePay extension

    1. Click on Modules > Module manager

    2. Find the SecurePay API payment method and click on the Configure button to open the configuration options

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

    1. file hosted on your domain is not correct or not accessible over internet as Apple needs to access the file for verification purpose.

    2. Path to the 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:

    1. 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 support@securepay.com.au

    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

    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

    Name Description
    status The health status of SecurePay API. Status could be UP or DOWN.