Navbar
  • Home
  • Authentication
  • Card payments
  • PayPal payments
  • AliPay Payments (Beta)
  • WeChat Payments (Beta)
  • Fraud detection (Beta)
  • Webhooks
  • Errors
  • Other Integration methods
  • Shopping cart integration
  • Support
  • Home

    Overview

    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 fiddle with 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 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://hello.sandbox.auspost.com.au/oauth2/ausujjr7T0v0TTilk3l5/v1/token \
      -H 'Authorization: Basic xxxxxxxx=' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials&scope=https%3A%2F%2Fapi.payments.auspost.com.au%2Fpayhive%2Fpayments%2Fread%20https%3A%2F%2Fapi.payments.auspost.com.au%2Fpayhive%2Fpayments%2Fwrite%20https%3A%2F%2Fapi.payments.auspost.com.au%2Fpayhive%2Fpayment-instruments%2Fread%20https%3A%2F%2Fapi.payments.auspost.com.au%2Fpayhive%2Fpayment-instruments%2Fwrite'
    
    
    {
        "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://hello.sandbox.auspost.com.au/oauth2/ausujjr7T0v0TTilk3l5/v1/token
    Live https://hello.auspost.com.au/oauth2/ausrkwxtmx9Jtwp4s356/v1/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.
    scope String Required Required to determine level of access for your application. Must be separated by a space character if more than one scope is specified. Supported scopes are: 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. Use https://api.payments.auspost.com.au/payhive/payments/read scope to retrieve payments details, https://api.payments.auspost.com.au/payhive/payments/write scope to make payments, https://api.payments.auspost.com.au/payhive/payment-instruments/read scope to retrieve customer payment instrument details, https://api.payments.auspost.com.au/payhive/payment-instruments/write scope to create and store customer payment instruments.

    Response

    Name Type Description
    access_token String The access token string as issued by the server
    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 scope that was requested

    Card payments

    Overview

    SecurePay API lives on your website as a customisable 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 all the financial security, liability 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.

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

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

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

    (6) Merchant server should make use of the token to make a payment to SecurePay API. You must make this payment request from your server.

    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": "2019-04-14T01:26:00.856Z",
        "amount": 1000,
        "status": "paid",
        "bankTransactionId": "7002157044",
        "customerCode": "anonymous",
        "merchantCode": "AAA000DM000",
        "ip": "127.0.0.1",
        "token": "994634932354242",
        "orderId": "efa12a94-7dd6-4078-a033-7b47aa7dc616"
    }
    

    (7) SecurePay API will process the anonymous payment and return a payment response

    (8) Merchant server should proxy the payment response back to the merchant website so that an appropriate response can be returned to the customer browser.

    JavaScript SDK

    Environment Details

    Environment SecurePay UI JavaScript SDK URL
    Sandbox https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js
    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
    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)

    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

    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 global callbacks are available:

    The following card specific callbacks are available:

    See Card SDK callbacks for more information.

    Card SDK Callbacks

    Option Description
    onCardTypeChange(cardType) Invoked when card type changes. Returns the card type ('visa', 'mastercard', 'amex' or 'diners' or 'unknown' if type cannot be determined).
    onCardBINChange(cardBIN) Invoked when BIN changes. Returns the card BIN (Bank Identification Number).
    onFormValidityChange(valid) Invoked when card form validity state changes. Returns a boolean flag indicating form validity.
    onTokeniseSuccess(tokenisedCard) Invoked when card is successfully tokenised. Returns the Tokenised Card that was created.
    onTokeniseError(error) Invoked when card tokenization failed

    Global SDK Callbacks

    Option Description
    onLoadComplete() Invoked when the UI Component has loaded
    onLoadError() - Deprecated Invoked when the UI Component did not load successfully

    Tokenised Card Object

        {
            "merchantCode": "YOUR_MERCHANT_CODE",
            "token": "520592516621111",
            "createdAt": "2019-04-14T01:26:00.856Z",
            "scheme": "visa",
            "bin": "411111",
            "last4": "1111",
            "expiryMonth": "10",
            "expiryYear": "20"      
        }
    
    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.
    createdAt A timestamp when card was tokenised, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    scheme A card scheme, e.g. visa, mastercard, diners, amex.
    bin Bank identification number.
    last4 The last 4 digits of the card number. (Please note the number of digits returned may vary due to the card scheme, eg: 3 digits may be returned)
    expiryMonth Two digit number representing the card expiry month.
    expiryYear Two digit number representing the card expiry year.

    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

    Create Payment

    Make a payment for a given card token.

    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": "2019-04-14T01:26:00.856Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "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"
    }
    

    If the user making the payment is known, it's recommended to use Create Payment instead. 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, 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. If not provided, SecurePay API will assign a unique id for the order.
    fraudCheckDetails Object Optional A fraud check details object.

    Response

    The Payment that was successfully created.

    Create PreAuth Payment

    Used to pre-authorise a payment against a token.

    Please make sure you do not leave the pre-auth in an incomplete state. You should either capture the pre-auth payment, or cancel the pre-auth payment. If left in incomplete state, funds on the card will be held for longer period of time causing frequent customer complains.

    To pre auth a payment, 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, 
              "merchantCode": "YOUR_MERCHANT_CODE", 
              "token": "de305d54-75b4-431b-adb2-eb6b9e546014", 
              "ip": "127.0.0.1", 
              "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
            }
    
    {
        "createdAt": "2019-04-14T01:26:00.856Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "ip": "127.0.0.1",
        "amount": "10000",
        "status": "success",
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Transaction successful"    
    }
    

    Used to pre-authorise a payment using a token.

    For capturing the pre-auth please go to Capture Payment or to cancel the pre-auth go to Cancel PreAuth Payment

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

    Response

    The PreAuth Payment that was successfully created.

    Cancel PreAuth Payment

    Used to cancel a pre-authorisation for a payment, using it's order id.

    Cancellation is always for the full amount. Also cancellation can't occur after a capture or a cancellation has already been made.

    To cancel a pre-auth payment, 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/{orderId}/cancel -X POST
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ "merchantCode": "YOUR_MERCHANT_CODE", 
              "ip": "127.0.0.1"
              }'
    
    {
         "merchantCode": "YOUR_MERCHANT_CODE",
         "ip": "127.0.0.1",
         "orderId": "d2b65e49-e163-43ca-bd72-78dafsfe79-78g1d4c23",
         "amount": 1000,
         "gatewayResponseCode": "00",
         "gatewayResponseMessage": "Transaction successful"
    }
    

    Used to cancel a pre-authorised payment.

    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.

    Response

    The Cancel PreAuth Payment Object that was successfully cancelled.

    Create Capture Payment

    Used to capture a pre-authorisation payment, using it's order id

    Capture payment must be 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 payment, 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 "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ "amount": 10000, 
              "merchantCode": "YOUR_MERCHANT_CODE", 
              "ip": "127.0.0.1"
              }'
    
    {
         "createdAt": "2019-04-14T01:26:00.856Z",
         "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"     
    }
    

    Used to capture a pre-authorised payment.

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture

    Path Variables

    Parameter Description
    orderId The orderId 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.
    Idempotency-Key Required 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.
    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 Customer)

    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": "2019-04-14T01:26:00.856Z",
        "customerCode": "YOUR_CUSTOMER_CODE",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "amount": "10000",
        "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. You will be able to retrieve and search customer payment history using this identifier.

    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.

    Response

    The Payment 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": "2019-04-14T01:26:00.856Z",
        "customerCode": "YOUR_CUSTOMER_CODE",
        "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "brandType": "credit",
        "brandCategory": "standard",
        "scheme": "visa",
        "bin": "424242",
        "last4": "4242",
        "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.

    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.

    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": "2019-04-14T01:26:00.856Z",
            "customerCode": "YOUR_CUSTOMER_CODE",
            "token": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "brandType": "credit",
            "brandCategory": "standard",
            "scheme": "visa",
            "bin": "424242",
            "last4": "4242",
            "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.

    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.

    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.

    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.

    Refund Payment

    Used to refund a previous payment.

    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 "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ "amount": 10000, 
              "merchantCode": "YOUR_MERCHANT_CODE",  
              "ip": "127.0.0.1"
            }'
    
    {
        "createdAt": "2019-04-14T01:26:00.856Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode" : "anonymous",
        "amount": "10000",
        "status": "paid",
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014"
    }
    

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds

    Header Parameters

    Parameter Required Description
    Idempotency-Key Required This key allows a client to safely retry the refund order 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 refund 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.
    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.

    Payment Objects

    Fraud Check Details Object

    The provider reference number of the fraud check result could be passed as a part of payment request or pre-authorise a payment request

    Name Type Required Description
    providerReferenceNumber String Required The provider reference number returned by Fraud Detection Endpoint could be find in Fraud Check Result Object.

    Payment Object

    A completed payment returned by Create Payment and Create Anonymous Payment

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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 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.
    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.

    PreAuth Payment Object

    A completed payment returned by Create Preauth Payment

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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 payment. Valid values are success failed unknown. If the preauth payment was processed and succeeded the status field in payload response is set to success. If preauth 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.
    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 PreAuth Payment Object

    A pre-authorisation that was cancelled by Cancel PreAuth Payment.

    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.
    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 Create Capture Payment.

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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 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.
    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.

    Payment Instrument Object

    A customer payment instrument object created by Create Payment Instrument, but also returned by List Payment Instruments, Retrieve Payment Instrument, List Payments for a customer.

    Name Type Description
    createdAt String A timestamp when payment instrument was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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.
    brandType String Brand of payment instrument. E.g. credit, debit, charge card etc. Refer to Bin base lookup for more details.
    brandCategory String Category of payment instrument. E.g. standard, premium, business etc. Refer to Bin base lookup for more details.
    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 4 digits of the card number. (Please note the number of digits returned may vary due to the card scheme, eg: 3 digits may be returned)
    expiryMonth String Two digit number representing the card expiry month.
    expiryYear String Two digit number representing the card expiry year.

    Refund Object

    A completed refund returned by Refund Payment.

    Name Type Description
    createdAt String A timestamp when refund was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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.
    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

    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
    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 -- Reached withdrawal limit Payment Gateway Yes 1061 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 INVALID_ACCOUNT -- Account has not been configured for card payments 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 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)
    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
    500 SYSTEM_ERROR -- Payment error from SecurePay API SecurePay API Yes 1030 cents in amount field

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

    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

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

    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

    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": "2019-04-14T01:26:00.856Z",
        "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 timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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": "2019-04-14T01:26:00.856Z",
        "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 timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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": "2019-04-14T01:26:00.856Z",
        "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 timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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

    AliPay Payments (Beta)

    Overview

    AliPay is an eWallet payment method which is a secure place where your shoppers can store funds to be used online. There are different ways for customers to make payments. Each of the payment methods is explained below in details.

    How it works

    In store customer QR code

    1.1. Customer is logged into AliPay app and provides the QR code to merchant. Merchant scans this QR code and makes a call to your server to make an Initiate AliPay Txn.

    1.2. Your server then proxies the request to perform the Initiate AliPay Txn to SecurePay API.

    1.3. SecurePay API sends the request to AliPay to initiate transaction.

    2.1. Once the transaction is completed, AliPay notifies customer and SecurePay API.

    2.2. Your server receives an AliPayPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In store merchant QR code

    1.1. Merchant makes a call to your server to make an Initiate AliPay Txn. Your server then proxies the request to perform Initiate AliPay Txn to SecurePay API.

    1.2. SecurePay API sends the request to AliPay to initiate transaction.

    2.1. AliPay sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate AliPay Response from SecurePay API which contains the QR Code.

    2.3. Merchant provides this QR code to the customer.

    3.1. Customer scans the QR code and makes a payment.

    4.1. Once the transaction is completed, AliPay notifies customer and SecurePay API.

    4.2. Your server receives an AliPayPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In Web Browser

    1.1. Customer initiates a purchase on a website. Your website makes a call to your server to make an Initiate AliPay Txn.

    1.2. Your server then proxies the request to perform the Initiate AliPay Txn to SecurePay API.

    1.3. SecurePay API sends the request to AliPay to initiate transaction.

    2.1. AliPay sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate AliPay Response from SecurePay API which contains QR code.

    3.1. Customer scans the QR code and makes a payment.

    4.1. Once the transaction is completed, WeChat/AliPay notifies customer and SecurePay API.

    4.2. Your server receives an AliPayPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In App

    1.1. Customer is logged into AliPay app and initiates the purchase. Customer app makes a call to your server to make an Initiate AliPay Txn.

    1.2. Your server then proxies the request to perform the Initiate AliPay Txn to SecurePay API.

    1.3. SecurePay API sends the request to AliPay to initiate transaction.

    2.1. AliPay sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate AliPay Response from SecurePay API which contains paymentUrl.

    2.3. Your server proxies paymentUrl to the customer.

    3.1. Customer is redirected to paymentUrl page and makes the payment.

    4.1. Once the transaction is completed, AliPay notifies customer and SecurePay API.

    4.2. Your server receives an AliPayPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    Rest API

    Initiate AliPay Transaction

    To initiate AliPay transaction:

    POST https://payments-stest.npe.auspost.zone/v2/wallets/alipay/payments/initiate
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/alipay/payments/initiate -X POST 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ 
                "merchantCode": "YOUR_MERCHANT_CODE", 
                "ip": "127.0.0.1",
                "amount": 10000, 
                "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
                "orderDescription": "text shown to buyer",
                "paymentChannel": "InBrowser",
                "redirectUrls": {
                    "successUrl": "http://<success url>",
                }
            }'
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "ip": "127.0.0.1",
        "amount": 10000,
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "status": "inprogress",
        "paymentChannel": "InBrowser",
        "paymentUrl": "https://mpay.royalpay.com.au/api/v1.0/gateway/partners/PINE/orders/5742521-11bf-4cbb-983a-dcbc8193480/pay?time=1536211158022&nonce_str=nonce&sign=68685f6bfe62&redirect=http://<success url>",
        "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAACHElEQVR42u2aS47DIBBEYeVjcFMb35QjzNIrmK4qSDR2Is2WFpYVOfbLwk3R34T2n+MnLGxhC1vYwjxgNeA4eGGfp51Xaq3g7uYLw3XZt0LGPssOAF+rN6yMmyUaRmtEwrtHzG7GK2U8MjIcfjGzA9cdCj+pBI8YRR64hfXUjNO+7IWpMTouWODv+dG/TY3146K8h2c+v8WsmbFKhxxCqgHbWb4rh0S1u8LMFJFhKF4Mu/gKzfPCFYY9e0nnLUPeuJnpqO+Oa3KsIc52gGZJir8mhr9LPz1mBjkZZ03bVR6M6/4MRrNjTZtXGSNzDNqExmneMAVcMMoe6cqw+ps3zF6fwla9gxVH+cP7nrAa3ulilrDNRM+94ADD6yc56gMerKv9JnIHWJNP5kL3kmfAD5HPjdFHtdyfsspr4u/1wvRY6HrOTBoPJBvwYM96wQEWtdYSOR5/CEYOsKYYNBIqpRm0CX7rCuO2zZvU3it3mai6w1i9ppfI7YysaoMvTG/9Ku7knFEUXPdCwAFG/zzawiM33qlzZ5jevaq+Y51eIfVHzJofU926U+S7+mxj0uEJ0yGz0F0r3+g28YSNZqnib5/jSAZ584WxAa5BhnovCk91+9AnnxxThz+pvRavrnBNrxximschaUSviUly8ImxF6GS53jXQc4wDao0Ny+0Q+/8V2fYa1DVh3Etyzjf5lnTYusvLgtb2MIW5h/7BTISCQWYITmqAAAAAElFTkSuQmCC",
        "providerReferenceNumber": "ab2e3aesf-eas2ty7rds-32ew"
    }
    

    Initiates an AliPay transaction.

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/wallets/alipay/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 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 for which the transaction will be initiated.
    orderId String Optional A client order id, will be used as reference to the payment.
    orderDescription String Required The description of order. This will be displayed to customer if paymentUrl is used by customer to make payment.
    paymentChannel String Required This parameter defines which channel is used to make the payment. Supported type are InBrowser, InApp, InstoreCustomerQRCode and InstoreMerchantQRCode. InBrowser is used if customer is initiating the transaction from browser. InApp is used if transaction is initiated from within AliPay mobile app. InstoreMerchantQRCode is used if transaction is initiated from merchant terminal. InstoreCustomerQRCode is used if transaction is initiated using customer's AliPay app QRCode.
    redirectUrls String Conditional Refer to Redirect URL for more details. This is required only if paymentChannel is of type InBrowser and InApp.
    deviceId String Conditional The device from which the request is made. This is required if paymentChannel is of type InstoreMerchantQRCodeand InstoreCustomerQRCode.
    qrCode String Conditional The payment QRCode scanned from customer's AliPay wallet. This is required if paymentChannel is of type InstoreCustomerQRCode.

    Redirect Urls

    Parameter Required Description
    successUrl Required The URL to which the client will be redirected to after successful AliPay payment. This is only applicable if product system is using paymentUrl (refer to response object) to display the QRCode.

    Response

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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.
    ip String Client IP address.
    amount Integer An integer value greater than 0, representing the total amount in cents.
    orderId String A client order id, will be used as reference to the payment.
    status String The status of the payment. Valid values are inprogress, paid, failed, cancelled, unknown. Refer to AliPay transaction status for details.
    paymentChannel String This parameter defines which channel is used to make the payment.
    paymentUrl String The URL issued by AliPay to initiate the transaction. URL will expire after 5 minutes if no action is performed on order. This field is returned for channelType: InBrowser, InApp and InstoreMerchantQRCode. If paymentChannel is of type InApp or InstoreMerchantQRCode the URL can only be opened from AliPay app only.
    qrCodeImage String QRCode image formatted in Base64. If product system don't want to redirect user to provider payment page, QRCode image can be displayed on product system payment page. This field is only returned if paymentChannel is of type InBrowser or InstoreMerchantQRCode.
    providerReferenceNumber String The reference number to the order, issued by provider.

    Retrieve AliPay Order details

    To retrieve AliPay order detail:

    GET https://payments-stest.npe.auspost.zone/v2/wallets/alipay/orders/{orderid}?merchantCode=YOUR_MERCHANT_CODE
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/alipay/orders/{orderId}?merchantCode=YOUR_MERCHANT_CODE -X GET 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "amount": 10000,
        "customerCode": "anonymous",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "providerReferenceNumber": "ab2e3aesf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Retrieve AliPay order details.

    HTTP Request

    GET https://payments-stest.npe.auspost.zone/v2/wallets/alipay/orders/{orderid}?merchantCode=YOUR_MERCHANT_CODE

    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.

    Query Parameters

    Parameter Required Description
    merchantCode Required Merchant account for which the funds are collected.

    Response

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    amount Integer An integer value greater than 0, representing the total amount in cents.
    customerCode String The identifier for the customer. In case of anonymous payment it is always anonymous.
    merchantCode String Merchant account for which the funds are collected.
    orderId String A client order id, will be used as reference to the payment.
    providerReferenceNumber String The reference number to the order, issued by provider.
    status String The status of the payment. Valid values are paid, failed, inprogress, cancelled, unknown. Refer to AliPay transaction status for details.

    Refund AliPay Payment

    To refund AliPay payment, use this code:

    POST https://payments-stest.npe.auspost.zone/v2/wallets/alipay/orders/{orderId}/refunds
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/alipay/orders/{orderId}/refunds -X POST 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ 
              "merchantCode": "YOUR_MERCHANT_CODE",  
              "amount": 10000, 
              "ip": "127.0.0.1"
            }'
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode" : "anonymous",
        "ip": "127.0.0.1",
        "amount": "10000",
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "providerReferenceNumber": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "status": "paid"
    }
    

    Used to refund a previous successful AliPay payment.

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/wallets/alipay/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 If you're collecting payments on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant.
    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 AliPay account 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 ISO Date Time with timezone offset of when the refund was made.
    merchantCode String If you're refunding payment on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant.
    customerCode String The identifier for the customer. In case of anonymous payment it is always anonymous.
    ip String Client IP address.
    amount String Total amount in cents that was refunded to customer AliPay account. The amount value cannot be greater than previously processed order amount.
    orderId String A client order id which is refunded.
    providerReferenceNumber String The reference number issued by provider for the refunded order.
    status String The status of the payment. Valid values are paid, failed, inprogress, cancelled, unknown. Refer to AliPay transaction status for details.

    AliPay transaction status

    Status Description
    paid The payment has been successful.
    failed The payment has been failed.
    inprogress The transaction is in pending state or it has not terminated, e.g. waiting on customer authorization.
    unknown The result of execution is not determined(e.g. due to connectivity issues). To verify the status in this case use retrieve AliPay get order details endpoint.
    cancelled The payment has been cancelled.

    Error Codes

    AliPay 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_ORDER_ID -- Order id has to be unique per merchant SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for AliPay payments 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
    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
    500 GATEWAY_ERROR -- Refund failure from Payment provider Provider No

    WeChat Payments (Beta)

    Overview

    WeChat Pay is a payment feature integrated into the WeChat mobile application, allowing users to complete payments quickly. There are different ways for customers to make payments. Each of the payment methods is explained below in details.

    How it works

    In store customer QR code

    1.1. Customer is logged into WeChat app and provides the QR code to merchant. Merchant scans this QR code and makes a call to your server to make an Initiate WeChat Txn.

    1.2. Your server then proxies the request to perform the Initiate WeChat Txn to SecurePay API.

    1.3. SecurePay API sends the request to WeChat to initiate transaction.

    2.1. Once the transaction is completed, WeChat/AliPay notifies customer and SecurePay API.

    2.2. Your server receives an WeChatPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In store merchant QR code

    1.1. Merchant makes a call to your server to make an Initiate WeChat Txn. Your server then proxies the request to perform Initiate WeChat Txn to SecurePay API .

    1.2. SecurePay API sends the request to WeChat to initiate transaction.

    2.1. WeChat sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate WeChat Response from SecurePay API which contains the QR Code.

    2.3. Merchant provides this QR code to the customer.

    3.1. Customer scans the QR code and makes a payment.

    4.1. Once the transaction is completed, WeChat notifies customer and SecurePay API.

    4.2. Your server receives an WeChatPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In Web Browser

    1.1. Customer initiates a purchase on a website. Your website makes a call to your server to make an Initiate WeChat Txn.

    1.2. Your server then proxies the request to perform the Initiate WeChat Txn to SecurePay API.

    1.3. SecurePay API sends the request to WeChat to initiate transaction.

    2.1. WeChat sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate WeChat Response from SecurePay API which contains QR code.

    3.1. Customer scans the QR code and makes a payment.

    4.1. Once the transaction is completed, WeChat notifies customer and SecurePay API.

    4.2. Your server receives an WeChatPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    In App

    1.1. Customer is logged into WeChat app and initiates the purchase. Customer app makes a call to your server to make an Initiate WeChat Txn.

    1.2. Your server then proxies the request to perform the Initiate WeChat Txn to SecurePay API.

    1.3. SecurePay API sends the request to WeChat to initiate transaction.

    2.1. WeChat sends the response to SecurePay API for initiated Txn.

    2.2. Your server receives the Initiate WeChat Response from SecurePay API which contains paymentUrl.

    2.3. Your server proxies paymentUrl to the customer.

    3.1. Customer is redirected to paymentUrl page and makes the payment.

    4.1. Once the transaction is completed, WeChat notifies customer and SecurePay API .

    4.2. Your server receives an WeChatPaymentProcessedEvent webhook notification from SecurePay API that contains the payment status.

    Rest API

    Initiate WeChat Transaction

    To initiate WeChat transaction:

    POST https://payments-stest.npe.auspost.zone/v2/wallets/wechat/payments/initiate
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/wechat/payments/initiate -X POST 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ 
                "merchantCode": "YOUR_MERCHANT_CODE", 
                "ip": "127.0.0.1",
                "amount": 10000, 
                "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
                "orderDescription": "text shown to buyer",
                "paymentChannel": "InBrowser",
                "redirectUrls": {
                    "successUrl": "http://<success url>",
                }
            }'
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "ip": "127.0.0.1",
        "amount": 10000,
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "status": "inprogress",    
        "paymentChannel": "InBrowser",
        "providerReferenceNumber": "ab2e3aesf-eas2ty7rds-32ew",
        "paymentUrl": "https://mpay.royalpay.com.au/api/v1.0/gateway/partners/PINE/orders/5742521-11bf-4cbb-983a-dcbc8193480/pay?time=1536211158022&nonce_str=nonce&sign=68685f6bfe62&redirect=http://<success url>",
        "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAACHElEQVR42u2aS47DIBBEYeVjcFMb35QjzNIrmK4qSDR2Is2WFpYVOfbLwk3R34T2n+MnLGxhC1vYwjxgNeA4eGGfp51Xaq3g7uYLw3XZt0LGPssOAF+rN6yMmyUaRmtEwrtHzG7GK2U8MjIcfjGzA9cdCj+pBI8YRR64hfXUjNO+7IWpMTouWODv+dG/TY3146K8h2c+v8WsmbFKhxxCqgHbWb4rh0S1u8LMFJFhKF4Mu/gKzfPCFYY9e0nnLUPeuJnpqO+Oa3KsIc52gGZJir8mhr9LPz1mBjkZZ03bVR6M6/4MRrNjTZtXGSNzDNqExmneMAVcMMoe6cqw+ps3zF6fwla9gxVH+cP7nrAa3ulilrDNRM+94ADD6yc56gMerKv9JnIHWJNP5kL3kmfAD5HPjdFHtdyfsspr4u/1wvRY6HrOTBoPJBvwYM96wQEWtdYSOR5/CEYOsKYYNBIqpRm0CX7rCuO2zZvU3it3mai6w1i9ppfI7YysaoMvTG/9Ku7knFEUXPdCwAFG/zzawiM33qlzZ5jevaq+Y51eIfVHzJofU926U+S7+mxj0uEJ0yGz0F0r3+g28YSNZqnib5/jSAZ584WxAa5BhnovCk91+9AnnxxThz+pvRavrnBNrxximschaUSviUly8ImxF6GS53jXQc4wDao0Ny+0Q+/8V2fYa1DVh3Etyzjf5lnTYusvLgtb2MIW5h/7BTISCQWYITmqAAAAAElFTkSuQmCC"
    }
    

    Initiates an WeChat transaction.

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/wallets/wechat/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 Type Required Description
    merchantCode String Required Merchant code uniquely identifies the customer. Merchant account on behalf of which the txn will be initiated.
    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 for which the transaction will be initiated.
    orderId String Optional A client order id, will be used as reference to the payment.
    orderDescription String Required The description of order. This will be displayed to customer if paymentUrl is used by customer to make payment.
    paymentChannel String Required This parameter defines which channel is used to make the payment. Supported type are InBrowser, InApp, InstoreCustomerQRCode and InstoreMerchantQRCode. InBrowser is used if customer is initiating the transaction from browser. InApp is used if transaction is initiated from within WeChat mobile app. InstoreMerchantQRCode is used if transaction is initiated from merchant terminal. InstoreCustomerQRCode is used if transaction is initiated using customer's WeChat app QRCode.
    redirectUrls String Conditional Refer to Redirect URL for more details. This is required only if paymentChannel is of type InBrowser and InApp.
    deviceId String Conditional The device from which the request is made. This is required if paymentChannel is of type InstoreMerchantQRCodeand InstoreCustomerQRCode.
    qrCode String Conditional The payment QRCode scanned from customer's WeChat wallet. This is required if paymentChannel is of type InstoreCustomerQRCode.

    Redirect Urls

    Parameter Required Description
    successUrl Required The URL to which the client will be redirected to after successful WeChat payment. This is only applicable if product system is using paymentUrl (refer to response object) to display the QRCode.

    Response

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    merchantCode String Merchant account for which the funds are collected.
    ip String Client IP address.
    customerCode String The identifier for the customer. In case of anonymous payment it is always anonymous.
    amount Integer An integer value greater than 0, representing the total amount in cents.
    orderId String A client order id, will be used as reference to the payment.
    status String The status of the payment. Valid values are paid, failed, inprogress, cancelled, unknown. Refer to WeChat transaction status for details.
    paymentChannel String This parameter defines which channel is used to make the payment.
    providerReferenceNumber String The reference number to the order, issued by provider.
    paymentUrl String The URL issued by WeChat to initiate the transaction. URL will expire after 5 minutes if no action is performed on order. This field is returned for channelType: InBrowser, InApp and InstoreMerchantQRCode. If paymentChannel is of type InApp or InstoreMerchantQRCode the URL can only be opened from WeChat app only.
    qrCodeImage String QRCode image formatted in Base64. If product system don't want to redirect user to provider payment page, QRCode image can be displayed on product system payment page. This field is only returned if paymentChannel is of type InBrowser or InstoreMerchantQRCode.

    Retrieve WeChat Order details

    To retrieve WeChat order detail:

    GET https://payments-stest.npe.auspost.zone/v2/wallets/wechat/orders/{orderid}?merchantCode=YOUR_MERCHANT_CODE
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/wechat/orders/{orderId}?merchantCode=YOUR_MERCHANT_CODE -X GET 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "amount": 10000,
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "providerReferenceNumber": "ab2e3aesf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Retrieve WeChat order details.

    HTTP Request

    GET https://payments-stest.npe.auspost.zone/v2/wallets/wechat/orders/{orderId}?merchantCode=YOUR_MERCHANT_CODE

    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.

    Query Parameters

    Parameter Required Description
    merchantCode Required Merchant account for which the funds are collected.

    Response

    Name Type Description
    createdAt String A timestamp when transaction was created, in ISO Date Time format with timezone offset e.g. 2019-04-14T01:26:00.856Z.
    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 Integer An integer value greater than 0, representing the total amount in cents.
    orderId String A client order id, will be used as reference to the payment.
    providerReferenceNumber String The reference number to the order, issued by provider.
    status String The status of the payment. Valid values are paid, failed, inprogress, cancelled, unknown. Refer to WeChat transaction status for details.

    Refund WeChat Payment

    To refund WeChat payment, use this code:

    POST https://payments-stest.npe.auspost.zone/v2/wallets/wechat/orders/{orderId}/refunds
    
    curl https://payments-stest.npe.auspost.zone/v2/wallets/wechat/orders/{orderId}/refunds -X POST 
        -H "Content-Type: application/json"
        -H "Authorization: Bearer xxxxxxxx"
        -d '{ 
              "merchantCode": "YOUR_MERCHANT_CODE",  
              "amount": 10000, 
              "ip": "127.0.0.1"
            }'
    
    {
        "createdAt": "2017-04-14 T01:26:00Z",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode" : "anonymous",
        "ip": "127.0.0.1",
        "amount": "10000",
        "orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
        "providerReferenceNumber": "de305d54-75b4-431b-adb2-eb6b9e546014",
        "status": "paid"
    }
    

    Used to refund a previous successful WeChat payment.

    HTTP Request

    POST https://payments-stest.npe.auspost.zone/v2/wallets/wechat/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
    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 WeChat account 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.
    merchantCode String Required If you're collecting payments on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant.

    Response

    Name Type Description
    createdAt String ISO Date Time with timezone offset of when the refund was made.
    merchantCode String If you're refunding payment on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant.
    customerCode String The identifier for the customer. In case of anonymous payment it is always anonymous.
    ip String Client IP address.
    amount String Total amount in cents that was refunded to customer WeChat account. The amount value cannot be greater than previously processed order amount.
    orderId String A client order id which is refunded.
    providerReferenceNumber String The reference number issued by provider for the refunded order.
    status String The status of the payment. Valid values are paid, failed, inprogress, cancelled, unknown. Refer to WeChat transaction status for details.

    WeChat transaction status

    Status Description
    paid The payment has been successful.
    failed The payment has been failed.
    inprogress The transaction is in pending state or it has not terminated, e.g. waiting on customer authorization.
    unknown The result of execution is not determined(e.g. due to connectivity issues). To verify the status in this case use retrieve WeChat get order details endpoint.
    cancelled The payment has been cancelled.

    Error Codes

    WeChat 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_ORDER_ID -- Order id has to be unique per merchant SecurePay API Yes
    400 INVALID_ACCOUNT -- Account has not been configured for WeChat payments 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
    401 UNAUTHORIZED -- Provided invalid 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
    500 GATEWAY_ERROR -- Refund failure from Payment provider Provider No

    Fraud detection (Beta)

    Overview

    Fraud detection is a tool for merchants to protect from malicious transactions.

    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 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 a fraud detection for a given order 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.

    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.

    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 values are PAYMENT_CARD and PAYPAL.
    token String Optional A tokenised payment instrument reference. Required if payment method is set to PAYMENT_CARD. 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

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

    Webhooks

    SecurePay API merchant can be registered to receive notifications of some events that occur within SecurePay API. These notifications are delivered as a standard webhook callback.

    Callback URL

    This can be any user defined url, for example:

    https://auspost.com.au/shop/events

    The following are the requirement for this endpoint:

    // Example webhook skeleton using Java
    public class EventHandler {
    
        private static final LoggerFactory LOG = LoggerFactory.getLogger(EventHandler.class);
    
        public Response handleEvent(String httpPostBody) {
            SomeObject event = // Uue jackson to deserialize http post body
    
            switch(event.type) {
                case "WeChatPaymentProcessedEvent" :
                    // TODO: asynchronously handle 'WeChatPaymentProcessedEvent'
                    break;
                default:
                    LOG.info("unknown event type {}", event);
                    break;
            }
    
            return ResponseBuilder.status(200).build();
        }
    }
    

    Implementation recommendations

    Supported events

    Currently SecurePay API can send any of the following events to your webhook. More events may be added in future; all webhook implementations are required to successfully acknowledge them.

    Event Description
    AliPayPaymentProcessedEvent Sent when an AliPay payment is finalised.
    AliPayRefundProcessedEvent Sent when an AliPay refund is finalised.
    WeChatPaymentProcessedEvent Sent when an WeChat payment is finalised.
    WeChatRefundProcessedEvent Sent when an WeChat refund is finalised.

    AliPayPaymentProcessedEvent

    Example AliPayPaymentProcessedEvent event:

    {
        "createdAt": "2017-10-25T04:35:51Z",
        "type": "AliPayPaymentProcessedEvent", 
        "version": 1,
        "organisationCode": "YOUR_ORGANISATION_CODE",
        "accountCode": "YOUR_ACCOUNT_CODE",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "orderId": "9eebc049-9fc3-467d-b737-d60f8b67026d",
        "amount": "500000",
        "paymentChannel": "InBrowser",
        "providerReferenceNumber": "ab2e3ae-sf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Sent when an AliPay payment is finalised.

    Name Description
    createdAt ISO Date Time with timezone offset of when the event was created.
    type This event will be set to 'AliPayPaymentProcessedEvent'.
    version Currently only version '1'.
    organisationCode The organisation code.
    accountCode The account code.
    merchantCode The merchant code.
    customerCode The identifier for the customer. In case of anonymous payment it is always anonymous.
    amount An integer value greater than 0, representing the total amount in cents.
    orderId A system (SecurePay API) defined, unique orderId that was used to perform the payment instruction.
    paymentChannel This parameter defines which channel is used to make the payment. Supported type are InBrowser and InApp.
    providerReferenceNumber The reference number to the order, issued by provider.
    status The status of the payment. Valid values are paid, failed, cancelled, unknown.

    AliPayRefundProcessedEvent

    Example AliPayRefundProcessedEvent event:

    {
        "createdAt": "2017-10-25T04:35:51Z",
        "type": "AliPayRefundProcessedEvent", 
        "version": 1,
        "organisationCode": "YOUR_ORGANISATION_CODE",
        "accountCode": "YOUR_ACCOUNT_CODE",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "amount": "500000",
        "orderId": "9eebc049-9fc3-467d-b737-d60f8b67026d",
        "providerReferenceNumber": "ab2e3ae-sf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Sent when an AliPay refund is finalised.

    Name Description
    createdAt ISO Date Time with timezone offset of when the event was created.
    type This event will be set to 'AliPayRefundProcessedEvent'.
    version Currently only version '1'.
    organisationCode The organisation code.
    accountCode The account code.
    merchantCode The merchant code.
    customerCode The identifier for the customer. In case of anonymous payment it is always anonymous.
    amount An integer value greater than 0, representing the total amount in cents.
    orderId A system (SecurePay API) defined, unique orderId that was used to perform the payment instruction.
    providerReferenceNumber The reference number to the order, issued by provider.
    status The status of the payment. Valid values are paid, failed, cancelled, unknown.

    WeChatPaymentProcessedEvent

    Example WeChatPaymentProcessedEvent event:

    {
        "createdAt": "2017-10-25T04:35:51Z",
        "type": "WeChatPaymentProcessedEvent", 
        "version": 1,
        "organisationCode": "YOUR_ORGANISATION_CODE",
        "accountCode": "YOUR_ACCOUNT_CODE",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "amount": "500000",
        "orderId": "9eebc049-9fc3-467d-b737-d60f8b67026d",
        "paymentChannel": "InBrowser",
        "providerReferenceNumber": "ab2e3ae-sf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Sent when a WeChat payment is finalised.

    Name Description
    createdAt ISO Date Time with timezone offset of when the event was created.
    type This event will be set to 'WeChatPaymentProcessedEvent'.
    version Currently only version '1'.
    organisationCode The organisation code.
    accountCode The account code.
    merchantCode The merchant code.
    customerCode The identifier for the customer. In case of anonymous payment it is always anonymous.
    amount An integer value greater than 0, representing the total amount in cents.
    orderId A system (SecurePay API) defined, unique orderId that was used to perform the payment instruction.
    paymentChannel This parameter defines which channel is used to make the payment. Supported type are InBrowser, InApp, InstoreCustomerQRCode and InstoreMerchantQRCode.
    providerReferenceNumber The reference number to the order, issued by provider.
    status The status of the payment. Valid values are paid, failed, cancelled, unknown.

    WeChatRefundProcessedEvent

    Example WeChatRefundProcessedEvent event:

    {
        "createdAt": "2017-10-25T04:35:51Z",
        "type": "WeChatRefundProcessedEvent", 
        "version": 1,
        "organisationCode": "YOUR_ORGANISATION_CODE",
        "accountCode": "YOUR_ACCOUNT_CODE",
        "merchantCode": "YOUR_MERCHANT_CODE",
        "customerCode": "anonymous",
        "amount": "500000",
        "orderId": "9eebc049-9fc3-467d-b737-d60f8b67026d",
        "providerReferenceNumber": "ab2e3ae-sf-eas2ty7rds-32ew",
        "status": "paid"
    }
    

    Sent when a WeChat refund is finalised.

    Name Description
    createdAt ISO Date Time with timezone offset of when the event was created.
    type This event will be set to 'WeChatRefundProcessedEvent'.
    version Currently only version '1'.
    organisationCode The organisation code.
    accountCode The account code.
    merchantCode The merchant code.
    customerCode The identifier for the customer. In case of anonymous payment it is always anonymous.
    amount An integer value greater than 0, representing the total amount in cents.
    orderId A system (SecurePay API) defined, unique orderId that was used to perform the payment instruction.
    providerReferenceNumber The reference number to the order, issued by provider.
    status The status of the payment. Valid values are paid, failed, cancelled, unknown.

    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

    Shopping cart integration

    Overview

    SecurePay offer a smooth integration with the most popular shopping carts and we maintain the latest selection. Find out more here.

    Support

    Contact Us

    Our support email address is [coming soon]

    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.