Introduction

If you do not already have 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/32 348 Diners
36430000000015 08/31 988 Diners Stolen
All Others N/A N/A All unknown cards are rejected with 42 - No Universal Account
Simulator

Merchant Warrior has developed a simulation engine to enable your testing to be as comprehensive as possible. Please use these cards if you have been told that you are connected to the MW Simulator. The cards listed here will only work in the sandbox environment, and will not function in production.

These cards will all give the specified response. Any card name, expiry and CVN can be used with these cards, as long as they are valid for the card. eg. Amex cards must have a 4 digit CVN, all other cards must have 3 digits, and the expiry needs to be in the future.

00 - Approved

Card Type Card Number
Visa 4111111111111111
Mastercard 5204740000001002
Mastercard 2223000000000007
Amex 377852136856480
Diners 3027285593502909
Discover 6011868764043133
JCB 3530111333300000

06 - Error

Card Type Card Number
Visa 4293189100000008
Mastercard 5163200000000008
Amex 377852884860965
Diners 3811683979228075
JCB 3562350000000003
Discover 6452418944930969

01 - Refer Card Issuer

Card Type Card Number
Visa 4123456789012349
Mastercard 5200000009915957
Amex 379936619672205
Diners 3001211836236774
JCB 6444744652558994
Discover 6444744652558994

04 - Pick Up Card

Card Type Card Number
Visa 4564710000000012
Mastercard 5531934095646789
Amex 377850264429575
Diners 3032297652537935
JCB 3566000020000410
Discover 6557364173679717

05 - Do Not Honour

Card Type Card Number
Visa 4564710000000020
Mastercard 5188680400000008
Amex 377852393955355
Diners 3627647201762817
JCB 3566303999942285
Discover 6557343573058797

12 - Invalid Transaction

Card Type Card Number
Visa 4564720000000037
Mastercard 5100000000404390
Amex 377851937065671
Diners 3009589978161401
JCB 3566023559743341
Discover 6557343771747332

14 - Invalid Card Number

Card Type Card Number
Visa 4631728544548139
Mastercard 5553016800092435
Amex 377851167501973
Diners 3028680198362072
JCB 3562107819932234
Discover 6557325784863321

15 - No Such Issuer

Card Type Card Number
Visa 4564726349130286
Mastercard 5163200000000792
Amex 377851530450205
Diners 3010814190687935
JCB 3562108735707197
Discover 6557343662761160

35 - Card Acceptor Contact Acquirer

Card Type Card Number
Visa 4511776015533390
Mastercard 5500000000101893
Amex 377852274416022
Diners 3606005251011335
JCB 3562106573776829
Discover 6557351187743191

41 - Lost Card

Card Type Card Number
Visa 4631712173502799
Mastercard 5400000000501994
Amex 377850859783295
Diners 3876426173392665
JCB 3562106567430433
Discover 6557354512703609

03 - No Universal Account/Closed Account

Card Type Card Number
Visa 4631745132973214
Mastercard 5551656096578803
Amex 377852653186006
Diners 3025114366410748
JCB 3562103970090060
Discover 6557338997283245

43 - Stolen Card

Card Type Card Number
Visa 4631713277495963
Mastercard 5100000000432896
Amex 377852612490622
Diners 3815552602426388
JCB 3562105197145221
Discover 6557331328168284

51 - Insufficient Funds

Card Type Card Number
Visa 4617579107297798
Mastercard 5197657993376796
Amex 377852831176358
Diners 3005770347113984
JCB 3562108930783977
Discover 6557366309352739

54 - Invalid Expiry Date

Card Type Card Number
Visa 4715729787853300
Mastercard 5200000000022498
Amex 379936953734488
Diners 3009979651398133
JCB 3562103635164805
Discover 6504427542576114

36 - Restricted Card

Card Type Card Number
Visa 4631749139175633
Mastercard 5200000000830999
Amex 377851312622278
Diners 3812984506458717
JCB 3562104173493747
Discover 6509809571378535

91 - Transaction Timed Out / Response Received Too Late

