Introduction

If you do not already an account with Merchant Warrior, first you will need to sign up for our services.

Once your account has been set up, navigate to Barracks and select Settings from the lefthand navigation menu. Near the top of this page there's a section labelled "Direct API" under "Merchant Settings". This contains three key pieces of information you will need to utilize Merchant Warrior services.

  1. Your Merchant UUID and API Key. These are two identifiers we use to check that a request is coming from you, and are included as parameters in most API requests.
  2. Your API Passphrase. This is the final primary aspect of identity verification and must be kept hidden from the public. If you believe your passphrase may have been compromised, we recommend that you change it as soon as possible.
Requests

API requests are submitted to Merchant Warrior API services using POST, and must be performed over HTTPS. These POST requests will be directed at https://api.merchantwarrior.com/[endpoint]/, where [endpoint] is detailed in the introduction to each API section. Requests made as part of sandbox testing, https://base.merchantwarrior.com/[endpoint]/ is used instead.

If you would prefer to submit JSON requests and receive JSON responses you will need to submit two additional headers with your requests:

  • MW-API-VERSION: 2.0
  • Content-Type: application/json
Hash Generation

Verification hashes are used to prove to MW that the request(s) being sent have been generated by you, and not a malicious third party who may have discovered your merchantUUID and apiKey. Even if a malicious third party was to discover the request data you have sent, they would not be able to create requests without knowing your API Passphrase. Your API Passphrase can be modified in the MW administration interface.

Hash Generator

Responses

Responses will be received in XML or JSON formatting (depending on if the JSON headers have been sent)

<?xml version="1.0" encoding="UTF-8"?>
<mwResponse>
    <responseCode>0</responseCode>
    <responseMessage>...</responseMessage>
   ...
</mwResponse>
{
"responseCode":0,
"responseMessage":"...",
...
}

Details about the specific contents of each response can be found with the corresponding method in this documentation.

Response Codes

There are three possible types of responseCode.

If the responseCode is >= 0, the responseMessage field will either contain a preset error or, if applicable, the direct error response given by the provider or MW Vault.

responseCode Meaning
< 0 MW validation error
= 0 Transaction/Operation was successful
> 0 Transaction/Operation was declined or delayed by the provider or service

Response Messages

All MW validation errors will contain a three-digit code prefix at the beginning of the responseMessage. This code will allow you to determine what specifically caused the MWE validation error to be returned, and allow you to deal with it accordingly.

responseCode Prefix Description
-3 001 Required field missing
-2 002 Invalid amount
-2 003 Invalid currency
-2 004 Invalid email
-2 005 Invalid name
-2 006 Invalid expiry
-2 007 Invalid card number
-1 008 Invalid auth details
-1 009 Invalid merchantUUID
-1 010 Invalid passphrase
-2 011 Invalid transactionID
-2 012 Invalid transaction
-2 013 Currency mismatch
-2 014 Invalid refund amount
-2 015 Refund exceeds transaction amount
-2 016 Transaction already reversed
-2 017 Invalid verification hash

View Responses

Sandbox Testing

Sandbox testing requests are made to https://base.merchantwarrior.com/[endpoint]/, where [endpoint] is described in the introduction to each API section.

The test cards below are the only valid card numbers that can be used for testing with CBA, ANZ, NAB, Bendigo & BankWest

Card Number Card Security Code Brand
5456789012345670 123 MasterCard
2223000000000007 123 MasterCard Series 2
4123456789012349 123 Visa
371449635311038 1234 American Express
30123400000000 123 Diners Club
3528000000000007 N/A JCB

Changing the expiry date in your request will change the transaction response. Below are a list of expiries with their response descriptions.

Expiry Date Description
10/24 Transaction approved
01/24 Refer Card Issuer
04/24 Pick Up Card
05/24 Do Not Honour
02/25 Invalid Transaction
04/25 Invalid Card Number
05/25 No Such Issuer
05/27 Card Acceptor Contact Acquirer
01/28 Lost Card
02/28 No Universal Account/Closed Account
03/28 Stolen Card
01/29 Insufficient Funds
04/29 Invalid Expiry Date
02/30 Restricted Card
08/30 Transaction Timed Out/Response Received Too Late
01/33 Card Issuer Unavailable
02/33 Transaction Cannot Be Completed

Any other expiry used will result in an Approved transaction response.

The test cards below are only valid card numbers that can be used for testing with Westpac, St. George & Bank of Melbourne .

Card Number Expiry Date CVN Description
4564710000000004 02/29 847 Visa Approved
5163200000000008 08/30 070 MC Approved
4564710000000012 02/25 963 Visa Expired
4564710000000020 05/30 234 Visa Low Funds ($10 credit limit)
5163200000000016 12/29 728 MC Stolen
4564720000000037 09/29 030 Visa Invalid CVV2
376000000000006 06/30 2349 Amex
343400000000016 01/29 9023 Amex Restricted
36430000000007 06/22 348 Diners
36430000000015 08/21 988 Diners Stolen
All Others N/A N/A All unknown cards are rejected with 42 - No Universal Account