The following sub-sections will outline the various API methods present in the Merchant Warrior Hosted Payments service
- Endpoints
-
processCard
The processCard method is the method used to perform a purchase request
-
processDDebitAuth
The processDDebitAuth method is used to initiate an electronic (paperless) direct debit authorization form
Sandbox
POST
https://securetest.merchantwarrior.com/
Copy
Production
POST
https://secure.merchantwarrior.com/
Copy
Requests are generated via a form with the parameters below presented to the customer's browser.
Required Parameters
Parameter | Description |
---|---|
method | This field is case sensitive. Currently, the only valid value for this parameter is ‘processCard’. |
merchantUUID | The value of this parameter is provided to you by Merchant Warrior. |
apiKey | The value of this parameter is provided to you by Merchant Warrior. |
transactionAmount | The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected. |
transactionCurrency | One of the following: AUD, CAD, EUR, GBP, JPY, NZD, SGD, USD. This is provider dependant. Please check with MW before attempting to process transactions in any currency other than AUD. This field is case insensitive. |
transactionProduct | A product (or sale) id or description. We recommend using an order/product id. This field’s primary purpose is to help the transaction be identifiable for reporting and accounting purposes. |
returnURL | The customer will be redirected to this URL upon completion of the transaction. |
notifyURL | Asynchronous POST notifications will be sent to this URL. |
urlHash | The urlHash field is a combination of your API Passphrase, and specific parameters sent in the transaction. See Web URL Hash for information on how to construct the hash correctly. |
hashSalt | Used to salt the return hash used in the 302 Redirect to redirectURL upon the completion of a transaction. A completely random string should be generated and inserted here, please do NOT use the example shown in our requests. |
hash | The verification hash is a combination of the MD5 of your API Passphrase, and specific parameters sent in the transaction. See Transaction Type Hash for information on how to construct the hash correctly. |
Optional Parameters
Parameter | Description |
---|---|
customerName | This field can only contain alphanumeric characters, as well as the full stop and hyphen character. |
customerCountry | Two letter ISO 3166-1 alpha-2 country code. |
customerState | Freeform field, keep consistent for your records and reporting. |
customerCity | Freeform field, keep consistent for your records and reporting. |
customerAddress | Freeform field. |
customerPostCode | This can also accomodate ZIP/Post codes for international transactions. |
customerPhone | Anything other than +,-, space and 0-9 will be stripped. |
customerEmail | Must be valid if present. Sending this optional parameter is highly recommended. |
logoURL | The URL to an image that will appear in the header of the hosted payment page. Image must be of PNG format and max dimensions of 90x90 pixels and a file size limit of 1500 kilobytes. If no logoURL is supplied a default basket image is used. |
surcharge | Calculate the surcharge for the transactions (after the cardholder types their card number in) and add it to the total amount charged to the card. This feature allows the merchant to receive the full amount in their settlement.
|
hostedID | The ID of the customized hosted payment page. This can be implemented if multiple hosted payment pages with different logos and banners is a requirement. |
allowedCards | Comma separated list of the card types allowed for the transaction. Possible options are -
Example: visa,mc |
returnOnApproved | Indicates to redirect to the Return URL only if the transaction is approved. If active, declined transactions will keep the user on the Hosted Payment Page and display an error message, allowing the user to try again. Example: 1 |
displayReference | Can be used to display a different reference on the Hosted Payment Page other than what is specified in transactionProduct. The value of transactionProduct will still be saved against the transaction and the value of displayReference is for display purposes only and is not saved. Example: Shoes R Us Purchase |
hideReference | Can be used to hide the reference displayed on the Hosted Payment Page entirely. The value of transactionProduct will still be saved against the transaction. Example: 1 |
<?xml version="1.0"?>
<mwResponse>
<custom1/>
<custom2/>
<custom3/>
<responseMessage>Transaction approved</responseMessage>
<transactionReferenceID>12345</transactionReferenceID>
<responseCode>0</responseCode>
<authCode>731357421</authCode>
<transactionAmount>10.00</transactionAmount>
<authResponseCode>08</authResponseCode>
<transactionID>1336-20be3569-b600-11e6-b9c3-005056b209e0</transactionID>
<receiptNo>731357421</receiptNo>
<customHash>65b172551b7d3a0706c0ce5330c98470</customHash>
<authSettledDate>2016-11-29</authSettledDate>
<paymentCardNumber>512345XXXXXX2346</paymentCardNumber>
<authMessage>Honour with identification</authMessage>
</mwResponse>
{
"custom1": [],
"custom2": [],
"custom3": [],
"responseMessage": "Transaction approved",
"transactionReferenceID": "12345",
"responseCode": "0",
"authCode": "731357421",
"transactionAmount": "10.00",
"authResponseCode": "08",
"transactionID": "1336-20be3569-b600-11e6-b9c3-005056b209e0",
"receiptNo": "731357421",
"customHash": "65b172551b7d3a0706c0ce5330c98470",
"authSettledDate": "2016-11-29",
"paymentCardNumber": "512345XXXXXX2346",
"authMessage": "Honour with identification"
}
{
"custom1": [],
"custom2": [],
"custom3": [],
"responseMessage": "Transaction approved",
"transactionReferenceID": "12345",
"responseCode": "0",
"authCode": "731357421",
"transactionAmount": "10.00",
"authResponseCode": "08",
"transactionID": "1336-20be3569-b600-11e6-b9c3-005056b209e0",
"receiptNo": "731357421",
"customHash": "65b172551b7d3a0706c0ce5330c98470",
"authSettledDate": "2016-11-29",
"paymentCardNumber": "512345XXXXXX2346",
"authMessage": "Honour with identification"
}<?xml version="1.0"?>
<mwResponse>
<response>https://www.mydomain.com/sample.return.php?status=approved&reference=1-373eb735-bd24-11e6-992a-005056b209e0&transactionReferenceID=12345&hash=c4c5db49d97b21c7898f3e8ed8057b24&custom1=&custom2=&custom3=&customHash=9c8bffd18b890aebf84b27744a205385&message=Transaction+approved&paymentCardNumber=512345XXXXXX2346&transactionAmount=10.00</response>
</mwResponse>
{
"response": "https:\/\/www.mydomain.com\/sample.return.php?status=approved&reference=1-373eb735-bd24-11e6-992a-005056b209e0&transactionReferenceID=12345&hash=c4c5db49d97b21c7898f3e8ed8057b24&custom1=&custom2=&custom3=&customHash=9c8bffd18b890aebf84b27744a205385&message=Transaction+approved&paymentCardNumber=512345XXXXXX2346&transactionAmount=10.00"
}
{
"response": "https:\/\/www.mydomain.com\/sample.return.php?status=approved&reference=1-373eb735-bd24-11e6-992a-005056b209e0&transactionReferenceID=12345&hash=c4c5db49d97b21c7898f3e8ed8057b24&custom1=&custom2=&custom3=&customHash=9c8bffd18b890aebf84b27744a205385&message=Transaction+approved&paymentCardNumber=512345XXXXXX2346&transactionAmount=10.00"
}<?xml version="1.0"?>
<mwResponse>
<custom1/>
<custom2/>
<custom3/>
<dccRate>0.77857</dccRate>
<dccAmt>1045.85</dccAmt>
<responseMessage>Transaction approved</responseMessage>
<transactionReferenceID>12345</transactionReferenceID>
<cardType>visa</cardType>
<dccOriginalCur>AUD</dccOriginalCur>
<responseCode>0</responseCode>
<dccOriginalAmt>1343.30</dccOriginalAmt>
<authCode>731357421</authCode>
<transactionAmount>10.00</transactionAmount>
<authResponseCode>08</authResponseCode>
<transactionID>1336-20be3569-b600-11e6-b9c3-005056b209e0</transactionID>
<receiptNo>731357421</receiptNo>
<dccCur>USD</dccCur>
<dccCom>2.75</dccCom>
<customHash>65b172551b7d3a0706c0ce5330c98470</customHash>
<authSettledDate>2016-11-29</authSettledDate>
<paymentCardNumber>512345XXXXXX2346</paymentCardNumber>
<authMessage>Honour with identification</authMessage>
</mwResponse>
{
"custom1": [],
"custom2": [],
"custom3": [],
"dccRate": "0.77857",
"dccAmt": "1045.85",
"responseMessage": "Transaction approved",
"transactionReferenceID": "12345",
"cardType": "visa",
"dccOriginalCur": "AUD",
"responseCode": "0",
"dccOriginalAmt": "1343.30",
"authCode": "731357421",
"transactionAmount": "10.00",
"authResponseCode": "08",
"transactionID": "1336-20be3569-b600-11e6-b9c3-005056b209e0",
"receiptNo": "731357421",
"dccCur": "USD",
"dccCom": "2.75",
"customHash": "65b172551b7d3a0706c0ce5330c98470",
"authSettledDate": "2016-11-29",
"paymentCardNumber": "512345XXXXXX2346",
"authMessage": "Honour with identification"
}
{
"custom1": [],
"custom2": [],
"custom3": [],
"dccRate": "0.77857",
"dccAmt": "1045.85",
"responseMessage": "Transaction approved",
"transactionReferenceID": "12345",
"cardType": "visa",
"dccOriginalCur": "AUD",
"responseCode": "0",
"dccOriginalAmt": "1343.30",
"authCode": "731357421",
"transactionAmount": "10.00",
"authResponseCode": "08",
"transactionID": "1336-20be3569-b600-11e6-b9c3-005056b209e0",
"receiptNo": "731357421",
"dccCur": "USD",
"dccCom": "2.75",
"customHash": "65b172551b7d3a0706c0ce5330c98470",
"authSettledDate": "2016-11-29",
"paymentCardNumber": "512345XXXXXX2346",
"authMessage": "Honour with identification"
}<?xml version="1.0"?>
<mwResponse>
<response>https://www.mydomain.com/sample.return.php?status=approved&reference=2-e2a1c77b-79ca-11e8-b076-005056b209e0&transactionReferenceID=12345&hash=ecb97ee50f2fecd77fd8e2b9420738cf&custom1=&custom2=&custom3=&customHash=5ffe664050654421284bbc5c4f137adb&message=Transaction+approved&paymentCardNumber=400555XXXXXX0001&transactionAmount=10.00&cardType=visa&dccOriginalCur=AUD&dccOriginalAmt=12.85&dccRate=0.77857&dccCur=USD&dccAmt=10.00&dccCom=2.75</response>
</mwResponse>
{
"response": "https:\/\/www.mydomain.com\/sample.return.php?status=approved&reference=2-e2a1c77b-79ca-11e8-b076-005056b209e0&transactionReferenceID=12345&hash=ecb97ee50f2fecd77fd8e2b9420738cf&custom1=&custom2=&custom3=&customHash=5ffe664050654421284bbc5c4f137adb&message=Transaction+approved&paymentCardNumber=400555XXXXXX0001&transactionAmount=10.00&cardType=visa&dccOriginalCur=AUD&dccOriginalAmt=12.85&dccRate=0.77857&dccCur=USD&dccAmt=10.00&dccCom=2.75"
}
{
"response": "https:\/\/www.mydomain.com\/sample.return.php?status=approved&reference=2-e2a1c77b-79ca-11e8-b076-005056b209e0&transactionReferenceID=12345&hash=ecb97ee50f2fecd77fd8e2b9420738cf&custom1=&custom2=&custom3=&customHash=5ffe664050654421284bbc5c4f137adb&message=Transaction+approved&paymentCardNumber=400555XXXXXX0001&transactionAmount=10.00&cardType=visa&dccOriginalCur=AUD&dccOriginalAmt=12.85&dccRate=0.77857&dccCur=USD&dccAmt=10.00&dccCom=2.75"
}
The processDDebitAuth method is used to initiate an electronic (paperless) direct debit authorization form
Required Parameters
Parameter | Description |
---|---|
method | This field is case sensitive. |
merchantUUID | The value of this parameter is provided to you by Merchant Warrior. |
apiKey | The value of this parameter is provided to you by Merchant Warrior. |
customerName | This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters. |
customerCountry | Two letter ISO 3166-1 alpha-2 country code. |
customerState | Freeform field, keep consistent for your records and reporting. |
customerCity | Freeform field, keep consistent for your records and reporting. |
customerAddress | Freeform field. |
customerPostCode | This can also accomodate ZIP/Post codes for international transactions. |
customerPhone | Anything other than +,-, space and 0-9 will be stripped. |
customerEmail | Sending this optional parameter is highly recommended. |
paymentAccountBSB | BSB of the account to be debited. This field must contain 6 digits. |
paymentAccountName | The name on the account to be debited. This must contain at the very least a space and no less than two characters. Only alphanumeric characters, hyphens, spaces and full stops are allowed. |
paymentAccountNumber | Account number of the account to be debited. This must be a valid account number. |
transactionCurrency | One of the following: AUD or NZD. |
hash | The verification hash is a combination of the MD5 of your API Passphrase, and specific parameters sent in the transaction. See Transaction Type Hash for information on how to construct the hash correctly. (Field is only required if transactionAmount and transactionCurrency have been set for a DDA) |
returnURL | The customer will be redirected to this URL upon completion of the transaction. |
notifyURL | Asynchronous POST notifications will be sent to this URL. |
urlHash | The urlHash field is a combination of your API Passphrase, and specific parameters sent in the transaction. See Web URL Hash for information on how to construct the hash correctly. |
hashSalt | Used to salt the return hash used in the 302 Redirect to redirectURL upon the completion of a transaction. |
Optional Parameters
Parameter | Description |
---|---|
transactionAmount | The amount must be formatted to have two decimal places. Any amounts without two decimal places or amounts less than one cent will be rejected. This field is not required if you are submitting a direct debit authorization that has a variable amount. |
logoURL | The URL to an image that will appear in the header of the hosted payment page. Image must be of PNG format and max dimensions of 90x90 pixels and a file size limit of 1500 kilobytes. If no logoURL is supplied a default Direct Debit icon is displayed. |
hostedID | Digits only. The ID of the customized hosted payment page. This can be implemented if multiple hosted DDA pages with different logos and banners are a requirement. |
custom1 | Freeform field. Returned as |
custom2 | Freeform field. Returned as |
custom3 | Freeform field. Returned as |
<?xml version="1.0"?>
<mwResponse>
<custom1>Test Field</custom1>
<custom2/>
<custom3/>
<fingerprint>f0ab06f8d69d3dafa06a5abd45460ace</fingerprint>
<responseMessage>DDA approved</responseMessage>
<paymentAccountBSB>123456</paymentAccountBSB>
<hash>da407c1d6ebc1ed405109497d1e0caa5</hash>
<responseCode>0</responseCode>
<paymentAccountNumber>987456123</paymentAccountNumber>
<paymentAccountName>John Doe</paymentAccountName>
<customerEmail>[email protected]</customerEmail>
<customHash>9f61558611bd58b97ea9f505536f5101</customHash>
</mwResponse>
{
"custom1": "Test Field",
"custom2": [],
"custom3": [],
"fingerprint": "f0ab06f8d69d3dafa06a5abd45460ace",
"responseMessage": "DDA approved",
"paymentAccountBSB": "123456",
"hash": "da407c1d6ebc1ed405109497d1e0caa5",
"responseCode": "0",
"paymentAccountNumber": "987456123",
"paymentAccountName": "John Doe",
"customerEmail": "[email protected]",
"customHash": "9f61558611bd58b97ea9f505536f5101"
}
{
"custom1": "Test Field",
"custom2": [],
"custom3": [],
"fingerprint": "f0ab06f8d69d3dafa06a5abd45460ace",
"responseMessage": "DDA approved",
"paymentAccountBSB": "123456",
"hash": "da407c1d6ebc1ed405109497d1e0caa5",
"responseCode": "0",
"paymentAccountNumber": "987456123",
"paymentAccountName": "John Doe",
"customerEmail": "[email protected]",
"customHash": "9f61558611bd58b97ea9f505536f5101"
}