Card Type Card Number
Visa 4631713707981210
Mastercard 5446471538337571
Amex 377852643992851
Diners 3684930560973740
JCB 3562107291467733
Discover 6504515951405112

15 - Card Issuer Unavailable

Card Type Card Number
Visa 4631756502801653
Mastercard 5446376540532533
Amex 379936492885940
Diners 3867263432361418
JCB 3562109655469016
Discover 6504486020047600

Specific Authorization Code Testing

If you need to simulate a specific issuer response code that is not covered by the above scenarios, use the following cards. You can include the exact issuer response code you want to receive by including it in the Card Name field, eg "08Bob Jones" will produce an "08 - Honour with identification" response.

Card Type Card Number
Visa 4661686268763776
Mastercard 5149024938880250
Mastercard 2222222222222224
Amex 348559568792267
Diners 3017559548368539
JCB 3562424339608339
Discover 6556356600257761

The simulator also supports the following cards for 3DS 2.0 testing. Choose which card to use to simulate the 3DS action you want to test. These cards also act like the cards above, so you can include the desired issuer response code in the card name to simulate a specific response.

Manual Challenge

Card Type Card Number
Visa 4631716043860311
Mastercard 5167473595100592
Amex 377851826358070
Diners 3001192225137726
JCB 3584145695882770
Discover 6504498873552834

Successful Authentication (Automatic Challenge Pass)

Card Type Card Number
Visa 4511774324799679
Mastercard 5161691610858193
Amex 377851498541607
Diners 3685416315533889
JCB 3584142032882258
Discover 6542477066608532

Failed Authentication (Automatic Challenge Fail)

Card Type Card Number
Visa 4293172753194849
Mastercard 5166674851597758
Amex 377851342111698
Diners 3835441249560369
JCB 3584142299672590
Discover 6573244951172699

Attempts / Non-Participating (Frictionless (Attempts) with no 3DS Method (Non-Participating))

Card Type Card Number
Visa 4525114332086104
Mastercard 5446476148092268
Amex 377850113449337
Diners 3014090285308564
JCB 3562105106083182
Discover 6509825415100836

Timeout (DS Timeout)

Card Type Card Number
Visa 4444333322221111
Mastercard 5166679383949633
Amex 376087778726102
Diners 3038387605159954
JCB 3584141042559740
Discover 6570176244095787

Timeout (3DS Method Timeout)

Card Type Card Number
Visa 4444333322221111
Mastercard 5166679383949633
Amex 376087778726102
Diners 3038387605159954
JCB 3584141042559740
Discover 6570176244095787

Not Enrolled

Card Type Card Number
Visa 4111111111111111
Mastercard 5204740000001002
Amex 377852136856480
Diners 3027285593502909
JCB 3530111333300000
Discover 6011868764043133

Unavailable (Frictionless No 3DS Method)

Card Type Card Number
Visa 4525114332086104
Mastercard 5446476148092268
Amex 377850113449337
Diners 3014090285308564
JCB 3562105106083182
Discover 6509825415100836

Authentication Unavailable (Card Not Enrolled)

Card Type Card Number
Visa 4111111111111111
Mastercard 5204740000001002
Amex 377852136856480
Diners 3027285593502909
JCB 3530111333300000
Discover 6011868764043133

Bypass Authentication (Frictionless N)

Card Type Card Number
Visa 4631773642610977
Mastercard 5459157606991464
Amex 379936352094765
Diners 3027687467474208
JCB 3584145656262608
Discover 6558428449903117

Successful Frictionless Authentication (Frictionless 3DS Method)

Card Type Card Number
Visa 4574357336019197
Mastercard 5446373276171776
Amex 377852201339230
Diners 3006205140196422
JCB 3562102804837241
Discover 6573661911483462

Failed Frictionless Authentication (Frictionless N)

Card Type Card Number
Visa 4631773642610977
Mastercard 5459157606991464
Amex 379936352094765
Diners 3027687467474208
JCB 3584145656262608
Discover 6558428449903117

Attempts Stand-In Frictionless Authentication (Frictionless A)

Card Type Card Number
Visa 4344161869960986
Mastercard 5162795916646654
Amex 377850212785789
Diners 3831877772683397
JCB 3584144622475303
Discover 6542194754719071

