Integrating with SecurePay
Getting started with SecurePay is quick and easy, and there are multiple ways you can integrate based on your needs. You also have the chance to test your integration after signing up for an account. SecurePay provides you with a sandbox version, allowing you to freely test SecurePay on your website for as long as you’d like before starting with a live account.
The methods in which you can integrate with SecurePay include SecurePay API, e-Commerce extensions and other methods such as XML, SecureFrame, SecureBill and more.
To find out more on each of the integration methods available, click on the links below.
SecurePay API
The SecurePay API allows you to take payments on your web site in a PCI DSS compliant manner whilst retaining a much greater degree of control over the look & feel than is possible with other payment integrations.
Getting started
Obtaining a SecurePay test account
To obtain your test credentials, you must first create an account with SecurePay. If you’d like to do this now, follow this link to the SecurePay home page and sign up for free.
After entering your details, you’ll be given a clientId
, a clientSecret
and a merchantCode
.
These are your test credentials, which you can use to explore SecurePay API’s functionality and integration for free before you start trading.
Giving SecurePay API a test run
Along with your clientId
and your clientSecret
, you will also have been issued a merchantCode
, which you will need to access the sandbox environment where SecurePay can be tested.
To test the SecurePay API and get a feel for how everything works, simply have your credentials ready and access the sandbox environment .
Setting up your live account
Once you’re ready, you can return to your SecurePay account and apply for your merchant account/facility.
After approval, you’ll receive a welcome email providing access to your merchant portal.
After logging in, you’ll notice an activated status letting you know that you’re all set up and ready to integrate our API onto your live site!
You will also find your live clientSecret
.
SecurePay will use this to confirm data exchanges (sensitive information) with you as a merchant, so keep it safe and secure!
Environment details
To consume SecurePay API you will need an accessToken
to authenticate, refer to the authentication section for more information.
Environment | Base URL |
---|---|
Sandbox | https://payments-stest.npe.auspost.zone |
Live | https://payments.auspost.net.au |
Authentication
Overview
SecurePay API uses the OAuth 2.0 protocol for authentication and authorization.
Your client application requests an access token from the Authorization Server
, and sends the token as part of the Authorization Header
to the SecurePay API resource that you want to access.
OAuth 2.0 is used by the world’s largest digital organisations, and it is currently the most secure and technologically advanced protocol of its kind. It uses fast-expiring access tokens that can only be utilised for specific resources by applications. This greatly mitigates the risk of “man-in-the-middle” attack and data breaching.
Client Credentials
Example code to obtain an access token:
curl -X POST \
https://welcome.api2.sandbox.auspost.com.au/oauth/token \
--header 'Authorization: Basic xxxxxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.payments.auspost.com.au'
{
"access_token": "eyJraWQiOiJJTzdwOUxNcEd0NBlLLV80Q192SFUyaUFvcGJoMXNZQ0JCOTV5cEthVzBJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkFSdUVqbmdlcmJFWHZ1M1ZEMGMzZjNjWDM3OWJzZzhzeElmTmZXNUttSGsiLCJpc3MiOiJodHRwczovL2Rldi00MjQ4ODMub2t0YS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNTYwNDAyMjQ0LCJleHAiOjE1NjA0ODg2NDQsImNpZCI6IjBvYW9rYXp4eTB2OEs5UGRVMzU2Iiwic2NwIjpbImh0dHBzOi8vYXBpLnBheW1lbnRzLmF1c3Bvc3QuY29tLmF1L3BheWhpdmUvbWFuYWdlLWFjY291bnRzL3JlYWQiLCJodHRwczovL2FwaS5wYXltZW50cy5hdXNwb3N0LmNvbS5hdS9wYXloaXZlL21hbmFnZS1hY2NvdW50cy93cml0ZSJdLCJzdWIiOiIwb2Fva2F6eHkwdjhLOVBkVTM1NiJ9.Zsv-NGEIUOOucmFl4_a2-E_Kd9GrlRuWvzwwYoU2s8C84PE1dFUzAIoXAs29jPYL3Ceu4t_TtKbm92VG_Oyd85-_pk7nYIli-1SxNSHwIcF8bNMV-mNngXEhjLA_Qm6eT-Ydj6k8Ww47XiDa8fYz48FMmi6f4zU44sEPL3wbNsPTIYEcQxzyO8gPpiKHn-74Gc7XVmFRAKngHr-3WrySevS8CzTlxdk3YJG60LHaivsXoAQ0vaREe4SaTwjlIaxLqfqVihG0B4o4dOlI9pT8gfhTfyb2QnTcyD16uQlUJuXGzlTZmg57mTwNeKmyFAAsOqKTITie-arizOIAtXqb2Q",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "https://api.payments.auspost.com.au/payhive/payments/read https://api.payments.auspost.com.au/payhive/payments/write https://api.payments.auspost.com.au/payhive/payment-instruments/read https://api.payments.auspost.com.au/payhive/payment-instruments/write"
}
Authentication URL
Environment | URL |
---|---|
Sandbox | https://welcome.api2.sandbox.auspost.com.au/oauth/token |
Live | https://welcome.api2.auspost.com.au/oauth/token |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
HTTP Basic Auth header containing your client id and client secret (issued during the on-boarding process). Refer to HTTP Basic Auth for more information. |
Content-Type | Required |
Should be set to application/x-www-form-urlencoded . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
grant_type | String | Required |
The grant_type parameter must be set to client_credentials . |
audience | String | Required |
The audience parameter must be set to https://api.payments.auspost.com.au . |
Response
Name | Type | Description |
---|---|---|
access_token | String | The access token string as issued by the server. Access_token issued will have permission to invoke all SecurePay API operations. |
token_type | String | Type of token - bearer |
expires_in | Integer | The duration of time in seconds the access token is granted for. |
scope | String | The scopes assigned to the client |
Card Payments
Overview
SecurePay API lives on your website as a customisable User Interface (UI) Component that securely captures customer card details so that payments can be made safely.
Unlike other payment services which will take customers off your website entirely, SecurePay provides a "UI Component" which is embedded on your web page. While we do use a iframe to achieve this, our functionality is entirely customisable. The website owner still retains absolute control over the look and feel of the page.
This means that you can customise your payments page exactly how you wish, maintaining total control of your customer experience while leaving the card security (PCI-DSS) and complexity to us.
UI Component:
Your PCI footprint
Any business that deals with card information is subject to compliance obligations in order to maintain security to a universal standard. This universal standard is referred to as being PCI-DSS compliant.
If your website hosts payment fields, you are within PCI scope. This has several implications for your business, but in summary, it means that you must continuously prove yourself PCI-DSS compliant and live up to a very high security standard.
However, by using the SecurePay integration method, you can minimize your PCI scope significantly. This is because customer card details never actually touch your system, absolving you of any security obligations that you would otherwise be subject to.
This integration method keeps your data secure, reducing your PCI scope without sacrificing the customer end-to-end experience.
Customer payment card data will be handled with consideration to the PCI DSS requirements applicable to SecurePay API as a service provider.
Adding the UI Component
<!-- Include the SecurePay UI Component. -->
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
<!-- Configure the UI component. -->
<script type="text/javascript">
var mySecurePayUI = new securePayUI.init({
containerId: 'securepay-ui-container',
scriptId: 'securepay-ui-js',
clientId: 'YOUR_CLIENT_ID',
merchantCode: 'YOUR_MERCHANT_CODE',
card: { // card specific config options / callbacks
onTokeniseSuccess: function(tokenisedCard) {
// card was successfully tokenised
// here you could make a payment using the SecurePay API (via your application server)
},
onTokeniseError: function(errors) {
// error while tokenising card
}
}
});
</script>
To add the SecurePay UI Component, include the JavaScript client library and configure the component as shown in the example code.
The UI component will render a card capture form, which you can use capture the data from your users in a PCI DSS compliant way.
How it works
(1) The SecurePay UI Component should be initialised on the merchant website within the customer browser. See Javscript SDK - Configuration Object for more information on configuration options.
(2) Once the user has entered their card details, the UI Component's tokenise method
needs to be called by the merchant website.
In ddc
mode tokenise method
should be called after onDCCQuoteSuccess
was invoked and customer selected a payment option.
(3) Card information will be tokenised by the SecurePay API.
(4) Tokenised card response is returned to the SecurePay UI Component.
(5) On successful tokenisation, the onTokeniseSuccess
will be invoked which includes a token
.
Please note that the card token generated is temporary and expires after 30 minutes. This token is a once-off usage token for one successful payment. To make token reusable, please use the Store Payment Instrument endpoint.
(6) (Optional) To utilise 3DS2, upon successful tokenisation, SecurePay's 3DS2 Javascript should be loaded and initialised and callbacks are configured. See 3DS2 Javascript - SDK
(7) (Optional) Trigger the 3DS2 Authentication process
(8) (Optional) Handle the authentication response.
(9) Merchant server should make use of the token
to make a payment
to SecurePay API. You must make this payment request from your server. (Optional) For payment authenticated with 3DS2, pass the Order Id initiated in Step 6.
Send the following HTTP request to SecurePay API to make an anonymous payment:
POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST
-H "Content-Type: application/json"
-H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "merchantCode": "YOUR_MERCHANT_CODE",
"amount": 10000,
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1"
}'
A successful payment will receive a response similar to the following:
HTTP/1.1 201 Created
CORRELATION-ID: efa12a94-7dd6-4078-a033-7b47aa7dc616
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"amount": 1000,
"status": "paid",
"bankTransactionId": "7002157044",
"customerCode": "anonymous",
"merchantCode": "AAA000DM000",
"ip": "127.0.0.1",
"token": "994634932354242",
"orderId": "efa12a94-7dd6-4078-a033-7b47aa7dc616"
}
(10) SecurePay API will process the anonymous payment and return a payment response
(11) Merchant server should proxy the payment response back to the merchant website so that an appropriate response can be returned to the customer browser.
JavaScript SDK
Environment Details
Environment | SecurePay UI JavaScript SDK URL |
---|---|
Sandbox | https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js |
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:
- include the JavaScript client library
- add a container element for the UI Component
- configure the UI Component
The securepay-ui.min.js
client library should be included in your HTML source as shown in the sample code:
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
The script adds a securePayUI
object to the global scope.
The SecurePayUI
object has a single public function init
which requires a UI Config object as its only argument:
var mySecurePayUI = new securePayUI.init({ ... });
This is where you pass your clientId
and other configuration information.
See UI Config Object for more information.
The SecurePay UI Component is inserted into the containerId
DOM element when configured correctly.
An error message will be shown in the browser console if the configuration object is invalid.
Public Methods
<button onclick="mySecurePayUI.tokenise();">Submit</button>
<button onclick="mySecurePayUI.reset();">Reset</button>
Two functions are available on the CardPayment
object after the UI Component has been created:
- securePayUI.tokenise()
- securePayUI.reset()
These commands are sent to the UI Component using the HTML5 window.postMessage API.
mySecurePayUI.tokenise()
will the following action:
- tokenise a new card
mySecurePayUI.reset()
will clear the card form fields in Checkout and Add Card view modes.
UI Config Object
<!doctype html>
<html>
<body>
<form onsubmit="return false;">
<div id="securepay-ui-container"></div>
<button onclick="mySecurePayUI.tokenise();">Submit</button>
<button onclick="mySecurePayUI.reset();">Reset</button>
</form>
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
<script type="text/javascript">
var mySecurePayUI = new securePayUI.init({
containerId: 'securepay-ui-container',
scriptId: 'securepay-ui-js',
clientId: 'YOUR_CLIENT_ID',
merchantCode: 'YOUR_MERCHANT_CODE',
card: {
allowedCardTypes: ['visa', 'mastercard'],
showCardIcons: false,
onCardTypeChange: function(cardType) {
// card type has changed
},
onBINChange: function(cardBIN) {
// card BIN has changed
},
onFormValidityChange: function(valid) {
// form validity has changed
},
onTokeniseSuccess: function(tokenisedCard) {
// card was successfully tokenised or saved card was successfully retrieved
},
onTokeniseError: function(errors) {
// tokenization failed
}
},
style: {
backgroundColor: 'rgba(135, 206, 250, 0.1)',
label: {
font: {
family: 'Arial, Helvetica, sans-serif',
size: '1.1rem',
color: 'darkblue'
}
},
input: {
font: {
family: 'Arial, Helvetica, sans-serif',
size: '1.1rem',
color: 'darkblue'
}
}
},
onLoadComplete: function () {
// the UI Component has successfully loaded and is ready to be interacted with
}
});
</script>
</body>
</html>
Option | Type | Required | Description |
---|---|---|---|
containerId | string | Yes | The HTML element id where the UI Component is to be inserted |
mode | string | No | Supported modes are checkout and dcc . Default mode is the checkout mode, it allows payment in AUD currency.dcc mode provides customers with an option to pay in a currency of the card used for payment. Read more in about dcc mode in Dynamic Currency Conversion section. |
scriptId | string | Yes | The HTML <script> element id which references securepay-ui.min.js |
clientId | string | Yes | Your client id |
merchantCode | string | Required if you have multiple merchant codes associated with your account | |
card | card-object | Yes | Specify card specific configuration options and callbacks |
style | style-object | Override default styles (background-color, font-size, font-weight, color) | |
checkoutInfo | checkout-info-object | Conditional | Should be present for in dcc mode. |
Card Object
Option | Type | Required | Description |
---|---|---|---|
allowedCardTypes | string[] | Specify which card types are allowed e.g. [visa , mastercard , amex , diners ] |
|
showCardIcons | boolean | Whether card type icons should be shown (false by default) |
Style Object
Option | Type | Required | Description |
---|---|---|---|
backgroundColor | string | Configure the backgroundColor of the UI component. Eg: white #FFFFFF |
|
label | style-element-object | Configure the fontFamily fontSize color of the label form fields. |
|
input | style-element-object | Configure the fontFamily fontSize color of the input form fields. |
Style Element Object
Option | Type | Required | Description |
---|---|---|---|
font | font-object | Configure the styling for the font object of the element. |
Font Object
Option | Type | Required | Description |
---|---|---|---|
family | string | Configure the font-family of the font for the element. Eg: "Times New Roman", Times, serif |
|
size | string | Configure the font-size of the font for the element. Eg: 1.25em 12px 10pt |
|
color | string | Configure the color of the font for the element. Eg: white #FFFFFF |
Checkout Info Object
Option | Type | Required | Description |
---|---|---|---|
orderToken | string | Conditional | Should be present for in dcc mode. A JWT token from Order Details. |
Dynamic Currency Conversion
Example of UI Component configured for dcc mode
<!doctype html>
<html>
<body>
<form onsubmit="return false;">
<div id="securepay-ui-container"></div>
<button onclick="mySecurePayUI.tokenise();">Submit</button>
<button onclick="mySecurePayUI.reset();">Reset</button>
</form>
<script id="securepay-ui-js" src="https://payments-stest.npe.auspost.zone/v3/ui/client/securepay-ui.min.js"></script>
<script type="text/javascript">
var mySecurePayUI = new securePayUI.init({
containerId: 'securepay-ui-container',
scriptId: 'securepay-ui-js',
mode: 'dcc',
checkoutInfo: {
orderToken: 'YOUR_JWT_TOKEN_FOR_THIS_ORDER'
},
clientId: 'YOUR_CLIENT_ID',
merchantCode: 'YOUR_MERCHANT_CODE',
card: {
allowedCardTypes: ['visa', 'mastercard'],
showCardIcons: false,
onCardTypeChange: function(cardType) {
// card type has changed
},
onBINChange: function(cardBIN) {
// card BIN has changed
},
onFormValidityChange: function(valid) {
// form validity has changed
},
onDCCQuoteSuccess: function(quote) {
// dynamic currency conversion quote was retrieved
},
onDCCQuoteError: function(errors) {
// quote retrieval failed
},
onTokeniseSuccess: function(tokenisedCard) {
// card was successfully tokenised or saved card was successfully retrieved
},
onTokeniseError: function(errors) {
// tokenization failed
}
},
style: {
backgroundColor: 'rgba(135, 206, 250, 0.1)',
label: {
font: {
family: 'Arial, Helvetica, sans-serif',
size: '1.1rem',
color: 'darkblue'
}
},
input: {
font: {
family: 'Arial, Helvetica, sans-serif',
size: '1.1rem',
color: 'darkblue'
}
}
},
onLoadComplete: function () {
// the UI Component has successfully loaded and is ready to be interacted with
}
});
</script>
</body>
</html>
Dynamic Currency Conversion (DCC) is a process in which your customers can make payments on their credit card in the card’s billing currency.
When your customers choose to pay in their own currency For security reasons, do not retrieve a new “access_token”, they lock in the exchange rate at the time of transaction and it remains the same for the lifecycle of the payment.
Supported currencies are: USD, EUR, NZD, GBP, IDR, CRC, COP, BRL, JMD, ZAR, PHP, ARS, INR, AED, CLP, TTD, UYU, MXN, GYD, HKD, GTQ, JPY, SGD, CHF, NOK, MYR, BBD, TZS, QAR, CAD.
Supported card types are: Visa and Mastercard.
Once your customer enters ten digits of their card number, the dynamic currency conversion quote will be retrieved by the SecurePay UI Component. If a quote is available for the card currency, exchange rate details are displayed to the customer. Customer can choose whether to pay in AUD or in the card currency.
The view of UI Component is slightly different depending on card type, see the examples below.
Example for Visa card
Example for Mastercard card
Prior to loading the UIComponent
, a payment order should be initiated by calling Initiate Payment Order from merchant server.
orderToken
should be passed from merchant server to merchant website and used to configure UI Config Object
.
With DCC tokenise method
should be called after onDCCQuoteSuccess
was invoked
and Tokenised Card Object will always contain DCC Quote Object.
If your customer chooses to pay in their card’s issued currency which is not AUD, then the converted object in DCC Quote Object will contain foreign currency and amount to charge the customer.
If customer chooses option to pay in AUD
, then base
field will be present. In this case merchant should charge customer with AUD
amount and currency.
DCC receipt format
(1) Must say "Original Transaction Amount" and amount must have AUD
prefix
(2) Must say "FX Rate 1 AUD" and show currency code and exchange rate that was returned in Tokenised Card Object in dccQuote.converted.currency
and dccQuote.converted.exchangeRate.value
fields respectively.
(3) Must say "Including X% margin", where X
is taken from dccQuote.converted.exchangeRate.value
field returned in Tokenised Card Object
(4) Must say "Final Transactional Amount". Must use foreign currency amount returned in amount
field of Payment Object.
Must prefix the amount with foreign currency code, eg. USD
taken from currency
field of Payment Object.
(5) Must say verbatim "This currency conversion has been provided by Merchant Name. I have been offered a choice of currencies for payment including AUD and agree to pay in USD", using foreign currency code for this transaction (eg. USD). It is advised to develop this text as a parameter so it can easily be changed in the future.
Callbacks
...
onTokeniseSuccess: function(tokenisedCard) {
console.log(tokenisedCard);
}
...
The UI Component sends messages to the client code when various events occur - such as a successful response being received
from a call to securePayUI.tokenise()
. These events can be handled by adding callback handler functions to the UI Config object.
The following callbacks are available:
Global SDK Callbacks
Option | Mode | Description |
---|---|---|
onLoadComplete() | checkout, dcc | Invoked when the UI Component has loaded |
onLoadError() - Deprecated | checkout, dcc | Invoked when the UI Component did not load successfully |
Card SDK Callbacks
Option | Mode | Description |
---|---|---|
onCardTypeChange(cardType) | checkout, dcc | Invoked when card type changes. Returns the card type ('visa', 'mastercard', 'amex' or 'diners' or 'unknown' if type cannot be determined). |
onCardBINChange(cardBIN) | checkout, dcc | Invoked when BIN changes. Returns the card BIN (Bank Identification Number). |
onFormValidityChange(valid) | checkout, dcc | Invoked when card form validity state changes. Returns a boolean flag indicating form validity. |
onDCCQuoteSuccess(dccQuoteDetails) | dcc | Could be invoked in dcc mode only. Invoked, when quote retrieval of dynamic currency conversion is successful. securePayUI.tokenise() should not be invoke prior receiving this callback, otherwise securePayUI.tokenise() call result in DCC_QUOTE_IN_PROGRESS error provided in onTokeniseError callback. |
onDCCQuoteError(error) | dcc | Could be invoked in dcc mode only. Invoked, when quote retrieval fails, for instance when orderToken is invalid. securePayUI.tokenise() method should not be invoked until UI component is reinitialised with valid configuration details. |
onTokeniseSuccess(tokenisedCard) | checkout, dcc | Invoked when card is successfully tokenised. Returns the Tokenised Card that was created. |
onTokeniseError(error) | checkout, dcc | Invoked when card tokenization failed |
Tokenised Card Object
Tokenise Card Object in checkout mode
{
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "520592516621111",
"createdAt": "2021-07-23T13:00:53.128+10:00",
"scheme": "visa",
"bin": "411111",
"last4": "111",
"expiryMonth": "10",
"expiryYear": "20"
}
Tokenise Card Object in dcc mode when customer chose to pay in card currency
{
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "520592516621111",
"createdAt": "2021-07-23T13:00:53.128+10:00",
"scheme": "visa",
"bin": "411111",
"last4": "111",
"expiryMonth": "10",
"expiryYear": "20",
"dccQuote": {
"converted": {
"currency": "USD",
"amount": "1285",
"exchangeRate": {
"value": "1.0946",
"markup": "3.50"
}
}
}
}
Tokenise Card Object in dcc mode when customer chose to pay in AUD
{
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "520592516621111",
"createdAt": "2021-07-23T13:00:53.128+10:00",
"scheme": "visa",
"bin": "411111",
"last4": "111",
"expiryMonth": "10",
"expiryYear": "20",
"dccQuote": {
"base": {
"currency": "AUD"
}
}
}
Name | Description |
---|---|
merchantCode | If you're collecting payments on behalf of other merchants (e.g. Post Bill Pay), this parameter allows you to uniquely identify the merchant. |
token | A tokenised payment instrument reference. Use this token in make payment call. Please note that the card token generated is temporary and expires after 30 minutes. This token is a once-off usage token for one successful payment. To make the token reusable, please use Store Payment Instrument endpoint. |
createdAt | A timestamp when card was tokenised, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
scheme | A card scheme, e.g. visa , mastercard , diners , amex . |
bin | Bank identification number. |
last4 | The last 3 digits of the card number. (Please note the number of digits returned may vary due to the card scheme) |
expiryMonth | Two digit number representing the card expiry month. |
expiryYear | Two digit number representing the card expiry year. |
dccQuote | Dynamic currency conversion quote, will be present in dcc mode only. |
DCC Quote Object
Returned in dccQuote
object in Tokenised Card Object
Name | Description |
---|---|
base.currency | Present if customer chose to pay in AUD or conversion rate was unavailable. Supported value: AUD . |
converted | Present if customer chose to pay in card currency which is not AUD, contains foreign currency and amount to charge the customer. Refer to Converted Object for field details. |
DCC Quote Details Object
Returned on successful quote retrieval in onDCCQuoteSuccess
callback
DCC quote details object
{
"base": {
"currency": "AUD"
},
"converted": {
"currency": "USD",
"amount": "1285",
"exchangeRate": {
"value": "1.0946",
"markup": "3.50"
}
}
}
Name | Description |
---|---|
base.currency | Contains the original currency for the order. Supported value: AUD . |
converted | If present contains details of dynamic currency conversion rate that will be presented to the customer. See Converted Object for details. |
Converted Object
Name | Description |
---|---|
currency | Populated with card currency. |
amount | Populated with converted amount in card currency in a lower denomination. |
exchangeRate | Populated with Exchange rate. |
Exchange rate object
Name | Description |
---|---|
value | Exchange rate that was retrieved for a card currency. |
markup | An agreed upon markup value added to the initial AUD amount before conversion, which is charged to the customer upon final payment. |
Error Object
{
"errors": [
{
"id": "1a909ec1-c96c-4ced-a471-d145a0e517ef",
"code": "MIN_CONSTRAINT_VIOLATION",
"detail": "must be greater than or equal to 1",
"source": {
"pointer": "amount"
}
}
]
}
Name | Required | Description |
---|---|---|
id | Yes |
Unique identifier for the error |
code | Yes |
Endpoint specific error code |
detail | Yes |
Detailed error description |
source.pointer | No |
If error is related to specific field in request this param will be populated with field name |
Rest API
To make a payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST
-H "Content-Type: application/json"
-H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "anonymous",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"amount": "10000",
"currency": "AUD",
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful"
}
Example of declined payment:
POST https://payments-stest.npe.auspost.zone/v2/payments
curl https://payments-stest.npe.auspost.zone/v2/payments -X POST
-H "Content-Type: application/json"
-H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10051,
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"amount": 10051,
"currency": "AUD",
"status": "failed",
"bankTransactionId": "824565",
"gatewayResponseCode": "51",
"gatewayResponseMessage": "Not sufficient funds",
"errorCode": "INSUFFICIENT_FUNDS",
"customerCode": "anonymous",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"token": "1117760467699043",
"orderId": "6f3e0642-187d-46b3-9f9f-1af3d8e344a0"
}
Create Payment
Make a payment for a given card token.
Token for anonymous payments expires after 30 minutes.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Idempotency-Key | Optional |
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key . |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, for AUD payments representing the total amount in cents to charge the provided (tokenised) payment instrument. For dynamic currency conversion payments this field should be set to the value of dccQuote.amount field provided in tokenise card object. |
currency | String | Optional |
Payment currency. Default value is AUD . Non AUD payments are supported for dynamic currency conversion payments only. For dynamic currency conversion payments this field should be set to the value of dccQuote.currency field provided in tokenise card object. |
orderId | String | Optional |
A client order id, will be used as reference to the payment. If not provided, SecurePay API will assign a unique id for the order. Note: < > " characters are not allowed in orderId. |
customerCode | String | Optional |
A unique (within your organisation) identifier of your customer. This is used when you want to perform a payment against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
fraudCheckDetails | String | Optional |
A payment fraud check details object. |
dccDetails | Object | Optional |
A dynamic currency conversion details object. Should be present for dynamic currency conversion payments. |
threedSecureDetails | Object | Optional |
A 3DS2 details Object. Required for payments authenticated with 3DS2. |
Response
The Payment that was successfully created.
Refund Payment
Used to refund a previous payment. Can only be used for AUD transactions.
For DCC transactions, only full refunds are supported and are only available via the SecurePay Merchant Portal.
To refund payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode" : "anonymous",
"amount": 10000,
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Approved"
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/orders/{orderId}/refunds
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Path Variables
Parameter | Description |
---|---|
orderId | A customer order id which was successfully processed previously and the merchant now wants to refund it. |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to refund. The amount will be refunded to the same payment instrument from which the payment was made for the order. The amount value to be refunded should be less then or equal to the actual paid amount. |
Response
The Refund that was successfully created.
Create Account Verification Transaction
An account verification is a $0 transaction used to verify the card details and its validity without impacting the customer’s available funds.
To process an Account Verification transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/account-verification
curl https://payments-stest.npe.auspost.zone/v2/payments/account-verification -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer XXXXXXXXXXXX"
-D'{ "merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"status": "success",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful"
}
This transaction type is supported by Visa and Mastercard only and available on selected acquiring banks (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA). Refer to SecurePay’s website FAQs for more information.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/account-verification
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the Account Verification transaction is processed against. |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
orderId | String | Optional |
A client order id, will be used as reference to the Account Verification. Note: < > " characters are not allowed in orderId. |
fraudCheckDetails | Object | Optional |
A account verification fraud check details object.. |
Response
The Account Verification that was successfully created.
Create PreAuth/InitialAuth Transaction
Used to pre-authorise a transaction against a token.
A pre-authorisation is used when wanting to reserve funds on a customer's credit card, which is generally held for five to ten business days. The time duration all depends on the cardholder's bank. During that time, you can “complete” the transaction to capture the funds.
To perform a standard pre-authorisation where you will only have the option of capturing the funds, is by passing PRE_AUTH in the preAuthType parameter field of the request.
For merchants that do not know the final amount when the transaction begins, they can process an initial authorisation transaction. An initial authorisation transaction is a flexible pre-authorisation that allows you to increase or decrease the actual amount when it’s known. You can process an initial authorisation transaction by passing INITIAL_AUTH in the preAuthType parameter field of the request. Please note initial authorisation is supported by Visa and Mastercard only, available on selected acquiring banks (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA) and can be used by merchants in certain industry categories. Refer SecurePay’s website FAQs for more information.
To process a pre-auth/initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"preAuthType": "INITIAL_AUTH",
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"amount": "10000",
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful"
}
To capture a standard pre-auth or initial-auth transaction please go to Capture PreAuth/InitialAuth Transaction.
If you would like to increase or cancel an approved initial-auth transaction, please go to Increase InitialAuth Transaction / Cancel InitialAuth Transaction
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
preAuthType | String | Optional |
This parameter defines which type of pre-authorisation is performed. Supported types are PRE_AUTH and INITIAL_AUTH . Default value is PRE_AUTH . |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. |
orderId | String | Optional |
A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
customerCode | String | Optional |
A unique (within your organisation) identifier of your customer. This is used when you want to perform a pre-auth payment against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
fraudCheckDetails | Object | Optional |
A preAuth fraud check details object. |
threedSecureDetails | Object | Optional |
A 3DS2 details Object. Required for payments authenticated with 3DS2. |
Response
The PreAuth Payment that was successfully created.
Increase InitialAuth Transaction
Used to increase an initial-auth transaction, using its order id.
Increment can't occur after a capture or a full cancellation has already been made.
To Increase an initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/increase
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/69d49ae5-a6f5-4627-8f7d-8f736011d028/increase -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"amount": 5000
}'
{
"createdAt": "2020-07-16T14:26:07.401+10:00",
"amount": 5000,
"status": "paid",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"orderId": "564966e8-2d7d-4bce-b0ed-33f26d751ba5"
}
Used to increase a pre-authorisation transaction of type INITIAL_AUTH
only.
NOTE:
- Preauth-Increments are only available on Visa or Mastercard and on selected (NAB, ANZ, Westpac Qvalent and Fiserv FDMSA) acquiring banks and can be used by merchants in certain industry categories. Refer to the SecurePay website FAQs for more information.
- For Visa transactions an
Increase InitialAuth Transaction
request will result in an amount increase only, it will not affect the validity period of the authorisation. The amount passed in anIncrease InitialAuth Transaction
request should be greater than zero for Visa transactions. - For Mastercard transactions an
Increase InitialAuth Transaction
request will result in an amount increase and extension of the validity period. To extend the validity period for Mastercard transactions only, you will have to pass a zero value in the amount field of the request.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/increase
Path Variables
Parameter | Description |
---|---|
orderId | The order id used for pre-auth payment. |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
amount | Integer | Required |
An integer value greater than or equal to 0, representing the increase amount. Refer to note section for more details. |
Response
The Increase PreAuth Payment Object that was successfully increased.
Cancel InitialAuth Transaction
Used to cancel an initial-authorisation transaction using its order id.
Cancellation is always for the full or partial amount. Also cancellation can't occur after a capture or a full amount has already been cancelled.
To cancel an initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/cancel
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/69d49ae5-a6f5-4627-8f7d-8f736011d028/cancel -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"amount": 5000
}'
{
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"orderId": "d2b65e49-e163-43ca-bd72-78dafsfe79-78g1d4c23",
"amount": 5000,
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful"
}
Used to cancel pre-authorisation payment of type INITIAL_AUTH
only.
NOTE:
Preauth-Cancellations are only available on Visa or Mastercard and on selected (NAB, ANZ*, Westpac Qvalent and Fiserv FDMSA) acquiring banks and can be used by merchants in certain industry categories. Refer to the SecurePay website FAQs for more information.
* The ANZ acquirer doesn’t currently support partial cancellations, only full cancellations can be made.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/cancel
Path Variables
Parameter | Description |
---|---|
orderId | The order id used for pre-auth payment. |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
amount | Integer | Optional |
An integer value greater than 0, representing an amount in cents to cancel. If the amount field is not present, the full amount that is left of the initial-authorisation will be cancelled. Refer to note section for more details. |
Response
The Cancel InitialAuth Payment Object that was successfully cancelled.
Capture PreAuth/InitialAuth Transaction
Used to capture a pre-authorisation transaction using its order id. This is applicable for both pre-auth types: PRE_AUTH
and INTIAL_AUTH
A capture must be completed for the full amount of the pre-auth, it can't be less (partial capture) or more (over capture). Also capture can only be done once and can't occur after a cancellation has been made.
To capture a pre-auth/initial-auth transaction, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture
curl https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"amount": 1000,
"status": "paid",
"orderId": "d2b65e49-e163-43ca-bd72-78dafsfe79-78g1d4c23",
"bankTransactionId": "731627310",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful"
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/preauths/{orderId}/capture
Path Variables
Parameter | Description |
---|---|
orderId | The order id used for pre-auth payment. |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. Note: The amount has to be equal to the pre-auth txn amount. |
Response
The Capture Payment Object that was successfully created.
Create Payment (Stored Payment Instrument)
To make payment for a customer, use this code:
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments -X POST
-H "Content-Type: application/json"
-H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"customerCode": "YOUR_CUSTOMER_CODE",
"merchantCode": "YOUR_MERCHANT_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"amount": "10000",
"currency": "AUD",
"status": "paid",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014"
}
Makes a payment for a logged in customer.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payments
Path Variables
Parameter | Description |
---|---|
customerCode | A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Idempotency-Key | Optional |
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key . |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. |
orderId | String | Optional |
A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
Response
The Payment that was successfully created.
Initiate Payment Order
Initiates a payment order. A Payment order has to be initiated prior making either a dynamic currency conversion (DCC) payment or a 3DS2 payment request.
The response from this request includes orderId
required for Create Payment and orderToken
required to retrieve a conversion rate by UI component (DCC) or to request 3DS2 authentication. The response for an 3DS2 order request will also include a threedSecureDetails
object with fields required during 3DS2 Authentication i.e. providerClientId
, sessionId
& simpleToken
.
Note that orderToken
expires after 10 minutes.
To create a payment order, use this code:
POST https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate
curl https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer XXXXXXXXXXXX"
-D'{ "merchantCode": "YOUR_MERCHANT_CODE",
"amount": 10000,
"ip": "127.0.0.1",
"orderReference": "Your reference for this order",
"orderType": "DYNAMIC_CURRENCY_CONVERSION"
}'
{
"ip": "127.0.0.1",
"orderReference": "Your reference for this order",
"merchantCode": "YOUR_MERCHANT_CODE",
"orderType": "DYNAMIC_CURRENCY_CONVERSION",
"amount": 10000,
"orderId": "2551d30c-250c-4d9d-afe6-3b6f2cab1ccf",
"orderToken": "YOUR_JWT_TOKEN_FOR_THIS_ORDER",
"createdAt": "2021-02-04T14:01:54.839+11:00"
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/orders/initiate
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0 in AUD, representing the total amount in cents. |
orderType | String | Required |
A type of the order to create. Currently supported types: DYNAMIC_CURRENCY_CONVERSION or THREED_SECURE . |
orderReference | String | Optional |
A client order reference, could be used as reference to the order. |
Response
The Order Details that was successfully created.
Create Payment Instrument
Allows management of tokenised payment instruments against organisation's users. This service does not directly manage the users (i.e. there is no "user" resource), that is left up to the consuming application.
To store payment instrument, use this code:
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-H "token: de305d54-75b4-431b-adb2-eb6b9e546014"
-H "ip: 127.0.0.1"
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"customerCode": "YOUR_CUSTOMER_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"scheme": "visa",
"bin": "424242",
"last4": "242",
"expiryMonth": "01",
"expiryYear": "19"
}
Stores a tokenised payment instrument against a customer identifier within the organisation (the organisation identifier is derived from authentication credentials).
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
Path Variables
Parameter | Description |
---|---|
customerCode | A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
token | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
Response
The Payment Instrument Object that was successfully created.
Payment Instruments
To retrieve payment instruments, use this code:
GET https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments -X GET
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-H "ip: 127.0.0.1"
{
"paymentInstruments": [
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"customerCode": "YOUR_CUSTOMER_CODE",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"scheme": "visa",
"bin": "424242",
"last4": "242",
"expiryMonth": "01",
"expiryYear": "19"
}
]
}
Retrieves stored payment instruments from the vault for an identified customer.
HTTP Request
GET https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments
Path Variables
Parameter | Description |
---|---|
customerCode | A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
Response
The current list of Payment Instrument Object that exist.
Delete Payment Instrument
To delete payment instrument, use this code:
DELETE https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
curl https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token -X DELETE
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-H "token: de305d54-75b4-431b-adb2-eb6b9e546014"
-H "ip: 127.0.0.1"
{
"customerCode": "DE8482",
"token": "1da87a11-4242-4163-883b-cded6d839a44",
"deleted": true
}
Deletes a previously stored payment instrument from the vault.
HTTP Request
DELETE https://payments-stest.npe.auspost.zone/v2/customers/{customerCode}/payment-instruments/token
Path Variables
Parameter | Description |
---|---|
customerCode | A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
Response
Name | Type | Description |
---|---|---|
customerCode | String | A unique (within your organisation) identifier of your customer. This value is used for security to validate that the logged in customer owns the payment instrument that is to be deleted. |
token | String | A tokenised payment instrument reference. This value uniquely identifies a payment instrument in the vault. |
deleted | Boolean | Status of deleted record. This should have a value of true if the record was found and deleted or false if no record matches the request parameters. |
Payment Objects
Payment Fraud Check Details Object
If FraudGuard rules needs to be applied before attempting the payment, fraudCheckType
should be populated with FRAUD_GUARD
value and relevant order details could be passed in the request.
If the fraud check has been performed via FraudGuard or ACI Red Shield Fraud detection endpoints, the provider reference number of the fraud check result could be passed as a part of payment request.
Name | Type | Required | Description |
---|---|---|---|
providerReferenceNumber | String | Conditional |
The provider reference number returned by FraudGuard or ACI Red Shield Fraud Detection Endpoints can be found in FraudGuard or ACI Red Shield Check Result Objects. |
fraudCheckType | String | Conditional |
If FraudGuard rules needs to be applied before attempting the payment, fraudCheckType should be populated with FRAUD_GUARD value. |
customerDetails | Object | Optional |
The Customer Details Object. |
shippingAddress | Object | Optional |
The Shipping Address Object. |
billingAddress | Object | Optional |
The Billing Address Object. |
Dynamic Currency Conversion Details Object
Used for dynamic currency conversion payments. Should be passed in dccDetails
of Create Payment request.
Name | Type | Required | Description |
---|---|---|---|
initiatedOrderId | String | Required |
Should be passed for dynamic currency conversion payments. Should be populated with dynamic conversion orderId returned in Payment Order Object |
3DS2 Details Object
Used for payments with 3DS2. Should be passed in threedSecureDetails
of Create Payment request and Create PreAuth/InitialAuth Transaction requests.
Name | Type | Required | Description |
---|---|---|---|
initiatedOrderId | String | Required |
Should be passed for payments with 3DS2. Should be populated with 3DS2 orderId returned in Payment Order Object |
liabilityShiftIndicator | String | Optional |
Optional field in Authorisation and Preauthorisation requests that is matched against the Liability Shift Indicator which SecurePay has stored from 3DS2 Authentication Response. |
Liability Shift Indicator
The purpose of this optional field in the authorisation/preauthorisation request is to:
(1) Provide control (and explicit acceptance) of whether to proceed with payments even if the 3DS2 authentication did not pass.
(2) Ensure that there has been no modification to the Liability Shift Indicator you receive in the authentication outcome, and your decision to continue with payment (or cease the payment flow) is based on correct authentication information.
Example #1: Your customer completes the 3DS2 authentication process and the Liability was not shifted, which means you are liable for fraudulent chargebacks. Based on your business reasoning you want to proceed with the payment, you must place a ‘N’ in the liabilityShiftIndicator field in the authorisation request to acknowledge and accept the liability has not been shifted to allow the payment to proceed.
Example #2: Your customer completes the 3DS2 authentication process and the Liability was not shifted. However, a malicious customer modifies the authentication outcome, and you receive an indicator that the liability was shifted to the issuer. You proceed with the payment as you understood it was shifted (but you are still liable for fraudulent chargebacks). As you have sent no value in the liabilityShiftIndicator field, the payment is rejected, protecting you and your customer. The LSI value in the authorisation request must match the Liability Shift Indicator value we have stored for the Authentication outcome. This gives control of proceeding or not proceeding with unauthenticated transactions. To see more details on how the field is sent, please refer to the integration guide for your integration in the developer resources on the SecurePay website. Please refer to the table below for the transaction flow scenarios relating to the liabilityShiftIndicator field:
SecurePay: Liability shift indicator from Authentication Outcome | Merchant: Liability Shift Indicator Sent in Authorisation Request ‘liabilityShiftIndicator’ | Result |
---|---|---|
Y | Y | Payment continues for processing |
N | N | Payment continues for processing |
Y | Not Provided | Payment continues for processing |
N | Y | 3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator |
Y | N | 3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator |
N | Not Provided | 3DS2 Payment is declined withResponse Code: 517 Response Text:Liability Shift Indicator |
PreAuth/Account Verification Fraud Check Details Object
If the fraud check has been performed via FraudGuard or ACI Red Shield Fraud detection endpoints, the provider reference number of the fraud check result could be passed as a part of payment request.
Name | Type | Required | Description |
---|---|---|---|
providerReferenceNumber | String | Conditional |
The provider reference number returned by FraudGuard or ACI Red Shield Fraud Detection Endpoints can be found in FraudGuard or ACI Red Shield Check Result Objects. |
Payment Object
A completed payment returned by Create Payment and Create Payment(Stored payment instrument)
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
token | String | The tokenised payment instrument that was used. |
ip | String | Client IP address. |
amount | String | Total amount in cents that was charged to the tokenised payment instrument. |
currency | String | Payment currency. |
status | String | The status of the payment. Valid values are paid failed unknown . If the payment was processed and succeeded the status field in payload response is set to paid. If payment was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If payment was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason. |
orderId | String | A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
bankTransactionId | String | The payment transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank or payment was declined due to results of requested FraudGuard check this field is populated with error code representing reason of failure. |
fraudCheckType | String | If payment request included FraudGuard check this field is populated with FRAUD_GUARD value. |
fraudCheckResult | Object | If payment request included FraudGuard check this field is populated fraud check result. Refer to Fraud Check Result for more details. |
Account Verification Transaction Object
A completed Account Verification transaction returned by Create Account Verification Transaction
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the Account Verification transaction is processed against. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
token | String | The tokenised payment instrument that was used. |
ip | String | Client IP address. |
orderId | String | A client order id, will be used as reference to the Account Verification. Note: < > " characters are not allowed in orderId. |
status | String | The status of the payment. Valid values are success or failed . If the verification was processed and succeeded, the status field in payload resonse is set to success. If the verification was processed but was failed, the status is set to failed and errorCode field is populated with error code related to reason of failure. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
PreAuth Payment Object
A completed payment returned by Create PreAuth/InitialAuth Transaction
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
token | String | The tokenised payment instrument that was used. |
ip | String | Client IP address. |
amount | String | Total amount in cents that was charged to the tokenised payment instrument. |
status | String | The status of the pre-auth/initial-auth transaction. Valid values are paid failed unknown . If the pre-auth/ initial-auth transaction was processed and successful the status field in payload response is set to paid. If the pre-auth/initial-auth transaction was processed but was declined, the status is set to failed and errorCode field is populated with error code related to reason of decline. If the pre-auth/initial-auth transaction was processed with unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason. |
orderId | String | A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
bankTransactionId | String | The payment transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
Cancel InitialAuth Payment Object
A initial-authorisation that was cancelled by Cancel InitialAuth Transaction.
Name | Type | Description |
---|---|---|
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | Client IP address that was used. |
amount | String | Total amount in cents that was cancelled. |
orderId | String | A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
Capture Payment Object
A completed pre-authorisation capture returned by Capture PreAuth/InitialAuth Transaction.
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | Client IP address that was used. |
amount | String | Total amount in cents that was charged to the tokenised payment instrument. |
status | String | The status of the pre-auth/initial-auth capture payment. Valid values are paid failed unknown . If the pre-auth/initial-auth capture payment was processed and successful the status field in the payload response is set to paid. If the pre-auth/initial-auth capture payment was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If the pre-auth/initial-auth capture payment was processed with an unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason. |
orderId | String | A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
bankTransactionId | String | The payment transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
Increase PreAuth Payment Object
A completed payment returned by Increase InitialAuth Transaction
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
amount | String | Total amount in cents that was increased to the tokenised payment instrument. |
status | String | The status of the transaction. Valid values are paid failed unknown . If the increase initial-auth transaction was processed and successful the status field in the payload response is set to paid . If the increase initial-auth transaction was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If the increase initial-auth transaction was processed with an unexpected status from gateway, the status is set to unknown and errorCode field is populated with error code related to reason. |
bankTransactionId | String | The payment transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | Client IP address. |
orderId | String | A client order id, will be used as reference to the payment. Note: < > " characters are not allowed in orderId. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
Payment Order Object
A completed payment returned by Initiate Payment Order
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when order was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | Client IP address. |
amount | String | Total amount in cents for this order. |
orderType | String | Payment order type. |
orderId | String | A payment order id. For orders created with intent of dynamic currency conversion payments or 3DS2 payments, the value of this field should be passed in Create Payment request in dynamic currency conversion details object or 3DS2 Details Object respectively. Note: < > " characters are not allowed in orderId. |
orderToken | String | JWT token associated with created order. For orders created with intent of dynamic currency conversion payments, this values should be passed by UI component to retrieve exchange rate details. For orders with intent of 3DS2 payments, this value should be passed to initialise the 3DS2 JS SDK library in order to authenticate the request. |
threedSecureDetails | Object | Field present only if orderType is THREED_SECURE . The 3DS2 Order Details Object. |
3DS2 Order Details Object
A response section for 3DS2 Order details in Payment Order Object
Name | Type | Description |
---|---|---|
providerClientId | String | The client Id assigned to the merchant by the 3DS2 provider. |
sessionId | String | A unique session id for an order. |
simpleToken | String | A shortened authentication token. The token is used to authenticate calls from browser. |
Payment Instrument Object
A customer payment instrument object created by Create Payment Instrument, but also returned by Payment Instruments.
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when payment instrument was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
customerCode | String | A unique (within your organisation) identifier of your customer. |
token | String | A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform transactions. Note: The token is same as the one passed in the request header. |
scheme | String | A card scheme. e.g. visa, mastercard, diners, amex.. If the card scheme card type is not known to SecurePay API unknown value will be returned. |
bin | String | Bank identification number. i.e. The first 6 digit numbers of the card. Note: Currently not supported. The field was added for future use. |
last4 | String | The last 3 digits of the card number. (Please note the number of digits returned may vary due to the card scheme) |
expiryMonth | String | Two digit number representing the card expiry month. |
expiryYear | String | Two digit number representing the card expiry year. |
Refund Object
A completed refund returned by Refund Payment.
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when refund was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
amount | String | Total amount in cents that was refunded to the tokenised payment instrument. The amount value cannot be greater than previously processed order amount. |
status | String | The status of the payment. Valid values are paid failed unknown . If the refund was processed and succeeded the status field in payload response is set to paid. If refund was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If refund was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason. |
orderId | String | A client order id which is refunded, will be used as reference number. Note: < > " characters are not allowed in orderId. |
bankTransactionId | String | The payment transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
Error Codes
Example of declined payment error response:
HTTP/1.1 201 Created
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"amount": 10051,
"currency": "AUD",
"status": "failed",
"bankTransactionId": "824565",
"gatewayResponseCode": "51",
"gatewayResponseMessage": "Not sufficient funds",
"errorCode": "INSUFFICIENT_FUNDS",
"customerCode": "anonymous",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"token": "1117760467699043",
"orderId": "6f3e0642-187d-46b3-9f9f-1af3d8e344a0"
}
Example of INVALID_ORDER_ID error response:
HTTP/1.1 400 Bad Request
{
"errors": [
{
"id": "3d5fb6a1-6ca3-4499-b8bc-3898d20945a9",
"code": "INVALID_ORDER_ID",
"detail": "Invalid request data"
}
]
}
Example of INVALID_ORDER_ID_FORMAT error response:
HTTP/1.1 400 Bad Request
{
"errors": [
{
"id": "af026c1e-0730-4313-b26f-fa857d061ebe",
"code": "INVALID_ORDER_ID_FORMAT",
"detail": "Invalid OrderId Format",
"source": {
"pointer": "orderId"
}
}
]
}
Example of authorization error response:
HTTP/1.1 401 Unauthorized
{
"message": "Unauthorized"
}
Example of internal error response:
HTTP/1.1 500 Internal Server Error
{
"errors": [
{
"id": "3d5fb6a1-6ca3-4499-b8bc-3898d20945a9",
"code": "GATEWAY_ERROR",
"detail": "Internal error"
}
]
}
Example of gateway timed out error response:
HTTP/1.1 504 Gateway Time-out
{
"errors": [
{
"id": "b5807f7e-4adc-11ee-be56-0242ac120002",
"code": "TIMED_OUT",
"detail": "The request timed out"
}
]
}
Payment Error Codes
Payments endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable | Test Data |
---|---|---|---|---|
201 | PAYMENT_DECLINED -- Payment declined |
Payment Gateway | Yes |
1005 or 1031 cents in amount field *Certain scenarios are not testable such as non-retriable declines |
201 | INSUFFICIENT_FUNDS -- Insufficient funds on payment instrument |
Payment Gateway | Yes |
1051 cents in amount field |
201 | EXPIRED_CARD -- Payment Instrument is expired |
Payment Gateway | Yes |
1033 cents in amount field |
201 | WITHDRAWAL_LIMIT -- Exceeds withdrawal amount limit |
Payment Gateway | Yes |
1061 cents in amount field |
201 | UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported |
Payment Gateway | No |
|
201 | INVALID_CVV -- Invalid CVV number |
Payment Gateway | No |
|
201 | LOST_OR_STOLEN_CARD -- Lost or stolen card |
Payment Gateway | Yes |
1007 cents in amount field |
201 | ACCOUNT_LOCKED -- Account is locked |
Payment Gateway | No |
|
201 | WITHDRAWAL_LIMIT -- Exceeds withdrawal frequency limit |
Payment Gateway | Yes |
1065 cents in amount field |
201 | GATEWAY_ERROR -- The payment gateway was not able to process the request due to an unexpected error |
Payment Gateway | Yes |
1009 cents in amount field |
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
|
400 | INVALID_ACCOUNT -- Account has not been configured for card payments or requested payment feature |
SecurePay API | Yes |
|
400 | INVALID_ORDER_ID -- Order id has to be unique per merchant |
SecurePay API | Yes |
send payment with an order id that was used by a previous payment |
400 | INVALID_ORDER_ID_FORMAT -- OrderId contains characters which are not allowed |
SecurePay API | Yes |
send an order id which contains any of these < > “ characters |
400 | TOKEN_NOT_FOUND -- Token does not exist |
SecurePay API | Yes |
send payment using a token which does not exist or does not belong to the customer |
400 | INVALID_MERCHANT_CODE -- Merchant Code is not listed in client account |
SecurePay API | Yes |
send payment with merchant not listed in account |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
send payment with an IP address that does not conform to the IPv4 or IPv6 standard |
400 | INVALID_AMOUNT -- Invalid amount for a payment |
SecurePay API | Yes |
send an amount that does not match the business rules for a specific operation (Eg: Different amount for pre-auth and capture pre-auth) |
400 | EXCEEDED_PREAUTH_AMOUNT -- Exceeded preauthorised amount |
SecurePay API | Yes |
send a partial or full cancel amount that exceeds pre-auth amount |
400 | INVALID_DCC_DETAILS -- No matching dcc order could be found for a payment request |
SecurePay API | Yes |
send payment using using initaitedOrderId that does not exist or was used by a previous payment |
401 | UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. |
SecurePay API | Yes |
|
500 | GATEWAY_ERROR -- Unexpected error while processing the request |
SecurePay API | No |
|
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
Payment Instrument Error Codes
Payments instruments endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for card payments |
SecurePay API | Yes |
400 | INVALID_TOKEN -- Token provided in payload is either already stored against some customer or does not exist in the system. |
SecurePay API | Yes |
400 | INVALID_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 |
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
Refund Error Codes
Refund endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
201 | REFUND_NOT_ALLOWED -- If refund amount is more than the previous paid order amount |
Payment Gateway | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for card payments |
SecurePay API | Yes |
400 | TRANSACTION_NOT_FOUND -- OrderId passed in refund request does not exist |
Payment Gateway | Yes |
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
401 | UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
500 | GATEWAY_ERROR -- Error while doing refund |
Payment Gateway | No |
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
Tokenise Instrument Error Codes
Tokenise endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Send malformed JSON in request |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for card payments |
SecurePay API | Yes |
400 | INVALID_CVV -- Invalid CVV details |
Payment Gateway | Yes |
400 | INVALID_PIN -- Invalid PIN details |
Payment Gateway | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
400 | DCC_QUOTE_IN_PROGRESS -- Could happen in dcc mode only. When tokenise call is made prior onDCCQuoteSuccess was invoked |
SecurePay API | Yes |
400 | INVALID_FORM_DETAILS -- Could happen in dcc mode only. When tokenise call is made prior user entered all required fields or selected the Currency option. |
SecurePay API | Yes |
400 | INVALID_ORDER_TOKEN -- Could happen in dcc mode only. When tokenise call is made after onDCCQuoteError callback invoked |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Tokenise error from SecurePay API |
SecurePay API | Yes |
500 | GATEWAY_ERROR -- Tokenisation error from Payment Gateway |
Payment Gateway | No |
500 | INVALID_CARD_DETAILS -- Invalid card details (could be number, cvv, expiry date, mismatch of cc details) |
Payment Gateway | Yes |
500 | PRE_AUTH_FAILED -- Pre-auth failed (could be cvv or any other reason, e.g. card blocked) |
Payment Gateway | Yes |
500 | INVALID_REQUEST_DATA -- Invalid request data (e.g. Invalid IP address) |
Payment Gateway | Yes |
500 | INVALID_ACCOUNT_DETAILS -- Invalid bank account details (bsb, account number, account name) |
Payment Gateway | No |
500 | INSUFFICIENT_FUNDS -- Insufficient funds |
Payment Gateway | Yes |
500 | EXPIRY_DATE -- Invalid expiry date |
Payment Gateway | No |
500 | UNSUPPORTED_CARD_TYPE -- Payment Instrument type not supported |
Payment Gateway | No |
500 | RESTRICTED_CARD_OR_ACCOUNT -- Restricted card or account |
Payment Gateway | No |
500 | LOST_OR_STOLEN_CARD -- Lost or stolen card |
Payment Gateway | No |
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
Testing
You can use the following test card numbers in our sandbox environment.
Card Type | Card Number |
---|---|
Visa | 4111111111111111 |
Visa | 4242424242424242 |
MasterCard | 5555555555554444 |
American Express | 378282246310005 |
For dynamic currency conversion payments you can use card numbers starting with the BIN below numbers in our sandbox environment. A DCC Quote retrieved only after 10 digits are typed in.
BIN | Currency |
---|---|
4242424242424242 | triggers scenario when card currency is not in the list of supported currencies or AUD, results in payment in AUD currency. |
4314261614350081 | USD |
5139006234627198 | EUR |
5432500000000006 | NZD |
5253030000000000 | GBP |
4472010000000000 | IDR |
5303990000000005 | CRC |
5306950000000006 | COP |
4073440000000002 | JMD |
4106750000000005 | ZAR |
4600050000000001 | PHP |
5440140000000001 | ARS |
4196070000000009 | INR |
4030860000000003 | AED |
5486530000000008 | CLP |
4147900000000007 | TTD |
4406960000000007 | UYU |
5579050000000005 | MXN |
4791320000000007 | GYD |
4006700000000001 | HKD |
4518770000000005 | GTQ |
5248050000000006 | JPY |
5240400000000001 | SGD |
5500180000000004 | CHF |
5269480000000009 | NOK |
4365110000000008 | MYR |
5476640000000007 | BBD |
4107340000000004 | TZS |
4301980000000001 | QAR |
5192900000000008 | CAD |
4757700000000002 | BRL |
3DS2 Testing
To test 3DS2 in the Sandbox environment, use Merchant Code of 5AR0055 when creating the 3DS2 payment order. You are not able to use your own Merchant Code and must use the Sandbox Test Merchant Code: 5AR0055. Please contact support at support@securepay.com.au if you need an alternate testing set up.
To use the test cards below you must use:
- Merchant Code: 5AR0055 and associated credentials for authentication, as well as using 5AR0055 when creating a 3DS2 payment order
- Card Holder Name: Test Card or an empty value
- Expiry date (YYMM): value must either be 2508 or an empty value
The Merchant ID, cardholder name, and expiry date must be set as above otherwise the authentication will fail.
Test Cards:
Authentication Outcome | transStatus | Card Type | Card Number | Challenge password | ECI |
---|---|---|---|---|---|
Frictionless | Y | VISA | 4100000000000100 | N/A | 05 |
Frictionless | Y | MasterCard | 5100000000000107 | N/A | 02 |
Frictionless | Y | AMEX | 340000000000108 | N/A | 05 |
Challenge | Y | VISA | 4100000000005000 | 123456 | 05 |
Challenge | Y | MasterCard | 5100000000005007 | 123456 | 02 |
Challenge | Y | AMEX | 340000000005008 | 123456 | 05 |
Challenge failed | N | VISA | 4100000000300005 | 111111 | Per card scheme |
Challenge failed | N | MasterCard | 5100000000300002 | 111111 | Per card scheme |
Challenge failed | N | AMEX | 340000000300003 | 111111 | Per card scheme |
Unavailable | U | VISA | 4100000000400003 | N/A | Per card scheme |
Unavailable | U | MasterCard | 5100000000400000 | N/A | Per card scheme |
Unavailable | U | AMEX | 340000000400001 | N/A | Per card scheme |
Rejected | R | VISA | 4100000000500000 | N/A | Per card scheme |
Rejected | R | MasterCard | 5100000000500007 | N/A | Per card scheme |
Rejected | R | AMEX | 340000000500008 | N/A | Per card scheme |
Attempted | A | VISA | 4100000000100009 | N/A | 06 |
Attempted | A | MasterCard | 5100000000100006 | N/A | 01 |
Attempted | A | AMEX | 340000000100007 | N/A | 06 |
Apple Pay Payments
Overview
Apple Pay is a simple and secure way for your customers to pay with their Apple Wallet on SecurePay. It allows your customers to quickly pay you using their credit or debit card that is stored on their Apple device, eliminating the need to enter card details. Each transaction is secured with Face ID, Touch ID or passcode. Click here to learn more about Apple Pay.
Apple Pay is available on NAB, ANZ and Fiserv (Westpac, Bankwest, St.George, Macquarie, FDMSA) acquiring bank links.
Before implementing Apple Pay, please see the below links:
How it works
Customers select Apple Pay when they want to check out. A payment sheet is shown to the customer, and they then authenticate using Face ID, Touch ID or passcode. The payment is then authorised by the card issuer.
On Apple Device
Initialise Session
1.1. Customer chooses to pay with Apple Pay by clicking Buy with Apple Pay button, then the browser makes Initiate Session call to your (merchant's) server.
1.2. Your server then sends the Initiate Session
request to SecurePay API to initialise the Apple Pay session.
1.3. SecurePay API sends initialise session request to Apple Pay server.
1.4. Initialise session response returned to the customer browser.
Payment Authorisation
2.1. When customer authorises the Payment with Touch ID, Face ID or Passcode, encrypted payment data request is sent to Apple Pay from a device.
2.2. Apple Pay returns encrypted Payment Data.
2.3. Apple Device sends Payment Request with encrypted payment data to your server.
2.4. Your server sends Apple Pay Payment Request
to SecurePay API.
2.5. Once the SecurePay API Processes the payment, response is sent back to your server.
Integration with Apple Pay
Integrating Apple Pay on your website is simple. You'll need to follow the instructions on using the Apple Pay JS API.
You'll need to make sure you follow Apple's marketing guidelines found here
.
Apple Pay Account setup
Before you can start integrating with Apple Pay, you will need to register the domains you would like to use for Apple Pay. This can be done by logging in to your SecurePay Account.
Firstly, for your live account, you will need to complete domain verification. Apple requires you to verify that you own the domains you are registering to use with Apple Pay. You will have to host the file at this location https://{domain-name}/.well-known/apple-developer-merchantid-domain-association
(where {domain-name}
is your domain) and make sure the file is accessible over the internet.
For Sandbox account, you can skip above step and simply register the domains.
For Sandbox
To test your integration, you will need to log in to your SecurePay Account to generate and obtain your Apple Pay specific credentials.
In the test credentials section of SecurePay Account, select Sandbox Credentials - Apple Pay
and follow on-screen instructions to configure Apple Pay in sandbox environment. Please note, your Sandbox Credentials - Apple Pay
credentials are different to your existing test credentials
and are unique to your Merchant Code.
You must register the domains you would like to use for sandbox testing by selecting Configure Apple Pay Sandbox
.
Later you will need these registered domains for Initiate Session Request
.
For Live
You can activate Apple Pay from the Payment features
tab by completing the instant application.
In the application, follow the steps to verify ownership of your domains. You must register the domains you would like to use for your live payments.
Later you will need these registered domains for Initiate Session Request
.
Your live credentials are the same as your existing live credentials.
On Safari Browser
This integration guide will help to integrate Apple Pay JS API
with your (merchant's) website.
Pre-requisite
- Apple Pay Account setup, please follow the instructions
here
. - Your customer must have an Apple device with a supported iOS/macOS/iPadOS version and use the Safari browser. For more details please visit
Apple Pay Availability by Region and Platform.
- In order to use Apple Pay, a user also must first add a credit or debit card to their Apple wallet.
Technical Details
Initiate Session
Apple Pay Button on web
<html>
<head>
<style type="text/css">
/* CSS */
.title {
color: blue;
text-decoration: bold;
text-size: 1em;
}
.author {
color: gray;
}
.apple-pay-button {
display: inline-block;
-webkit-appearance: -apple-pay-button;
-apple-pay-button-type: buy; /* Use any supported button type like donate, plain. Refer https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons */
}
.apple-pay-button-black {
-apple-pay-button-style: black;
}
.applePayButtonContainer {
width: auto;
height: auto;
padding: 0;
margin: 0;
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
}
</style>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
<script>
$(document).ready(() => {
//1.1
/*Check that the window.ApplePaySession class exists to ensure Apple Pay is supported and available in the browser.
Then, call supportsVersion with the ApplePaySession that will be used (link in description for more details on supportVersion).
Finally, call canMakePayments to ensure that the device is capable of making Apple Pay payments */
//ApplePaySession.canMakePayments() this works only when https is enabled in server, please enable https in local server for development.
if (ApplePaySession && ApplePaySession.canMakePayments()) {
$('.unsupportedBrowserMessage').css('display', 'none');
$('.apple-pay-button').css('display', 'block');
console.log('Startup Check: Device is capable of making Apple Pay payments');
}
});
function onApplePayButtonClicked() {
console.log('Clicked Buy with Apple Pay');
}
</script>
</head>
<body>
<div class="unsupportedBrowserMessage" style="display: block;">
Your browser does not support Apple Pay on the web.<br>
To try this demo, open this page in Safari.<br>
(See <a href="#requirements">Requirements</a>.)
</div>
<div class="applePayButtonContainer">
<a lang="us" id="overviewApplePayButton" class="apple-pay-button apple-pay-button-black" onclick="onApplePayButtonClicked()" title="Start Apple Pay"
role="link" tabindex="0" style="display: none;"></a>
</div>
</body>
</html>
Sample code for Apple Pay web integration
function onApplePayButtonClicked() {
//1.1 session.begin() is called at last after initialising required callbacks
//ref.1.2
const paymentRequest = generatePaymentRequest();
const session = new ApplePaySession(APPLE_PAY_VERSION, paymentRequest)
//ref.1.3
session.onvalidatemerchant = function (event) {
//here you will be making a call to SecurePay API Initialise Session
const promise = requestApplePaySession();
promise.then(function (session) {
//ref.1.4
session.completeMerchantValidation(session.sessionObject);
}).catch(function (error) {
//abort() will trigger oncancel handler where you can handle error
session.abort();
//here you can handle error
return;
});
}
//oncancel handler is called when UI is dismissed
session.oncancel = (event) => {
console.log("Session canceled called when UI is dismissed" + JSON.stringify(event))
}
//ref.2.1/2.2
session.onpaymentauthorized = function (event) {
//ref.2.3 here you will be making a call to SecurePay API Payment Request
mercahntApi.payment({
//The event parameter contains the ApplePayPayment attribute.
//Ref. https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypayment
//Also, map this object with SecurePay Apple Pay Payment Api
token: event.payment
}, function (err, paymentResponse) {
if (err) {
//ref.2.5
session.completePayment(session.STATUS_FAILURE);
return;
}
//ref.2.4
session.completePayment(session.STATUS_SUCCESS);
//Send payment data details to your server.
});
}
//ref.1.1 This is important call to begin the session initialisation process
session.begin();
function generatePaymentRequest() {
const request = {
countryCode: "AU",
currencyCode: "AUD",
merchantCapabilities: ["supports3DS"],
supportedNetworks: ["masterCard", "visa"],
total: {
amount: 100.00,
label: "The Cake Store",
type: "final"
}
}
return request;
}
}
1.1. Before displaying Apple Pay as a payment option in your website, determine if the user’s device supports Apple Pay and respective version.
If it does then show Apple Pay Button
.
Reference Links for integration of Apple Pay Button
- Apple Pay Button
- Customising and styling the Apple Pay Button
- Apple Pay Supported Version on the web
1.2. When the user taps the Apple Pay button, you need to call a JS function which will create a session
object with PaymentRequest
.
Here, you can set PaymentRequest to display your business name and the total amount. You can also collect information like billing details or shipping information.
See Apple’s documentation for full guidance on how to customize the payment request of ApplePaySession.
1.3. Then call session.begin()
which
will initiate Apple JS API Merchant Validation process.
1.3. Once you do call session.begin()
, the browser will invoke session.onvalidatemerchant
handler,
which must create a merchant session from your server by calling Initiate Session
to SecurePay API.
For security reasons, your server must do this call, not your browser client code.
1.4. After the successful session response comes back, use response.sessionObject on completeMerchantValidation(sessionObject)
to complete session.onvalidatemerchant()
handler.
1.5. The browser will then display the payment sheet where your customer needs to authorise the payment.
Initiate Payment after Authorisation
2.1. Next when your customer authorised the payment with Touch ID, Face ID or Passcode, onpaymentauthorized
event handler is called on session object.
2.2. Here, you must implement the session.onpaymentauthorized
handler,
that will be responsible for processing the payment transaction. Please follow the Apple Pay guidelines on the usage of onpaymentauthorized handler.
2.3. Your server then sends the Apple Pay Payment Request
to SecurePay API.
Again for security reasons, your server must do this call, not your browser client code.
2.4. And lastly, after getting a Payment Response, call session.completePayment(..)
with appropriate Status Code from ApplePaySession
.
2.5. In case of error response, use STATUS_FAILURE with an array of associated ApplePayError
objects.
Testing
- Before you start, use merchant’s own credential by logging in to your SecurePay account. Please see these are separate
clientId
andsecret
from other Playground test credentials you might have. - Test Credit Cards are available at Apple Pay - Sandbox Testing - Apple Developer for testing. Also, SecurePay only supports Visa and Mastercard cards as of now.
- The Apple Developer website provides the tools and information you need to make great apps for Apple platforms. If you’re new to development on Apple platforms, you can get started for free. Apple may charge additional fees for the developer account.
The steps to create the developer account are as follow:
- You first have to accept this developer agreement by clicking this link accept the Apple Developer Agreement.
- If you do not already have an Apple ID, click the link to create one.
- You have successfully created an Apple developer account!
- Please refer to Account - Help - Apple Developer for the complete guide to create an Apple developer account
- Once developer account is created then apple developer account can be used to login to app store and connect to create your test account for ApplePay wallet - Sandbox Testing - Apple Pay.
Rest API
Initiate Session
Initiate Session API:
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate
Request:
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
{
"domain": "cakebaking.com",
"displayName": "Cake Store",
"merchantCode": "MERCHANT_CODE",
"ip": "127.0.0.1"
}
Response:
{
"merchantCode": "MERCHANT_CODE",
"ip": "127.0.0.1",
"sessionObject": {...}
}
SecurePay initiates a session with Apple Pay.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/sessions/initiate
Header Parameters
Parameter | Required |
Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required |
Description |
---|---|---|---|
domain | String | Required |
The merchant domain registered with Apple Pay and it must be the domain where customer is making a payment . Must not be longer than 255 characters. |
displayName | String | Required |
The merchant name that will be displayed to customer while authorising the payment. Must not be longer than 64 characters. |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6. |
Response
Name | Type | Description |
---|---|---|
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | A customer IP address. Must be a valid IPv4 or IPv6. |
sessionObject | Object | Contains the object that was returned by Apple Pay. Should be passed by merchant to device as it is. |
Apple Pay Payment
Apple Pay Payment API:
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments
Request:
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-H "Idempotency-Key: 022361c6-3e59-40df-a58d-532bcc63c3ed"
{
"amount": 10000,
"currrency": "AUD",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"paymentData": {
"encryptedData": "Szv0rBU1zE1cwbszivpKrWx...",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQE",
"version": "EC_v1",
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEJJak7jaMn7vzU...",
"publicKeyHash": "7zbHcn1VIPU/+gfdlnglvsvnvfvscsd=",
"transactionId": "1f2239b7ce042f736c5c9829f115ff2fc87a4b3dd518bfd83cadd6b765c785ac",
"applicationData": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
}
Response:
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"amount": "10000",
"currency": "AUD",
"status": "paid",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Transaction successful",
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac"
}
SecurePay supports only Visa and Mastercard cards as of now.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/payments
Header Parameters
Parameter | Required |
Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Idempotency-Key | Optional |
This key allows a client to safely retry the payment request if it fails to receive a response from the server, e.g. due to a network connection error, etc. The server guarantees to process a payment only once if the same key is used across multiple transactions within 12 hours. It is important for the client to generate random keys, hence the use of UUIDs is strongly encouraged but not enforced by the application. If not passed orderId will be used as Idempotency-Key. |
Request Parameters
Parameter | Type | Required |
Description |
---|---|---|---|
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. |
currency | String | Optional |
Payment currency. Default value is AUD. If value is set, then it must be AUD. |
orderId | String | Optional |
A client order id, will be used as reference to the payment. Must be unique and no longer than 60 characters. |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6. |
paymentData | Object | Required |
Refer to PaymentData object details for more details. |
Apple Pay Payment Data Object
Use event.payment.token.paymentData
of onpaymentauthorized
Apple JS callback event to populate Payment Data object fields.
Parameter | Type | Required |
Description |
---|---|---|---|
encryptedData | String | Required |
Encrypted payment data, set as paymentData.data . |
signature | String | Required |
Signature of the payment and header data, set as paymentData.signature |
version | String | Required |
Version information about the payment token, set as paymentData.version |
ephemeralPublicKey | String | Required |
Ephemeral public key bytes, set as paymentData.header.ephemeralPublicKey |
publicKeyHash | String | Required |
Hash of the X.509 merchant’s certificate, set as paymentData.header.publicKeyHash . |
transactionId | String | Required |
Transaction identifier, generated on the device. Set as paymentData.header.transactionId . |
applicationData | String | Conditional |
Set as paymentData.header.applicationData . Check if applicationData is being set, ref.1.2 of Session's Payment Request , if it is then this must be passed in Payment Request Api. |
Response
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when transaction was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
amount | Integer | An integer value greater than 0, representing the total amount in cents. |
currency | String | Payment currency. |
status | String | The status of the payment. Valid values are paid , failed , unknown . Refer to Payment transaction status for details. |
bankTransactionId | String | The reference number to the order, issued by provider. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for Apple Pay payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
merchantCode | String | Merchant account for which the funds are collected. |
ip | String | Client IP address. |
orderId | String | A client order id, will be used as reference to the payment. |
Refund Apple Pay Payment
Used to refund a previous Apple Pay payment. Can only be used for AUD transactions.
To refund Apple Pay payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"amount": 10000,
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"bankTransactionId": "de305d54-75b4-431b-adb2-eb6b9e546014",
"gatewayResponseCode": "00",
"gatewayResponseMessage": "Approved"
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/applepay/orders/{orderId}/refunds
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Path Variables
Parameter | Description |
---|---|
orderId | A customer order id which was successfully processed previously and the merchant now wants to refund it. |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
merchantCode | String | Required |
Merchant account for which the funds are collected. |
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to refund. The amount will be refunded to the same payment instrument from which the payment was made for the order. The amount value to be refunded should be less then or equal to the actual paid amount. |
Response
Name | Type | Description |
---|---|---|
createdAt | String | A timestamp when refund was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | String | Merchant account for which the funds are collected. |
amount | String | Total amount in cents that was refunded to the payment instrument. The amount value cannot be greater than previously processed order amount. |
status | String | The status of the refund. Valid values are paid failed unknown . If the refund was processed and succeeded the status field in payload response is set to paid. If refund was processed but was declined the status is set to failed and errorCode field is populated with error code related to reason of decline. If refund was processed with unexpected status from gateway the status is set to unknown and errorCode field is populated with error code related to reason. |
orderId | String | A client order id which is refunded, will be used as reference number. |
bankTransactionId | String | The refund transaction reference from the payment gateway. |
gatewayResponseCode | String | Bank response code which identifies the reason the transaction was approved or decline. Refer to bank response code for card payments. |
gatewayResponseMessage | String | Detailed message of the bank response code. |
errorCode | String | If transaction was processed but declined by the bank this field is populated with error code representing reason of failure. |
Payment Transaction Status
Status | Description |
---|---|
paid |
The payment has been successful. |
failed |
The payment has been failed. |
unknown |
The result of execution is not determined(e.g. due to connectivity issues). |
Error Codes
SecurePay Apple Pay endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
400 | INVALID_REQUEST_DATA -- Invalid request data |
SecurePay API | Yes |
400 | INVALID_REQUEST_DATA -- Unable to decrypt Payment Data |
SecurePay API | Yes |
400 | INVALID_REQUEST_DATA -- Amount and Currency mismatch |
SecurePay API | Yes |
400 | INVALID_APPLE_PAY_DETAILS -- DomainName is not registered with Apple Pay |
SecurePay API | Yes |
400 | INVALID_ORDER_ID -- Order id has to be unique per merchant and must be no longer than 49 characters |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for Apple Pay payments |
SecurePay API | Yes |
500 | GATEWAY_ERROR -- Refund failure from Payment provider |
Provider | No |
401 | UNAUTHORIZED -- Provided invalid Http access token. Refer to client credentials for more information. |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
400 | TRANSACTION_NOT_FOUND -- Order doesn't exist or not paid |
SecurePay API | Yes |
Direct Entry Payments
Overview
Direct Entry payments includes both direct debit and direct credit functionality.
These transactions use the BSB and account number to charge a customer’s bank account (direct debit) or to send funds to a customer's bank account (direct credit). To be eligible to use direct debit, you must have an active direct debit or direct credit account with SecurePay.
Direct entry payments are not processed in real time; they are stored in SecurePay’s database and processed daily. Direct entry transactions can be viewed in the merchant portal.
Rest API
Create Direct Entry Payment
Used to make direct debit and credit payments.
To do direct entry payment, use this code:
POST https://payments-stest.npe.auspost.zone/v2/direct-entry
curl https://payments-stest.npe.auspost.zone/v2/direct-entry -X POST
-H "Content-Type: application/json"
-H "Authorisation: Bearer xxxxxxxx"
-d '{
"ip": "127.0.0.1",
"merchantCode": "YOUR_MERCHANT_CODE",
"orderId": "9fe4b0a848ac",
"amount": 10000,
"paymentMethod": "DirectCredit",
"bsb": "013457",
"accountNumber": "123456789",
"accountName": "Jane Doe",
}'
{
"orderId": "9fe4b0a848ac",
"transactionId": "848403",
"settlementDate": "2020-08-03",
"amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"paymentMethod": "DirectCredit",
"bsb": "013457",
"accountNumber": "123456789",
"accountName": "Jane Doe",
"ip": "127.0.0.1"
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/direct-entry
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 . |
merchantCode | String | Required |
Merchant account code for which payment is performed. |
orderId | String | Required |
A client order id, will be used as reference to the payment. Should not be longer than 18 characters. Supported characters are alphanumeric, ' ' (blank space) and special characters: / - & . * ' . |
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the account. |
bsb | String | Required |
6-digit Australian bank-state-branch (BSB) number. |
accountNumber | String | Required |
The account number for the bank account. Should not be longer than 9 characters. |
accountName | String | Required |
The name of the person or business that owns the bank account. Should not be longer than 32 characters. |
paymentMethod | String | Required |
The type of payment. Supported values are DirectDebit and DirectCredit . |
Response
Name | Type | Description |
---|---|---|
ip | String | Client IP address. |
merchantCode | String | Merchant account for which the funds are collected. |
orderId | String | A client order id, will be used as reference to the payment. |
transactionId | String | The payment transaction reference from the payment gateway. |
amount | String | Total amount in cents that was charged to the account. |
settlementDate | String | The settlement date of a successful payment. |
paymentMethod | String | The type of payment performed. Values are DirectDebit and DirectCredit |
bsb | String | 6-digit Australian bank-state-branch (BSB) number. |
accountNumber | String | The account number for the bank account. |
accountName | String | The name of the person or business that owns the bank account. |
Error Codes
Direct Entry endpoint uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
400 | DDA_NOT_FOUND -- The DDA was not found |
Payment Gateway | No |
400 | BELOW_DDA_MIN_AMOUNT -- Amount is lower than the DDA min limit |
Payment Gateway | No |
400 | EXCEEDED_DDA_MAX_AMOUNT -- Amount is higher than the DDA max limit |
Payment Gateway | No |
400 | EXPIRED_DDA -- The DDA has expired |
Payment Gateway | No |
400 | INVALID_ACCOUNT -- Account has not been configured for direct entry payments |
Payment Gateway | No |
401 | UNAUTHORIZED -- Provided invalid credentials. Refer to bearer auth for more information. |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | No |
500 | GATEWAY_ERROR -- Error while processing the request |
Payment Gateway | No |
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
PayPal Payments
How it works
To include the PayPal button please refer to the PayPal Checkout Button Integration example.
1.1. When the user clicks on the PayPal button, it triggers the payment()
callback function from the PayPal Button. In that method, you make a call to your server to make an Initiate PayPal Txn
.
1.2. Your server then proxies the request to perform the Initiate PayPal Txn
to SecurePay API.
2.1. Your server receives the Initiate PayPal Txn Response
from SecurePay API which contains the paymentId
.
2.2. Your app/web then receives the response in the payment()
callback function, which then return the paymentId
.
3.1. PayPal script loads the PayPal LightBox, where the user login and authorize the payment.
4.1. Once the user authorize the payment, the onAuthorize()
callback function is called. You now have access to the payerId
which is required for the next step.
5.1. In the onAuthorize()
function, you make a call to your server to make an Execute PayPal Txn
to perform the payment.
5.2. Your server then proxies the request to perform the Execute PayPal Txn
.
6.1. Your server receives the Execute PayPal Txn Response
from SecurePay API.
6.2. Your app/web then receives the response in the onAuthorize()
.
7.1 PayPal will render the success/failure page based on the following callbacks onAuthorize
,onCancel
and onError
.
Sample code
Sample code for PayPal button web integration:
paypal.Button.render({
env: 'sandbox',
locale: 'en_AU',
style: { size: 'responsive', color: 'silver', shape: 'pill', label: 'pay' },
commit: true,
payment: function() { // initiate payment
return getPaymentId().then(function(paymentId) {
console.log('SecurePay API responded with paymentId:', paymentId);
return paymentId;
})
},
onAuthorize: function(data, actions) { // execute payment
console.log('Sending authorization request to SecurePay API with payerID:', data.payerID);
return authorizePayment(data.payerID).then(function(response) {
console.log('SecurePay API responded with data:', response);
})
}
}, '#paypal-button'); // element where paypal button will be injected
var amount = 5075;
var merchantCode = 'XXXXXXXXXXX';
var orderId = Date.now();
var ip = '127.0.0.1';
function getPaymentId() {
return new Promise(function (resolve, reject) {
var xhttp = new XMLHttpRequest();
//Important this call is to the merchant server not SecurePay API
xhttp.open('POST', '/your-backend-api/paypal/initiate', true); // API proxies request through to SecurePay API: /v1/wallets/paypal/payments/initiate
xhttp.setRequestHeader('content-type', 'application/json');
xhttp.onload = function () {
if (this.status == 200) {
resolve(JSON.parse(xhttp.response).paymentId);
}
};
xhttp.send(JSON.stringify({
amount: amount,
merchantCode: merchantCode,
ip: ip,
orderId: orderId
}));
});
}
function authorizePayment(payerId) {
return new Promise(function (resolve, reject) {
var xhttp = new XMLHttpRequest();
//Important this call is to the client server not SecurePay API
xhttp.open('POST', '/your-backend-api/paypal/execute', true); // API proxies request through to SecurePay API: '/v1/wallets/paypal/payments/orders/orderId/execute'
xhttp.setRequestHeader('content-type', 'application/json');
xhttp.onload = function () {
if (this.status == 200) {
resolve(JSON.parse(xhttp.response));
}
};
xhttp.send(JSON.stringify({
amount: amount,
merchantCode: merchantCode,
ip: ip,
orderId: orderId,
payerId: payerId
}));
});
}
This method adds a Paypal button
to the client website, which when clicked, opens a PayPal lightbox overlaying the current webpage. It utilises PayPal's standard express checkout flow and code.
To implement this method, the client should:
1 - add the following PayPal script to their page:
<script src="https://www.paypalobjects.com/api/checkout.js"></script>
2 - add a div where the paypal button will be inserted:
<div id="paypal-button"></div>
3 - add the PayPal paypal.Button.render
code snippet (as shown opposite).
The PayPal code snippet inserts the PayPal button into the DOM within the element specified. When the user clicks on this button, it triggers the payment()
callback function to be called.
This function expects a PayPal paymentId
to be returned via a promise.
The paymentID
is obtained via a call to SecurePay API's Initiate PayPal Transaction service API.
The code example opposite: getPaymentId()
provides an example of how this API call could be implemented using a Promise.
When the promise is resolved, and paymentId
returned, the PayPal script loads the lightbox, where the user can login
and authorise the payment.
Once the user is done, the onAuthorize()
callback function is called automatically.
Within this function a call should be made to SecurePay API's Execute PayPal Transaction
service API to execute the payment.
The code example opposite: authorizePayment()
provides an example of how this API call could be implemented
using a Promise.
Note: the payerID
is obtained from the input parameter to onAuthorize()
and sent in the POST request to the SecurePay API.
Rest API
Initiate PayPal Transaction
To initiate PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate
curl https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"paymentType": "sale",
"noShipping": true,
"billingDescription": "text displayed to buyer",
"redirectUrls": {
"successUrl": "http://<success url>",
"cancelUrl": "http://<cancel url>"
},
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "anonymous",
"ip": "127.0.0.1",
"amount": "10000",
"paymentUrl": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-2B968028MX02434E",
"paymentId": "EC-2B968028MX02434E",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"paymentType": "sale",
"noShipping": true
}
Initiates a PayPal express checkout transaction.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/initiate
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Required | Description |
---|---|---|
merchantCode | Required |
Merchant account for which the funds are collected. |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Required |
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. |
orderId | Optional |
A client order id, will be used as reference to the payment. |
paymentType | Optional |
This parameter defines what kind of PayPal transaction you are initiating. Supported type is sale . sale is used for a once-off payment. Default is set to sale . |
noShipping | Optional |
Defines if shipping address will be made visible when customer logs into PayPal account to authorise the transaction. Set it to true if you don't want to make shipping address visible to customer - in case of digital goods. Default value is false . |
billingDescription | Optional |
The text will appear on customer's PayPal account, as they will login to there PayPal account to authorise the transaction. Note: This feature is currently supported only for paymentType recurring only. |
redirectUrls | Required |
Refer to Redirect URLs for more details. |
Redirect URLs
Parameter | Required | Description |
---|---|---|
successUrl | Required |
The URL to which the client will be redirected to after successful PayPal authorisation. |
cancelUrl | Required |
The URL to which the client will be redirected to in case of failure or cancellation of PayPal authorisation. |
Response
Name | Description |
---|---|
createdAt | A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | Merchant account for which the funds are collected. |
customerCode | The identifier for the customer. In case of anonymous payment it is always anonymous . |
ip | Client IP address. |
amount | An integer value greater than 0, representing the total amount in cents. |
orderId | A client order id, will be used as reference to the payment. |
paymentId | The token id issued by PayPal to initiate the transaction. Token will expire after 3 hours. |
paymentUrl | The URL issued by PayPal to initiate the transaction. |
paymentType | This parameter defines what kind of PayPal transaction you are initiating. Following types are supported sale . sale is used for a once-off payment. Default is set to sale . |
noShipping | Defines if shipping address will be made visible when customer logs into PayPal account to authorise the transaction. Set it to true if you don't want to make shipping address visible to customer - in case of digital goods. |
errorCode | If transaction was having some issues and field is populated with error code representing reason of failure. |
Execute PayPal Transaction
To execute PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/orders/{orderId}/execute
curl https://payments-stest.npe.auspost.zone/v1/wallets/paypal/payments/orders/{orderId}/execute -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1",
"payerId": "1234"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "anonymous",
"ip": "127.0.0.1",
"amount": "10000",
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"providerReferenceNumber": "7LT4359579269504C"
}
Executes a PayPal express checkout transaction after the customer has logged into PayPal and accepted it.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/payments/orders/{orderId}/execute
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Path Variables
Parameter | Description |
---|---|
orderId | A client's order id received after successful processing of Initiate PayPal Transaction. |
Request Parameters
Parameter | Required | Description |
---|---|---|
merchantCode | Required |
Merchant account for which the funds are collected. |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Required |
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. |
payerId | Required |
The payer id returned from PayPal after customer has completed authorisation . |
Response
Name | Description |
---|---|
createdAt | A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | Merchant account for which the funds are collected. |
customerCode | The identifier for the customer. In case of anonymous payment it is always anonymous . |
ip | Client IP address. |
amount | An integer value greater than 0, representing the total amount in cents. |
orderId | A client order id, will be used as reference to the payment. |
providerReferenceNumber | The transaction id returned from PayPal. Will be empty if no response has been received back from PayPal. |
providerDetails | The PayPal Provider Details associated with the transaction. Please note this field will only be returned if PayPal Gateway return those details. |
status | The status of the payment. Valid values are paid , failed , inprogress and unknown . Refer to the table below for details: |
PayPal Express checkout transaction statuses
Status | Description |
---|---|
inprogress |
The transaction is in pending state or it has not terminated, e.g. an authorisation may be awaiting completion. |
paid |
The payment has been captured. |
failed |
The payment has failed. |
unknown |
The result of execution is not determined(e.g. due to connectivity issues). To verify the status in this case use retrieve PayPal order details endpoint. |
Refund PayPal Transaction
To refund PayPal transaction:
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds
curl https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{ "amount": 10000,
"merchantCode": "YOUR_MERCHANT_CODE",
"ip": "127.0.0.1"
}'
{
"createdAt": "2021-07-23T13:00:53.128+10:00",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "anonymous",
"ip": "127.0.0.1",
"amount": "10000",
"status": "paid",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"providerReferenceNumber": "7LT4359579269504C"
}
Refunds a previously executed PayPal transaction.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}/refunds
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Path Variables
Parameter | Description |
---|---|
orderId | A customer order id which was successfully processed previously which the merchant now wants to refund. |
Request Parameters
Parameter | Required | Description |
---|---|---|
merchantCode | Required |
Merchant account for which the funds are collected. |
ip | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
amount | Required |
An integer value greater than 0, representing the total amount in cents for which the transaction will be initiated. |
Response
Name | Description |
---|---|
createdAt | A timestamp when plan was created, in ISO Date Time format with offset from UTC/Greenwich e.g. 2021-07-23T13:00:53.128+10:00. |
merchantCode | Merchant account for which the funds are collected. |
customerCode | The identifier for the customer. In case of anonymous payment it is always anonymous . |
ip | Client IP address. |
amount | An integer value greater than 0, representing the total amount in cents. |
status | The status of the payment. Valid values are paid failed . |
orderId | A client order id, will be used as reference to the payment. |
providerReferenceNumber | The transaction id returned from paypal. |
errorCode | If transaction was having some issues and field is populated with error code representing reason of failure. |
Retrieve PayPal order details
To retrieve status, billing & shipping details of PayPal payment by order id:
GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
curl -X GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
{
"orderId": "01cce4c5-3cf3-4fb5-81ea-2425e6c532d8",
"paymentId": "PAYID-LWCHDSY21197268NE401560F",
"status": "paid",
"amount": "10000",
"payerDetails": {
"firstName": "Joe",
"lastName": "Smith",
"email": "joe.smith@some-email-address.com"
},
"shippingAddress": {
"name": "Joe Smith",
"streetLine1": "111 Bourke St",
"city": "Melbourne",
"stateCode": "VIC",
"postcode": "3000",
"countryCode": "AU"
}
}
Retrieves billing & shipping details for a customer that has previously initiated/executed a PayPal transaction.
HTTP Request
GET https://payments-stest.npe.auspost.zone/v2/wallets/paypal/orders/{orderId}?merchantCode={merchantCode}
Path Variables
Parameter | Description |
---|---|
orderId | A client order id, which is used as reference to the payment. |
Request Parameters
Parameter | Required | Description |
---|---|---|
merchantCode | Required |
Merchant account for which the funds are collected. |
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Response
Name | Description |
---|---|
orderId | The order id for the PayPal transaction. |
paymentId | The payment id which was issued by PayPal to initiate/execute the transaction. |
status | The transaction status for the order. Valid values are created , paid , failed ,unknown . Once transaction is initiated the status is set to created. If the payment was processed and succeeded the status is set to paid. If payment was processed but was declined the status is set to failed. If the request was processed with unexpected status from gateway the status is set to unknown |
amount | An integer value greater than 0, representing the total amount in cents. |
payerDetails | The PayPal Payer details associated with the PayPal transaction. |
shippingAddress | The PayPal Shipping Address associated with the PayPal transaction. |
PayPal Objects
PayPal Shipping Address Object
PayPal account owner shipping address returned as part of the response to a Retrieve PayPal order details request.
Name | Description |
---|---|
name | The name of the person associated with the shipping address. |
streetLine1 | The first line of the street address. |
streetLine2 | The second line of the street address (if there is one). |
city | The name of the city. |
stateCode | The name abbreviation of the state. Eg: (Victoria = VIC) |
postcode | The postal or zip code. |
countryCode | The code of the country. Eg: (Australia = AU) |
PayPal Payer Details Object
PayPal account owner details returned as part of the response to a Retrieve PayPal order details request.
Name | Description |
---|---|
firstName | The payer's first name. |
lastName | The payer's last name. |
The payer's email address. |
PayPal Provider Details Object
PayPal Provider details returned as part of the response to a Execute PayPal Transaction request.
Name | Description |
---|---|
reasonCode | Describes why the order status is inprogress . Possible values: CHARGEBACK , GUARANTEE , BUYER_COMPLAINT , REFUND , UNCONFIRMED_SHIPPING_ADDRESS , ECHECK , INTERNATIONAL_WITHDRAWAL , RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION , PAYMENT_REVIEW , REGULATORY_REVIEW , UNILATERAL , VERIFICATION_REQUIRED , TRANSACTION_APPROVED_AWAITING_FUNDING . |
Error Codes
PayPal endpoints uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
400 | INVALID_REQUEST_DATA -- Invalid request data |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for PayPal payments |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
400 | INVALID_ORDER_ID -- Order id has to be unique per merchant |
SecurePay API | Yes |
401 | UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
500 | PAYPAL_ERROR -- Error happened on PayPal end while processing request |
SecurePay API | Yes - talk to SecurePay API team |
3D Secure 2
Overview
3D Secure 2 (3DS2) is an additional layer of security that aids fraud prevention. 3DS2 is a protocol managed by EMVCo used to authenticate the identity of the person making the payment to ensure that they are the legitimate cardholder even before the payment is done.
This is done by providing the card issuer with a high volume of contextual data to aid in the decision on which authentication flow to be used. The card issuer checks whether the payment being requested is from the legitimate cardholder. This results to a more frictionless experience where customers are verified, and payment then proceeds. In cases where the issuer identifies that the transaction is high risk, they can prompt challenge questions for the customer to answer as an additional verification.
With SecurePay 3DS2 which currently supports protocol version 2.1.0, you will be able to authenticate before submitting payment authorisation requests. Depending on the result of authentication, merchants or issuers can bear responsibility during chargebacks when the payment authorised is found to be fraudulent and not authorised by the cardholder.
By utilising SecurePay’s 3DS2 Javascript, you will be able to send an authentication request for which you will receive the authentication result that includes the liability shift information. Depending on the authentication result, you will have the flexibility to decide whether to proceed or not with the payment authorisation.
SecurePay 3DS2 is supported for the following categories:
- Payment Types: Create Payment and PreAuth/InitialAuth
- Currencies: AUD
- Acquiring Bank with corresponding Card Types:
Acquiring Bank | Visa | Mastercard | Amex |
---|---|---|---|
NAB | ✓ | ✓ | |
Westpac | ✓ | ✓ | ✓ |
ANZ | ✓ | ✓ | |
CBA | ✓ | ✓ | ✓ |
Fiserv FDMSA | ✓ | ✓ | ✓ |
3DS2 Javascript SDK
How does it work?
3DS2 authentication should be done before a payment authorisation request is sent. Authentication can be accomplished by using the 3DS2 JavaScript SDK, following either of the two methods below:
Recommended method:
- Initiate a 3DS2 Payment Order.
- Load the SecurePay 3DS2 Javascript client library.
- Initialise the 3D Secure script and configure the callback methods required during the checkout page load.
- Trigger the 3DS2 Authentication process when ready (i.e. Payment or checkout commenced).
- Handle the authentication outcome.
Alternate method: This may increase in load time. Also, this can only be done once you have filled all the 3DS2 required fields.
- Initiate a 3DS2 Payment Order.
- Load the SecurePay 3DS2 Javascript client library.
- Initialise and trigger 3DS2 authentication together using the method
initAndStartThreeDS
. - Handle the authentication outcome.
Environment Details
Environment | SecurePay 3DS2 JavaScript SDK URL |
---|---|
Sandbox | https://test.api.securepay.com.au/threeds-js/securepay-threeds.js |
Live | https://api.securepay.com.au/threeds-js/securepay-threeds.js |
Initiate A 3DS2 Payment Order
Initiate a Payment order of order type THREED_SECURE
.
The following fields from the Initiate Payment Order response will be used for 3DS authentication process: orderToken
, threedSecureDetails.providerClientId
, threedSecureDetails.sessionId
and threedSecureDetails.simpleToken
Load SecurePay 3DS2 JavaScript SDK
The securepay-threeds.js
client library should be included in your HTML source as shown in the sample code:
Live Environment: <script th:id="sp-threeds-js" th:src="https://api.securepay.com.au/threeds-js/securepay-threeds.js" type="text/javascript"></script>
Sandbox Environment: <script th:id="sp-threeds-js" th:src="https://test.api.securepay.com.au/threeds-js/securepay-threeds.js" type="text/javascript"></script>
Initialise the 3D Secure JS
Add an iframe element for the Challenge Form
The 3DS2 will need a challenge window for some calls to get customer's input for the challenge. Hence create an element for this window to be published when required.
<iframe id="3ds-v2-challenge-iframe" name="3ds-v2-challenge-iframe" style="width: 500px; height: 500px; visibility:hidden;">
Once loaded, the script can be initialised with the following parameters.
var sp3dsConfig = {
clientId: providerClientId,
iframe: iframeElement,
token: orderToken,
simpleToken: simpleToken,
threeDSSessionId: sessionId,
onRequestInputData: onRequestInputDataCallback,
onThreeDSResultsResponse: onThreeDSResultsResponseCallback,
onThreeDSError: onThreeDSErrorCallback
};
var securePayThreedsUI = new window.SecurePayThreedsUI();
window.securePayThreedsUI = securePayThreedsUI;
securePayThreedsUI.initThreeDS(sp3dsConfig);
Parameter | Description |
---|---|
clientId | 3DS2 Client Id of the merchant. The value can be obtained from Initiate Payment order response, threedSecureDetails.providerClientId . |
iframe | The iframe element that can be used to display 3DS2 challenge form. Iframe element should be defined in checkout/payment page and passed into the Java Script during initialisation. For example: In Add an iframe element, value will be: document.getElementById(“3ds-v2-challenge-iframe”) |
token | An order token that was returned from Initiate Payment order response, orderToken |
simpleToken | A simple authentication token that was returned from Initiate Payment order response, threedSecureDetails.simpleToken |
threeDSSessionId | A unique session id (sessionId) that was returned from Initiate Payment order response. threedSecureDetails.sessionId |
onRequestInputData | See onRequestInputData callback section |
onThreeDSResultsResponse | See onThreeDSResultsResponse callback section |
onThreeDSError | See onThreeDSResultsResponse callback section |
- If any of the config objects are missing, error
VALIDATION_ERROR - missing mandatory config
will be received. - If the clientID provided is incorrect, error
INITIALISATION_ERROR - JavaScript initialisation error
will be received. - If invalid type of iframe is used, then
WRONG_CONFIG_TYPE_ERROR - config is not in expected format
will be received.
Configure the callbacks required for the script
onRequestInputData callback
onRequestInputData callback will collect relevant information from customer to be used in an 3DS2 Authentication request. onRequestInputData callback is executed prior to an HTTP request initiated by 3DS2 javascript. The callback should return an object with the following details.
{
"cardTokenInfo":{
"cardholderName":"John More Doe",
"cardToken":"6326270000000000"
},
"accountData":{
"emailAddress":"john.doe@test.com",
"mobilePhone":{
"cc":"+61",
"subscriber":"400000000"
},
"workPhone":{
"cc":"+61",
"subscriber":"400000000"
},
"homePhone":{
"cc":"+61",
"subscriber":"400000000"
}
},
"billingAddress":{
"city":"Suburb",
"state":"NSW",
"country":"AU",
"zipCode":"2000",
"streetAddress":"Unit 1",
"detailedStreetAddress":"123 Street Suburb",
"detailedStreetAddressAdditional":"123 Street Suburb"
},
"shippingAddress":{
"city":"Suburb",
"state":"NSW",
"country":"AU",
"zipCode":"2000",
"streetAddress":"Unit 1",
"detailedStreetAddress":"123 Street Suburb",
"detailedStreetAddressAdditional":"123 Street Suburb"
},
"merchantRiskData":{
"deliveryTimeframeType":"01",
"reOrderType":"01",
"shippingMethodType":"01"
},
"threeDSInfo":{
"threeDSReqAuthMethodInd":"02"
}
}
Parameter | Required | Description |
---|---|---|
cardTokenInfo | required | Card holder details associated with the issued card used for the purchase. See CardTokenInfo Object |
accountData | required | Additional Information related to the card holder. See AccountData Object |
billingAddress | required | Cardholder billing address associated with the card used for this purchase. See Address Object |
shippingAddress | optional | Shipping address requested by the Cardholder. See Address Object |
threeDSInfo | optional | Additional information associated with the Authentication request as required by different card schemes (e.g. visa, mastercard, diners, amex). Required for Visa Cards Only. Card scheme can be found in the onTokeniseSuccess callback response TokenisedCardSee ThreeDSInfo Object |
merchantRiskData | optional | The Merchant Risk Data contains optional information about the specific purchase by the Cardholder. Card scheme can be found in the onTokeniseSuccess callback response TokenisedCardSee MerchantRiskData Object |
CardTokenInfo Object
Parameter | Required | Type | Description |
---|---|---|---|
cardholderName | required | String | Name of the cardholder. Alphanumeric characters including blank space ' '. Minimum length of 2. Maximum length of 45. |
cardToken | required | String | A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information, which is then used to perform the transaction. |
AccountData Object
Parameter | Required | Type | Description |
---|---|---|---|
mobilePhone | optional | ContactNumber | The mobile phone number provided by the cardholder. |
workPhone | optional | ContactNumber | The work phone number provided by the cardholder |
homePhone | optional | ContactNumber | The home phone number provided by the cardholder |
emailAddress | required | String | The email address associated with the cardholder in string format. Max length of 254. |
ContactNumber Object
Parameter | Required | Type | Description |
---|---|---|---|
cc | required | String | Country code of the contact number. A prefix of '+' followed by 1 to 3 numeric country code. |
subscriber | required | Integer | Subscriber number. Maximum length of 15 numeric characters. Mandatory if cc is provided and should follow string length according to country code. |
Address Object
Parameter | Required | Type | Description |
---|---|---|---|
streetAddress | required | String | First Line of the street address. Maximum length of 50 characters. |
detailedStreetAddress | optional | String | Second line of the street address. Maximum length of 50 characters. |
detailedStreetAddressAdditional | optional | String | Third line of the street address. Maximum length of 50 characters. |
city | required | String | Name of the City. Maximum length of 50 characters. |
state | required | String | The state or province following ISO 3166-2. |
country | required | String | Country. Can contain the 3-digit numeric ISO code or the 2 or 3 alpha character ISO code. |
zipcode | required | String | ZIP or postal code. Maximum length of 16 characters. |
ThreeDSInfo Object
Parameter | Required | Type | Description |
---|---|---|---|
threeDSReqAuthMethodInd | required | String | Method used to authenticate the user with the client web application. Accepted Values:01 : No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)02 : Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials03 : Login to the cardholder account at the 3DS Requestor system using federated ID04 : Login to the cardholder account at the 3DS Requestor system using issuer credentials05 : Login to the cardholder account at the 3DS Requestor system using third-party authentication06 : Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator |
MerchantRiskData Object
Parameter | Required | Type | Description |
---|---|---|---|
deliveryTimeframeType | Optional | String | The merchandise delivery timeframe. Accepted values:01 : Electronic Delivery02 : Same day shipping03 : Overnight shipping04 : Two-day or more shipping |
reOrderType | Optional | String | Indicates whether the cardholder is reordering previously purchased merchandise. Accepted values:01 : First time ordered02 : Reordered |
shippingMethodType | Optional | String | Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. Accepted values: 01 : Ship to cardholder’s billing address02 : Ship to another verified address on file with merchant03 : Ship to address that is different than the cardholder’s billing address04 : “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)05 : Digital goods (includes online services, electronic gift cards and redemption codes)06 : Travel and Event tickets, not shipped07 : Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.) |
deliveryEmailAddress | conditional | String | For Electronic delivery, the email address to which the merchandise was delivered. Mandatory for Amex Card when shippingMethodType = 05 . Max length of 254. |
onThreeDSResultsResponse callback
The onThreeDSResultsResponse callback provides the outcome of the 3DS2 authentication process. When 3DS2 authentication process has finished, this callback provides a liability shift indicator and other supporting parameters.
Parameter | Type | Description |
---|---|---|
liabilityShiftIndicator | String | Liability Shift Indicator. This indicates whether the chargeback liability is shifted to the issuer Possible values: Y : Liability for relevant Chargeback reason codes is shifted to the issuer.N : Liability for relevant Chargeback reason codes Is not shifted to the issuer.Refer to Liability Shift Indicator Matrix for more information |
transStatus | String | Transaction Status. This value indicates whether a transaction qualifies as an authenticated transaction. It is received from the 3DS2 server and follows the EMVCo specification for 3DS2 data elements. |
transStatusReason | String | Transaction Status Reason. It provides additional information to support the transStatus. It is received from the 3DS2 server and follows the EMVCo specification for 3DS2 data elements. Refer to Transaction Status Reason Codes for more information. |
eci | String | E-Commerce Indicator/Security Level Indicator(SLI) This is a two-digit value returned by the Directory Server that indicates the result of the authentication. |
authenticationValue | String | Authentication Value. Also known as Cardholder Authentication Verification Value(CAVV). This is a value returned by the Issuer ACS that performed the authentication. |
cardDescription | String | Card Brand Description used during authentication. |
onThreeDSError callback
The onThreeDSError callback is used when there is a failure during the 3DS2 authentication process. Callback will be executed with a javascript array that contains one or more javascript objects, each object contains the following information. See Error codes for more information.
// Sample format for Error Object
[
{
id: 'b7e41d4f-0dc5-45ae-b5f3-c73f6e2943c9',
code: '180',
detail: 'Unable to perform 3DS Authentication'
}
]
Parameter | Type | Description |
---|---|---|
id | String | A unique error id which can be used for troubleshooting. |
code | Integer | An error code indicating the error |
detail | String | Error details. |
Trigger the 3DS2 Authentication
Once the script is initialised and all the callbacks configured correctly, the authentication process can be triggered. Example to Trigger 3DS2 authentication process
var spThreedsUI = window.securePayThreedsUI;
spThreedsUI.startThreeDS();
During this step, onRequestInputData callback will be used to collect necessary information to prepare an 3DS2 authentication request.
- If 3ds authentication process is triggered before the initialisation has completed, then error
GENERIC_THREEDS_START_ERROR - Failed to start Threeds Authentication
will be received.
Initialise and start 3DS
This is an alternate approach where we initialise and trigger the 3DS2 authentication in a single call. Please note that this call can only be done once we have all the callbacks configured correctly.
var sp3dsConfig = {
clientId: providerClientId,
iframe: iframeElement,
token: orderToken,
simpleToken: simpleToken,
threeDSSessionId: sessionId,
onRequestInputData: onRequestInputDataCallback,
onThreeDSResultsResponse: onThreeDSResultsResponseCallback,
onThreeDSError: onThreeDSErrorCallback
};
var securePayThreedsUI = new window.SecurePayThreedsUI();
window.securePayThreedsUI = securePayThreedsUI;
securePayThreedsUI.initAndStartThreeDS(sp3dsConfig);
Handle the Authentication Outcome
Once the 3DS2 authentication process has finished, a callback will be done via onThreeDSResultsResponse callback to notify the authentication outcome. This callback includes a Liability Shift Indicator and other supporting parameters.
If an error has occurred during the authentication process, a callback will be done via onThreeDSError callback.
Liability Shift Indicator
SecurePay receives eci (SLI)
and authentication value (CAVV)
from the 3D Secure server as part of the authentication process.
SecurePay uses the value of these parameters along with the card brand used during authentication to determine if the chargeback liability shifts to the issuer or stays with the merchant.
The shift indicates who will be responsible for relevant fraudulent chargebacks.
Along with the transStatus, transStatusReason, eci and authentication value, the Liability Shift Indicator is included in the response callback for merchant visibility as a guide, allowing the flexibility to decide whether to proceed with the payment or not.
Please note that the Liability Shift is applicable only to relevant fraud related chargebacks and is governed by individual scheme rules.
Liability Shift Indicator Matrix Object
Card Brand | Authentication Value Presence | eci | Trans Status | Authentication Result | Liability Shift Indicator |
---|---|---|---|---|---|
MasterCard | Yes | 02 | Y | Fully Authenticated | Y (Liability shifts to Issuer) |
MasterCard | Yes | 01 | A | Attempted Authentication | Y (Liability shifts to Issuer) |
MasterCard | No | 00 | N | Not Authenticated | N (Liability stays with Merchant) |
MasterCard | No | 00 | U | Unable to authenticate. | N (Liability stays with Merchant) |
MasterCard | No | 00 | R | Rejected | N (Liability stays with Merchant) |
MasterCard | Yes | 07 | Y | Fully Authenticated | Y (Liability shifts to Issuer) |
Visa | Yes | 05 | Y | Fully Authenticated | Y (Liability shifts to Issuer) |
Visa | Yes | 06 | A | Attempted Authentication | Y (Liability shifts to Issuer) |
Visa | No | 06 | A | Attempted Authentication | N (Liability stays with Merchant) |
Visa | No | 07 | N | Not Authenticated | N (Liability stays with Merchant) |
Visa | No | 07 | R | Rejected | N (Liability stays with Merchant) |
Visa | Yes | 07 | Y | Fully Authenticated | N (Liability stays with Merchant) |
Amex | Yes | 05 | Y | Fully Authenticated | Y (Liability shifts to Issuer) |
Amex | Yes | 06 | A | Attempted Authentication | Y (Liability shifts to Issuer) |
Amex | No | N | Not Authenticated | N (Liability stays with Merchant) | |
Amex | No | R | Rejected | N (Liability stays with Merchant) | |
Amex | No | 07 | U | Unable to authenticate. | N (Liability stays with Merchant) |
Transaction Status Reason Codes
Reason code | Detail | Description |
---|---|---|
01 | Card authentication failed | If this occurs multiple times for the same card, contact your Acquirer. |
02 | Unknown Device | The device the cardholder used for authentication is not the same as the registered device. The cardholder needs to use the same device. If this information is not known, then the cardholder will need to contact their card issuer. |
03 | Unsupported Device | The cardholder used a device that the ACS does not support e.g., unsupported OS, device not considered secure. |
04 | Exceeds authentication frequency limit | The maximum limit of authentications has been exceeded. Wait to try again or try a different card. If issue persists, then the cardholder will need to contact the card Issuer. |
05 | Expired card | Please check the expiry date of your card and try again. |
06 | Invalid card number | The card number is invalid. Please check and re-enter the details or try a different card. |
07 | Invalid transaction | There is an issue with the transaction. The cardholder will need to contact their card Issuer. |
08 | No Card record | The card does not support 3DS or is not enrolled in 3DS from the Issuer. Please try a different card. |
09 | Security failure | There is a security failure on this card. Please try a different card. |
10 | Stolen card | Records show that the card used has been flagged as stolen. The cardholder will need to contact their card Issuer. |
11 | Suspected fraud | Suspected fraudulent activity has been detected. The cardholder will need to contact their card Issuer. |
12 | Transaction not permitted to cardholder | This type of transaction is not permitted. The cardholder will need to contact their card Issuer. |
13 | Cardholder not enrolled in service | The card used is currently not enrolled for 3DS. |
14 | Transaction timed out at the ACS | An authentication response has not been received within a given time, please try again shortly. If the problem persists, the cardholder will need to contact their card issuer. |
15 | Low confidence | |
16 | Medium confidence | |
17 | High confidence | |
18 | Very High confidence | |
19 | Exceeds ACS maximum challenges | Number of failed challenges exceeded the maximum set by the ACS. Please wait and try again or try a different card. |
20 | Non-Payment transaction not supported | ACS does not allow/support payment transactions (if received on a PA - Payment transaction) OR ACS does not allow/support non-payment transactions (if received on a NPA - Non Payment transaction). |
21 | 3RI transaction not supported | ACS does not allow/support merchant-initiated transactions. |
22–79 | Reserved for EMVCo future use (values invalid until defined by EMVCo) | |
80–99 | Reserved for DS use |
Error Codes
Code | Detail | Originating System |
---|---|---|
104 | Invalid Merchant ID. The provided clientID is incorrect. |
SecurePay API |
151 | Invalid ISO Currency Code. | SecurePay API |
176 | Merchant Not Enrolled in 3D Secure. | SecurePay API |
180 | Unable to perform 3DS Authentication. Might be due to: Card brand used is not supported for 3DS2. Connection issue between 3DS server and Directory Server. Mandatory field is incorrectly provided. |
SecurePay API |
181 | Card Unsupported for 3D Secure. | SecurePay API |
182 | 3D Secure Configuration Error. Internal Error occurred preventing 3DS2 process to proceed. |
SecurePay API |
183 | Invalid value for <field> . |
SecurePay API |
504 | Unable to process the request. Invalid Token is used or Token is expired. |
SecurePay API |
515 | Unable to process your request. Timeout or internal connectivity errors. |
SecurePay API |
517 | Acquirer not configured for 3DS2 for used card type. | SecurePay API |
517 | Liability Shift indicator error. | SecurePay API |
517 | Unexpected value for <field> . |
SecurePay API |
517 | <field> must not be Null. |
SecurePay API |
517 | Order not in valid state. | SecurePay API |
517 | Order intent used is invalid. | SecurePay API |
517 | Invalid or Duplicate Request. | SecurePay API |
517 | Invalid Origin. | SecurePay API |
3DS2 Testing
Full testing scenarios and information can be found here: Card Testing 3DS2
Fraud detection - FraudGuard
Overview
Fraud detection - FraudGuard is a tool for transaction fraud detection and prevention. Developed by SecurePay, this tool reduces your exposure to fraudulent transactions by detecting fraud before it occurs. You can customise your fraud settings by establishing your own rules within a points system, so you’re always in control.
The Fraud Detection API performs a fraud check, and returns back its fraud risk assessment. Based on this assessment, you are able to decide on whether to go ahead with the transaction (by using the Payment API), or to stop the order from proceeding. You enjoy this flexibility with our fraud solution.
Rest API
Perform Fraud Detection
Performs fraud detection, given the following details.
To do fraud detection, use this code:
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
curl https://payments-stest.npe.auspost.zone/v2/antifraud/check -X POST
-H "Content-Type: application/json"
-H "Authorisation: Bearer xxxxxxxx"
-d '{ "fraudCheckType": "FRAUD_GUARD",
"ip": "127.0.0.1",
"merchantCode": "YOUR_MERCHANT_CODE",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"paymentDetails": {
"amount": 10000,
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"paymentMethod": "PAYMENT_CARD"
}
}'
{
"orderId": "17df5bdb-f17a-48d7-99f9-ff2d9660db97",
"fraudCheckType": "FRAUD_GUARD",
"fraudCheckResult": {
"providerReferenceNumber": "0bde9e63-d41a-4e4a-be7f-3949411f1f2e",
"score": 0,
"providerResponseMessage": "Fraud check passed"
}
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 . |
orderId | String | Optional |
A client order id, which will be used as reference to fraud check. If not provided, SecurePay API will assign a unique id for the order. |
merchantCode | String | Required |
Merchant account code for which fraud check is performed. |
fraudCheckType | String | Required |
This parameter defines which type of fraud check is used. Supported type is FRAUD_GUARD . |
paymentDetails | Object | Required |
The Payment Details Object. |
customerDetails | Object | Optional |
The Customer Details Object. |
shippingAddress | Object | Optional |
The Shipping Address Object. |
billingAddress | Object | Optional |
The Billing Address Object. |
customerCode | String | Optional |
A unique (within your organisation) identifier of your customer. This is used when you want to perform a fraud request against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Response
Name | Type | Description |
---|---|---|
orderId | String | A client order id, which will used as reference to fraud check. |
fraudCheckType | String | Returns type of fraud check performed. Values could be FRAUD_GUARD . |
fraudCheckResult | Object | Fraud check result. Refer to Fraud Check Result for more details. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
Fraud Objects
Payment Details Object
Payment details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description |
---|---|---|---|
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. |
paymentMethod | String | Required |
The payment method used by the customer. Supported value is PAYMENT_CARD . |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information for paymentMethod PAYMENT_CARD . |
Customer Details Object
Customer details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
emailAddress | String | Optional |
Customer email | Should contain @ character and at least one preceding and following character, up to 60 characters |
Shipping Address Object
Customer shipping address details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
firstName | String | Optional |
Customer shipping first name | Should not be longer than 30 characters |
lastName | String | Optional |
Customer shipping last name | Should not be longer than 30 characters |
city | String | Optional |
Customer shipping city | Should not be longer than 20 characters |
postcode | String | Optional |
Customer shipping postcode | Should not be longer than 4 characters |
countryCode | String | Optional |
Customer shipping country code | 3 characters long country code in ISO 3166-1 |
Billing Address Object
Customer billing address details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
countryCode | String | Optional |
Customer billing country code | 3 characters long country code in ISO 3166-1 |
Fraud Check Result Object
Detailed part of the response to a Perform Fraud Detection request.
Name | Type | Description |
---|---|---|
providerReferenceNumber | String | The fraud check reference number. |
score | Integer | The result of the fraud check. |
providerResponseMessage | String | This field contains details of the result. |
Fraud Error Codes
Fraud endpoint uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Send malformed JSON in request |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account is not configured for fraud check type provided in request |
Payment Gateway | No |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
500 | FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway |
Payment Gateway | No |
Fraud detection - ACI ReD Shield
Overview
Fraud detection – ACI ReD Shield is another tool for transaction fraud detection and prevention. This tool is provided by a third party, ACI Worldwide.
The Fraud Detection API performs a fraud check, and returns back its fraud risk assessment. Based on this assessment, you are able to decide on whether to go ahead with the transaction (by using the Payment API), or to stop the order from proceeding. You enjoy this flexibility with our fraud solution.
Fraud Javascript SDK
Fraud integration JS SDK integration:
<script>
var io_install_flash = false;
var io_install_stm = false;
</script>
<script type="text/javascript" src="https://mpsnare.iesnare.com/snare.js"></script>
<script>
function io_bb_callback(bb, complete) {
console.log("Blackbox: " + bb,complete);
}
</script>
The fraud detection with ACI ReD endpoint requires device fingerprint field to be included as part of the customer-object. The device fingerprint generation and validation is provided by Iovation ReputationManager 360 (Iovation Javascript SDK).
The snare.js script should be included in your HTML source as shown in the sample code:
The callback function "io_bb_callback" will be called with two arguments.
- bb: blackbox (The device fingerprint)
- complete : true/false flag to denote the process completion.
See the Iovation Integration Guide for more info:
Rest API
Perform Fraud Detection
Performs fraud detection, given the following details.
To do fraud detection, use this code:
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
curl https://payments-stest.npe.auspost.zone/v2/antifraud/check -X POST
-H "Content-Type: application/json"
-H "Authorisation: Bearer xxxxxxxx"
-d '{ "fraudCheckType": "ACI_FRAUD_CHECK",
"ip": "127.0.0.1",
"merchantCode": "YOUR_MERCHANT_CODE",
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"paymentDetails": {
"amount": 10000,
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"paymentMethod": "PAYMENT_CARD"
}
}'
{
"orderId": "0475f32d-fc23-4c02-b19b-9fe4b0a848ac",
"fraudCheckType": "ACI_FRAUD_CHECK",
"fraudCheckResult": {
"providerReferenceNumber": "70113",
"result": "PASSED",
"providerResponseMessage": "Transaction accepted"
}
}
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/antifraud/check
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 . |
orderId | String | Optional |
A client order id, which will be used as reference to fraud check. If not provided, SecurePay API will assign a unique id for the order. |
merchantCode | String | Required |
Merchant account code for which fraud check is performed. |
fraudCheckType | String | Required |
This parameter defines which type of fraud check is used. Supported type is ACI_FRAUD_CHECK . |
paymentDetails | Object | Required |
The Payment Details Object. |
merchantWebsite | String | Optional |
Merchant website url. |
productDetails | Object | Optional |
The list of Product Details Objects. |
customerDetails | Object | Optional |
The Customer Details Object. |
shippingAddress | Object | Optional |
The Shipping Address Object. |
billingAddress | Object | Optional |
The Billing Address Object. |
customFields | Object | Optional |
The Custom fields Object. |
customerCode | String | Optional |
A unique (within your organisation) identifier of your customer. This is used when you want to perform a fraud request against a stored payment instrument. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
Response
Name | Type | Description |
---|---|---|
orderId | String | A client order id, which will used as reference to fraud check. |
fraudCheckType | String | Returns type of fraud check performed. Values could be ACI_FRAUD_CHECK . |
fraudCheckResult | String | Fraud check result. Refer to Fraud Check Result for more details. |
customerCode | String | The identifier for the customer. In case of anonymous payment it is always anonymous . |
Fraud Objects
Payment Details Object
Payment details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description |
---|---|---|---|
amount | Integer | Required |
An integer value greater than 0, representing the total amount in cents to charge the provided (tokenised) payment instrument. |
paymentMethod | String | Required |
The payment method used by the customer. Supported value is PAYMENT_CARD . |
token | String | Required |
A tokenised payment instrument reference. This value is used by the payment gateway to retrieve the actual card information for paymentMethod PAYMENT_CARD . |
Product Details Object
Product details to include as part of a Perform Fraud Detection request. Product details should be passed as a list of Product details objects.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
sku | String | Optional |
Product identifier | Should not be longer than 12 characters |
itemQuantity | Integer | Optional |
Product quantity | An integer value greater than 0 and up to 12 digits long. |
itemDescription | String | Optional |
Product description | Should not be longer than 127 characters |
itemUnitPrice | Integer | Optional |
Product unit price | An integer value greater than 0 and up to 12 digits long, representing the unit price in cents. |
itemPartNumber | String | Optional |
Product part number | Should not be longer than 30 characters |
itemShippingComment | String | Optional |
Product shipping comment | Should not be longer than 160 characters |
itemGiftMessage | String | Optional |
Product gift message | Should not be longer than 160 characters |
Customer Details Object
Customer details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
emailAddress | String | Optional |
Customer email | Should contain @ character and at least one preceding and following character, up to 60 characters |
phoneNumber | String | Optional |
Customer phone number | Should contain digits only, up to 19 digits |
deviceFingerprint | String | Optional |
Customer device fingerprint - Refer to fraud_integration to get this field | Should contain less than or equal to 6000 characters |
Shipping Address Object
Customer shipping address details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
firstName | String | Optional |
Customer shipping first name | Should not be longer than 30 characters |
lastName | String | Optional |
Customer shipping last name | Should not be longer than 30 characters |
streetLine1 | String | Optional |
Customer shipping street name | Should not be longer than 30 characters |
streetLine2 | String | Optional |
Customer shipping street name | Should not be longer than 30 characters |
city | String | Optional |
Customer shipping city | Should not be longer than 20 characters |
postcode | String | Optional |
Customer shipping postcode | Should not be longer than 4 characters |
stateCode | String | Optional |
Customer shipping state code | Should not be longer than 10 characters |
countryCode | String | Optional |
Customer shipping country code | 3 characters long country code in ISO 3166-1 |
Billing Address Object
Customer billing address details to include as part of a Perform Fraud Detection request.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
firstName | String | Optional |
Customer billing first name | Should not be longer than 30 characters |
lastName | String | Optional |
Customer billing last name | Should not be longer than 30 characters |
streetLine1 | String | Optional |
Customer billing street name | Should not be longer than 30 characters |
streetLine2 | String | Optional |
Customer billing street name | Should not be longer than 30 characters |
city | String | Optional |
Customer billing city | Should not be longer than 20 characters |
postcode | String | Optional |
Customer billing postcode | Should not be longer than 4 characters |
stateCode | String | Optional |
Customer billing state code | Should not be longer than 10 characters |
countryCode | String | Optional |
Customer billing country code | 3 characters long country code in ISO 3166-1 |
Custom Fields Object
Custom fields to include as part of a Perform Fraud Detection request.
If fraud check provider has capability to allow merchant to configure custom rules, merchant can use Custom Fields.
Once custom rules are configured on fraud provider portal (e.g. ACI Fraud Check), merchant could use the Custom Fields to trigger specific rules.
At the moment custom rules are supported only for ACI_FRAUD_CHECK
.
Name | Type | Required | Description | Validation rule |
---|---|---|---|---|
customField1 | String | Optional |
Custom fraud check rules | Should not be longer than 256 characters |
customField2 | String | Optional |
Custom fraud check rules | Should not be longer than 256 characters |
customField3 | String | Optional |
Custom fraud check rules | Should not be longer than 256 characters |
customField4 | String | Optional |
Custom fraud check rules | Should not be longer than 256 characters |
customField5 | String | Optional |
Custom fraud check rules | Should not be longer than 256 characters |
Fraud Check Result Object
Detailed part of the response to a Perform Fraud Detection request.
Name | Type | Description |
---|---|---|
providerReferenceNumber | String | The fraud check reference number. |
result | String | The result of the fraud check. Valid values are PASSED , SUSPECTED or BLOCKED . |
providerResponseMessage | String | This field contains details of the result. |
Fraud Error Codes
Fraud endpoint uses the following error codes:
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Send malformed JSON in request |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
500 | FRAUD_CHECK_ERROR -- Error while doing fraud check from Payment Gateway |
Payment Gateway | No |
Scheduled Payments
Overview
Scheduling API provide merchant capability to create once off payment on specified date or recurring payments. Note, that a card token needs to be stored against customer through Create payment instrument endpoint prior of creating a schedule. The period of recurring payments could be custom day interval or calendar intervals such as weekly, fortnightly, monthly, quarterly, half yearly or annually.
Rest API
Create a once off payment on specified date
To create a once off payment on specified date:
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{
"ip": "127.0.0.1",
"referenceNumber": "Invoice 123",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "YOUR_CUSTOMER_CODE",
"amount": 10000,
"payDate": "2019-12-03"
}'
{
"ip": "127.0.0.1",
"scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4",
"referenceNumber": "Invoice 123",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "YOUR_CUSTOMER_CODE",
"amount": 10000,
"payDate": "2019-12-03"
}
Creates once off payment on specified date in the future.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/once-off
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
referenceNumber | String | Required |
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. Should not be longer than 30 characters. |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
customerCode | String | Required |
A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
amount | Number | Required |
An integer value greater than 0, representing the amount in cents. |
token | String | Required |
A tokenised payment instrument reference. |
payDate | String | Required |
The date in ISO 8601 format when the payment should be made, for example 2020-01-13. Should be not earlier than the next day. |
Response
Name | Type | Description |
---|---|---|
ip | String | Client IP address. |
scheduleId | String | A unique schedule id, will be used as reference to the schedule. |
referenceNumber | String | A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. |
merchantCode | String | Merchant account for which the funds are collected. |
customerCode | String | A unique (within your organisation) identifier of your customer. |
amount | Number | An integer value greater than 0, representing the amount in cents. |
token | String | A tokenised payment instrument reference. |
payDate | String | The date in ISO 8601 format when the payment should be made, for example 2020-01-13. |
Create a payment schedule
To create a recurring scheduled payment:
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{
"ip": "127.0.0.1",
"referenceNumber": "Invoice 123",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "YOUR_CUSTOMER_CODE",
"amount": 1000,
"recurringTransaction": true,
"scheduleDetails": {
"paymentIntervalType": "DAILY_INTERVAL",
"intervalLength": 10,
"startDate": "2019-12-03",
"endDate": "2020-04-23"
}
}'
{
"ip": "127.0.0.1",
"scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4",
"referenceNumber": "Invoice 123",
"token": "de305d54-75b4-431b-adb2-eb6b9e546014",
"merchantCode": "YOUR_MERCHANT_CODE",
"customerCode": "YOUR_CUSTOMER_CODE",
"amount": 10000,
"recurringTransaction": true,
"scheduleDetails": {
"paymentIntervalType": "DAILY_INTERVAL",
"intervalLength": 10,
"startDate": "2019-12-03",
"endDate": "2020-04-23",
"lastPaymentDate": "2020-04-21"
}
}
Creates a payment schedule.
HTTP Request
POST https://payments-stest.npe.auspost.zone/v2/payments/schedules/recurring
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
referenceNumber | String | Required |
A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. Should not be longer than 30 characters. |
merchantCode | String | Required |
Merchant account for which the funds are collected. |
customerCode | String | Required |
A unique (within your organisation) identifier of your customer. Please note anonymous is a reserved keyword and must not be used. Should not be longer than 30 characters including - alphanumeric and _ |
amount | Number | Required |
An integer value greater than 0, representing the amount in cents. |
token | String | Required |
A tokenised payment instrument reference. |
recurringTransaction | Boolean | Required |
Whether a Merchant has agreement with a Cardholder, whereby the Cardholder authorizes the Merchant to store and use the Cardholder's credit card data periodically and on an ongoing basis. For a recurring payment transaction expiry date and CVV in most cases are ignored by the bank. |
scheduleDetails | Object | Required |
A schedule details request object. |
Response
Name | Type | Description |
---|---|---|
ip | String | Client IP address. |
scheduleId | String | A unique schedule id, will be used as reference to the schedule. |
referenceNumber | String | A transaction identifier. This value will appear against all processed transactions. Typically an invoice number. |
merchantCode | String | Merchant account for which the funds are collected. |
customerCode | String | A unique (within your organisation) identifier of your customer. |
amount | Number | An integer value greater than 0, representing the amount in cents. |
token | String | A tokenised payment instrument reference. |
recurringTransaction | Boolean | Whether a Merchant has agreement with a Cardholder, whereby the Cardholder authorizes the Merchant to store and use the Cardholder's credit card data periodically and on an ongoing basis. For a recurring payment transaction expiry date and CVV in most cases are ignored by the bank. |
scheduleDetails | Object | A schedule details response object. |
Delete a payment schedule or a once off payment on specified date
To delete a payment schedule or a once off payment on specified date:
DELETE https://payments-stest.npe.auspost.zone/v2/payments/schedules/559d4616-ff9c-4ce2-ad6f-93983ff69ee4
curl https://payments-stest.npe.auspost.zone/v2/payments/schedules/559d4616-ff9c-4ce2-ad6f-93983ff69ee4 -X DELETE
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx"
-d '{
"ip": "127.0.0.1",
"merchantCode": "YOUR_MERCHANT_CODE"
}'
{
"ip": "127.0.0.1",
"merchantCode": "YOUR_MERCHANT_CODE",
"scheduleId": "559d4616-ff9c-4ce2-ad6f-93983ff69ee4"
}
Deletes an existing payment schedule or a once off payment on specified date in the future. Use scheduleId value returned by Create a payment schedule endpoint or Create a once off payment on specified date endpoint.
HTTP Request
DELETE https://payments-stest.npe.auspost.zone/v2/payments/schedules/{scheduleId}
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
Content-Type | Required |
Should be set to application/json . |
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ip | String | Required |
A customer IP address. Must be a valid IPv4 or IPv6 . |
scheduleId | String | Required |
A unique schedule id returned by Create a payment schedule endpoint or Create a once off payment on specified date endpoint. |
Response
Name | Type | Description |
---|---|---|
ip | String | Client IP address. |
scheduleId | String | The schedule id that has been deleted. |
merchantCode | String | Merchant account for which the funds are collected. |
Scheduling Objects
Schedule Details Object Request
Schedule details to include as part of a Create schedule request.
Name | Type | Required | Description |
---|---|---|---|
paymentIntervalType | String | Required |
Type of scheduling, possible values are DAILY_INTERVAL , WEEKLY , FORTNIGHTLY , MONTHLY , QUARTERLY , HALF_YEARLY , ANNUALLY . If schedulingType is set to DAILY_INTERVAL , a length in days should be provided in intervalLength field. |
intervalLength | Number | Conditional |
Required when schedulingType is DAILY_INTERVAL , specifies the number of days between payments. Must be positive number. |
startDate | String | Required |
The date in ISO 8601 format when the first payment should be made, for example 2020-01-13. Should be not earlier than the next day. |
endDate | String | Optional |
The date in ISO 8601 format when the last payment should be made, for example 2020-04-13. Should be later than startDate field. If the endDate is not specified, payments will occur indefinitely until schedule is deleted. |
Schedule Details Object Response
Schedule details in Create schedule response.
Name | Type | Required | Description |
---|---|---|---|
paymentIntervalType | String | Required |
Type of scheduling, possible values are DAILY_INTERVAL , WEEKLY , FORTNIGHTLY , MONTHLY , QUARTERLY , HALF_YEARLY , ANNUALLY . If schedulingType is set to DAILY_INTERVAL , a length in days should be provided in intervalLength field. |
intervalLength | Number | Conditional |
Required when paymentIntervalType is DAILY_INTERVAL , specifies length of scheduling interval. Must be positive number. |
startDate | String | Required |
The date in ISO 8601 format when the first payment should be made, for example 2020-01-13. Should be not earlier than the next day. |
endDate | String | Optional |
The date in ISO 8601 format when the last payment should be made, for example 2020-04-13. Should be later than startDate field. If the endDate is not specified, payments will occur indefinitely until schedule is deleted. |
lastPaymentDate | String | Conditional |
If endDate if provided in create schedule request, lastPaymentDate will provide actual last payment date based on startDate and paymentIntervalType provided, could be differ from endDate provided in request. |
Error Codes
Response Code | Error Code | Originating System | Testable |
---|---|---|---|
400 | BAD_REQUEST -- Bad request data |
SecurePay API | Yes |
400 | INVALID_REQUEST_DATA -- Invalid request data |
SecurePay API | Yes |
400 | INVALID_ACCOUNT -- Account has not been configured for credit card payments |
SecurePay API | Yes |
400 | INVALID_IP_ADDRESS -- Invalid IP address |
SecurePay API | Yes |
401 | UNAUTHORIZED -- Provided invalid Auth Credentials. Bearer Access Token. Refer to client credentials for more information on obtaining an access token. |
SecurePay API | Yes |
500 | SYSTEM_ERROR -- Error happened in SecurePay API while processing request |
SecurePay API | Yes |
500 | GATEWAY_ERROR -- Error from Payment Gateway |
Payment Gateway | No |
504 | TIMED_OUT -- Payment Gateway took too long to respond |
Payment Gateway | No |
Errors
Overview
{
"errors": [
{
"id": "1a909ec1-c96c-4ced-a471-d145a0e517ef",
"code": "MIN_CONSTRAINT_VIOLATION",
"detail": "must be greater than or equal to 1",
"source": {
"pointer": "amount"
}
}
]
}
In case of an error from SecurePay API, the following response is returned.
Response
Name | Required | Description | Type |
---|---|---|---|
errors | Yes |
List of error objects | Error |
Error
Name | Required | Description |
---|---|---|
id | Yes |
Unique identifier for the error |
code | Yes |
Endpoint specific error code |
detail | Yes |
Detailed error description |
source.pointer | No |
If error is related to specific field in request, this param will be populated with the field name |
Other Integration methods
Overview
SecurePay offers other integration methods to accept payments through your website or handle bill payments. To find out more about services or obtain credentials to use these services, contact the team here.
Integration guides
e-Commerce extensions
Overview
SecurePay offer a smooth integration with the most popular e-Commerce extensions, and we maintain the latest selection.
eCommerce compatibility of payment features
Magento | WooCommerce | PrestaShop | Opencart | |
---|---|---|---|---|
Card Payments / Refunds | ✓ | ✓ | ✓ | ✓ |
Apple Pay | ✓ | ✓ | ||
Fraudguard | ✓ | ✓ | ||
Dynamic Currency Conversion | ✓ | ✓ | ||
3DS2 | ✓ | ✓ |
Magento
See compatibility of e-Commerce extensions in overview here
SecurePay API Magento Install Instructions
This guide outlines the download and install instructions for the SecurePay API Magento extension.
The current version of the SecurePay API Magento extension is 2.0.1
Latest version |
Version 2.0.1, 20th June 2023
|
Version history |
For previous versions please refer changelog.txt |
Part 1 - Download the extension
Download the extension to get started:
Part 2 - Install the extension
Upload the extension file to the Magento2_root/app/code folder of your Magento installation using FTP, SFTP or SSH - depending on your server setup
Unzip the extension
Connect into php the server (via SSH) and execute the following commands:
bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:clean
php bin/magento cache:flush
Part 3 - Configure the SecurePay extension
Enable and configure SecurePay API in Magento Admin under
Stores > Configuration > Sales -> Payment Methods > SecurePay Payment
Find the SecurePay API payment method and open to view the configuration options
Edit options where required
Clear Magento cache
OpenCart
See compatibility of e-Commerce extensions in overview here
SecurePay API OpenCart Install Instructions
This guide outlines the download and install instructions for the SecurePay API OpenCart extension.
The current version of the SecurePay API OpenCart extension is 1.3.0
Latest version |
Version 1.3.0, 4th August 2022
|
Part 1 - Download the extension
Download the extension to get started:
Part 2 - Install the extension
Login to your OpenCart admin interface
Navigate to
Extensions > Installer
Click on the button
Browse your computer to find the downloaded extension (with .ocmod.zip extension), and upload the extension
Navigate to
Extensions > Modifications
Click on the button
Part 3 - Configure the SecurePay extension
Navigate to
Extensions > Extensions
Select
Payments
inChoose the extension type
dropdownClick the
Plus
sign on the right of SecurePay Payment method to enable itAfter the payment method has been enabled, click the
Pen
button to open the configuration options. Fill the form with required information and click theSave
button on the top right.
WooCommerce
See compatibility of e-Commerce extensions in overview here
SecurePay API WooCommerce Install Instructions
This guide outlines the download and install instructions for the SecurePay API WooCommerce extension.
The current version of the SecurePay API WooCommerce extension is 2.0.3
Latest version |
Version 2.0.3, 25th July 2023
|
Version history |
For previous versions please refer changelog.txt |
Part 1 - Download the extension
Download the extension to get started:
Part 2 - Install the extension
Login to your Wordpress admin interface
Navigate to
Plugins > Add New
Click on the
Upload Plugin
button at the top of the pageBrowse your computer to find the downloaded extension, and upload the extension
Click the
Activate
button to activate the extension
Part 3 - Configure the SecurePay extension
Click on
WooCommerce > Settings
then click on thePayments
tabFind the SecurePay API payment method and click on the
Manage
button to open the configuration optionsEdit options where required and save
PrestaShop
See compatibility of e-Commerce extensions in overview here
SecurePay API PrestaShop Install Instructions
This guide outlines the download and install instructions for the SecurePay API PrestaShop extension.
The current version of the SecurePay API PrestaShop extension is 1.4.0
Latest version |
Version 1.4.0, 4th August 2022
|
Part 1 - Download the extension
Download the extension to get started:
Part 2 - Install the extension
Login to your PrestaShop admin interface
Navigate to
Modules > Module manager
Click on the
Upload a module
button at the top of the pageBrowse your computer to find the downloaded extension, and upload the extension
Part 3 - Configure the SecurePay extension
Click on
Modules > Module manager
Find the SecurePay API payment method and click on the
Configure
button to open the configuration optionsEdit options where required and save
Troubleshooting Guide
This troubleshooting guide provides information regarding common issues and mistakes with regard to merchant's Apple Pay setup, payment token expired or incorrect input format. It also provides information about fixes, knowledge bases, and support for those issues.
List of supported issues
Apple Pay Domain Verification Failed
Possible cause and solution:
file hosted on your domain is not correct or not accessible over internet as Apple needs to access the file for verification purpose.
Path to the file is not correct according to the guidelines, please follow the instructions
here
for Apple Pay Account setup. Expected URL for Domain Verification file ishttps://{domain-name}/.well-known/apple-developer-merchantid-domain-association
.
Mismatch in Amount being settled
Possible cause and solution:
- Amount sent in request is not in the expected format.
If you are sending $1.00, the amount value should be 100. Do not send float values (1.00 will be treated as 1 cent).
Please refer please follow the instructions
here
for expected input formats.
Support
Contact Us
Our support email address is support@securepay.com.au
System status
GET https://payments-stest.npe.auspost.zone/v2/health
curl https://api.payments-stest.npe.auspost.zone/v2/health -X GET
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxxx
{
"status": "UP"
}
To check the system / health status of the SecurePay API, make the following request.
HTTP Request
GET https://payments-stest.npe.auspost.zone/v2/health
Header Parameters
Parameter | Required | Description |
---|---|---|
Authorization | Required |
Refer to client credentials for more information on obtaining an access token. |
Response
Name | Description |
---|---|
status | The health status of SecurePay API. Status could be UP or DOWN. |