Unavailable Frictionless Authentication from the Issuer (Frictionless U)

Card Type Card Number
Visa 4715722496185288
Mastercard 5162279415160368
Amex 377850367873398
Diners 3677041135713873
JCB 3584147698530646
Discover 6558436501058241

Rejected Frictionless Authentication by the Issuer (Frictionless R)

Card Type Card Number
Visa 4631758482194299
Mastercard 5163295523861761
Amex 377850912829739
Diners 3015554046656503
JCB 3584147537400761
Discover 6542263476960345

Successful Step Up Authentication (Automatic Challenge Pass)

Card Type Card Number
Visa 4511774324799679
Mastercard 5161691610858193
Amex 377851498541607
Diners 3685416315533889
JCB 3584142032882258
Discover 6542477066608532

Failed Step Up Authentication (Automatic Challenge Fail)

Card Type Card Number
Visa 4293172753194849
Mastercard 5166674851597758
Amex 377851342111698
Diners 3835441249560369
JCB 3584142299672590
Discover 6573244951172699

Step Up Authentication is Unavailable (Frictionless U)

Card Type Card Number
Visa 4715722496185288
Mastercard 5162279415160368
Amex 377850367873398
Diners 3677041135713873
JCB 3584147698530646
Discover 6558436501058241

Error on Authentication (DS Timeout)

Card Type Card Number
Visa 4444333322221111
Mastercard 5166679383949633
Amex 376087778726102
Diners 3038387605159954
JCB 3584141042559740
Discover 6570176244095787

Bypassed Authentication (Frictionless N)

Card Type Card Number
Visa 4631773642610977
Mastercard 5459157606991464
Amex 379936352094765
Diners 3027687467474208
JCB 3584145656262608
Discover 6558428449903117
Authorization Response Codes

The following table lists the Authorization Response Codes that are returned by an issuer and/or acquiring switch when processing credit/debit card transactions. These values are also returned in the authResponseCode value in a transaction response. American Express Direct Link and Discover Direct Link response codes are available below this table.

Authorization Code Description
00 Approved
01 Refer to Card Issuer
02 Refer to Issuer's special conditions
03 Invalid Merchant
04 Pick Up Card
05 Do Not Honor
06 Error
07 Pick Up Card, Special Conditions
08 Honor with identification
09 Request in Progress
10 Partial Amount Approved
11 VIP Approval
12 Invalid Transaction
13 Invalid Amount
14 Invalid Card Number
15 No Such Issuer
16 Approved, update track 3
17 Customer Cancellation
18 Customer Dispute
19 Re-enter Transaction
20 Invalid Response
21 No Action Taken (no match)
22 Suspected Malfunction
23 Unacceptable Transaction Fee
24 File Update not Supported by Receiver
25 Unable to Locate Record on File
26 Duplicate File Update Record
27 File Update Field Edit Error
28 File Update File Locked Out
29 File Update not Successful
30 Format Error
31 Bank not Supported by Switch
32 Completed Partially
33 Expired Card - Pick Up
34 Suspected Fraud - Pick Up
35 Contact Acquirer - Pick Up
36 Restricted Card - Pick Up
37 Call Acquirer Security - Pick Up
38 Allowable PIN Tries Exceeded
39 No CREDIT Account
40 Requested Function not Supported
41 Lost Card - Pick Up
42 No Universal Amount
43 Stolen Card - Pick Up
44 No Investment Account
45 Account Closed
46 Identification Required
47 Identification Cross-Check Required
48 No Customer Record
49 Reserved For Future Realtime Use
50 Reserved For Future Realtime Use
51 Insufficient Funds
52 No Cheque Account
53 No Savings Account
54 Expired Card
55 Incorrect PIN
56 No Card Record
57 Trans. not Permitted to Cardholder
58 Transaction not Permitted to Terminal
59 Suspected Fraud
60 Card Acceptor Contact Acquirer
61 Exceeds Withdrawal Amount Limits
62 Restricted Card
63 Security Violation
64 Original Amount Incorrect
65 Exceeds Withdrawal Frequency Limit
66 Card Acceptor Call Acquirer Security
67 Hard Capture - Pick Up Card at ATM
68 Response Received Too Late
75 Allowable PIN Tries Exceeded
76 Previous message not found
77 Data does not match original message
80 Invalid Date
81 Cryptographic failure
82 Incorrect CVV
83 Unable to verify PIN
84 Invalid authorization life cycle
85 No reason to decline
86 ATM Malfunction
87 No Envelope Inserted
88 Unable to Dispense
89 Administration Error
90 Cut-off in Progress
91 Issuer or Switch is Inoperative
92 Financial Institution Not Found
93 Trans Cannot be Completed
94 Duplicate Transmission
95 Reconcile Error
96 System Malfunction
97 Reconciliation Totals Reset
98 MAC Error
99 Reserved for National Use
N0 Force STIP (VISA)
N3 Cash Service Not Available (VISA)
N4 Cash request exceeds issuer limit (VISA)
N7 Decline for CVV2 failure (VISA)
P2 Invalid biller information (VISA)
P5 PIN Change Unblock Declined (VISA)
P6 Unsafe PIN (VISA)
XA Forward to issuer
XD Forward to issuer
XX Unknown Code

The table below lists the Authorization Response Codes that are returned if your American Express transactions are being processed via the American Express Direct Link.

Authorization Code Description
000 Approved
001 Approve with ID
002 Partial Approval (Prepaid Cards only)
100 Deny
101 Expired Card / Invalid Expiration Date
106 Exceeded PIN attempts
109 Invalid merchant
110 Invalid amount
111 Invalid account / Invalid MICR (Travelers Cheque)
115 Requested function not supported
117 Invalid PIN
119 Cardmember not enrolled / not permitted
122 Invalid card security code (a.k.a., CID, 4DBC, 4CSC)
125 Invalid effective date
130 Additional customer identification required
181 Format error
183 Invalid currency code
187 Deny - New card issued
189 Deny - Canceled or Closed Merchant/SE
200 Deny - Pick up card
400 Reversal Accepted
900 Accepted - ATC Synchronization
909 System Malfunction (Cryptographic Error)
912 Issuer not available

The table below lists the Authorization Response Codes that are returned if your Discover transactions are being processed via the Discover Direct Link.

Authorizatoin Code Description
000 pin change successful
001 honor with identification
081 approved by Issuer
082 approved by Xpress
083 approved by Acquirer
084 offline approved
085 offline approved, Unable to go online
086 card verification successful
100 do not honor
101 expired card
102 suspected fraud
104 restricted card
106 allowable PIN tries exceeded
109 invalid merchant
110 invalid amount
111 invalid card number
115 requested function not supported
117 incorrect PIN
118 cycle range suspended
119 Transaction not permitted to cardholder
122 card validity period exceeded
124 violation of law
125 card not effective
129 suspected counterfeit card
140 offline declined, Merchant Forced Acceptance
141 unable to go online, offline declined, Merchant Forced Acceptance
163 security violations
181 decline given by POS participant
182 decline given by Issuer
183 Domain Restriction Control Failure
184 decline given by Xpress, no communication with Issuer
185 decline given by Xpress, card is local use only
188 Xpress unable to forward request to Issuer X
192 Restricted Merchant
194 PIN change or unblock failed
195 new PIN not accepted
196 chip information advice
197 card verification failure
198 TVR or CVR validation failed
200 do not honor
201 expired card
202 suspected fraud
203 card acceptor contact Acquirer
204 restricted card
205 card acceptor call Acquirers security department
206 allowable PIN tries exceeded
207 special conditions
208 lost card
209 stolen card
210 suspected counterfeit card
280 temporary status lost card
281 temporary status stolen card
300 successful
301 not supporte by reciever
302 unable to locate record on file
303 duplicate record, old record replaced
304 data element edit error
305 file locked out
306 not successful
307 format error
308 duplicate, new record rejected
309 unknown file
380 not successful, cross reference exists
382 continutation data in next record
397 card on Positive File
399 VIP card with limits
400 accepted
480 function code not allowed
481 account number invalid
482 account number does not mod10
483 no matching cycle range exists for this account
484 invalid amount
680 Forward to destination Participant
600 accepted
800 accepted
909 destination not known
910 destination not in service
Chargeback Reason Codes

The following table lists the Visa chargeback reason codes and their descriptions.

Reason Code Description
10.1 EMV Liability Shift
10.2 EMV Liability Shift Non-counterfeit Fraud
10.3 Card-Present Environment
10.4 Card-Absent Environment
10.5 Visa Fraud Monitoring Program
11.1 Card Recovery Bulletin
11.2 Declined Authorisation
11.3 No Authorisation
12.1 Late Presentment
12.2 Incorrect Transaction Code
12.3 Incorrect Currency
12.4 Incorrect Account Number
12.5 Incorrect Amount
12.6 Duplicate Processing/Paid by Other Means
12.7 Invalid Data
13.1 Merchandise/Services Not Received
13.2 Cancelled Recurring Transaction
13.3 Not as Described or Defective Merchandise/Service
13.4 Counterfeit Merchandise
13.5 Misrepresentation
13.6 Credit Not Processed
13.7 Cancelled Merchandise/Services
13.8 Original Credit Transaction Not Accepted
13.9 Non-Receipt of Cash or Load Transaction Value

The following table lists the MasterCard chargeback reason codes and their descriptions.

Reason Code Description
4837 No Cardholder Authorization
4840 Fraudulent Processing of Transactions
4847 Exceeds Floor Limit, Not Authorised
4849 Questionable Merchant Activity
4862 Counterfeit Transaction / Magnetic Stripe POS Fraud
4863 Cardholder Does Not Recognize
4870 Chip Liability Shift
4871 Chip/PIN Liability Shift
4807 Warning Bulletin File
4808 Requested/Required Authorisation Not Obtained
4812 Account Number Not On File
4831 Transaction Amount Differs
4834 Duplicate Processing / POS Error
4835 Card Not Valid or Expired
4842 Late Presentment
4846 Correct Transaction Currency Code Not Provided
4850 Installment Billing Dispute
4902 Required Information Illegible or Missing
4999 Domestic Chargeback Dispute (Europe Region Only)
4841 Canceled Recurring or Digital Goods Transactions
4853 Cardholder Dispute
4854 Cardholder Dispute (U.S. Region Only)
4855 Goods or Services Not Provided
4857 Card-Activated Telephone Transaction
4859 Addendum, No-show, or ATM Dispute
4860 Credit Not Processed

The following table lists the American Express chargeback reason codes and their descriptions.

Reason Code Description
4507 Incorrect Transaction Amount or Account Number Presented
4512 Multiple Processing
4513 Credit Not Presented
4515 Paid through Other Means
4516 Request for Support Not Fulfilled
4517 Request for Support Illegible/Incomplete
4521 Invalid Authorization
4523 Unassigned C/M Account Number
4526 Missing Signature
4527 Missing Imprint
4530 Currency Discrepancy
4534 Multiple ROCs
4536 Late Presentment
4540 Card Not Present
4544 Cancellation of Recurring Goods/Services Services
4553 Not as Described or defective merchandise
4554 Goods and Services Not Received
4750 Car Rental Charge in Dispute
4752 Credit/Debit Presentment Error
4754 Local Regulatory/Legal Dispute
4755 No Valid Authorization
4758 Expired/Not Yet valid card
4763 Fraud Full Recourse
4798 Fraud Liability Shift - Counterfeit
4799 Fraud Liability Shift - Lost/Stolen
MAC Codes

The following table lists the Merchant Advice Codes (MAC) and their descriptions. If a MAC code is returned to you in our response, its instructions must be followed. Failure to do so many incur a penalty fee.

MAC Code Description
1 Updated information needed
2 Try again later
3 Do not try again
4 Transaction not supported
21 Stop recurring payment requests
24 Retry after 1 hour
25 Retry after 24 hours
26 Retry after 2 days
27 Retry after 4 days
28 Retry after 6 days
29 Retry after 8 days
30 Retry after 10 days
40 Consumer non-reloadable prepaid card
41 Consumer single-use virtual card number