Hosted Payments

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

Endpoints

Sandbox
POST https://securetest.merchantwarrior.com/ Copy

Production
POST https://secure.merchantwarrior.com/ Copy

processCard

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’.
Example: processCard

merchantUUID

The value of this parameter is provided to you by Merchant Warrior.
Example: 123456789abcd

apiKey

The value of this parameter is provided to you by Merchant Warrior.
Example: 1a3b5c

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.
Example: 10.00

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.
Example: AUD

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.
Example: ABC4321
Valid length: Up to 255 characters. Some Acquirers limit this field to 40 characters.

returnURL

The customer will be redirected to this URL upon completion of the transaction.
Example: https://www.example.com/return.php

notifyURL

Asynchronous POST notifications will be sent to this URL.
Example: https://www.example.com/notify.php

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.
Example: 511999e54b9ad51ce4c28d7f0550ac81
Valid Length: 32 characters

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.
Example: 3x4mpl3s4lt!

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.
Example: e9ddc296b76b3398934bfc06239073df
Valid length: 32 characters

Optional Parameters

Parameter Description
customerName

This field can only contain alphanumeric characters, as well as the full stop and hyphen character.
Example: Mr. Example Person
Valid length: Between 2 and 255 characters

customerCountry

Two letter ISO 3166-1 alpha-2 country code.
Example: AU
Valid length: 2 characters

customerState

Freeform field, keep consistent for your records and reporting.
Example: Queensland
Valid length: Up to 75 characters

customerCity

Freeform field, keep consistent for your records and reporting.
Example: Brisbane
Valid length: Up to 75 characters

customerAddress

Freeform field.
Example: 123 Test Street
Valid length: Up to 255 characters

customerPostCode

This can also accomodate ZIP/Post codes for international transactions.
Example: 4000
Valid length: Between 4 and 10 characters

customerPhone

Anything other than +,-, space and 0-9 will be stripped.
Example: 0401234567 or 61731234567
Valid length: Up to 25 characters

customerEmail

Must be valid if present. Sending this optional parameter is highly recommended.
Example: [email protected]
Valid length: Up to 255 characters

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.
Example: https://www.example.com/logo.png

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.

  • 0: Disable all surcharging (including the surcharging values listed in the Barracks portal)
  • 1: Enable surcharge
  • Null or omitted: Revert to default behaviour of using the surcharge percentages listed in the Barracks portal.
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.
Example: 1

allowedCards

Comma separated list of the card types allowed for the transaction.

Possible options are -

  • visa
  • mc
  • amex
  • diners
  • discover
  • jcb

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

Copy
<?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>
Transaction approved 12345 0 731357421 10.00 08 1336-20be3569-b600-11e6-b9c3-005056b209e0 731357421 65b172551b7d3a0706c0ce5330c98470 2016-11-29 512345XXXXXX2346 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"
}
{ "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&amp;reference=1-373eb735-bd24-11e6-992a-005056b209e0&amp;transactionReferenceID=12345&amp;hash=c4c5db49d97b21c7898f3e8ed8057b24&amp;custom1=&amp;custom2=&amp;custom3=&amp;customHash=9c8bffd18b890aebf84b27744a205385&amp;message=Transaction+approved&amp;paymentCardNumber=512345XXXXXX2346&amp;transactionAmount=10.00</response>
</mwResponse>
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"
}
{ "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>
0.77857 1045.85 Transaction approved 12345 visa AUD 0 1343.30 731357421 10.00 08 1336-20be3569-b600-11e6-b9c3-005056b209e0 731357421 USD 2.75 65b172551b7d3a0706c0ce5330c98470 2016-11-29 512345XXXXXX2346 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"
}
{ "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&amp;reference=2-e2a1c77b-79ca-11e8-b076-005056b209e0&amp;transactionReferenceID=12345&amp;hash=ecb97ee50f2fecd77fd8e2b9420738cf&amp;custom1=&amp;custom2=&amp;custom3=&amp;customHash=5ffe664050654421284bbc5c4f137adb&amp;message=Transaction+approved&amp;paymentCardNumber=400555XXXXXX0001&amp;transactionAmount=10.00&amp;cardType=visa&amp;dccOriginalCur=AUD&amp;dccOriginalAmt=12.85&amp;dccRate=0.77857&amp;dccCur=USD&amp;dccAmt=10.00&amp;dccCom=2.75</response>
</mwResponse>
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"
}
{ "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" }
processDDebitAuth

The processDDebitAuth method is used to initiate an electronic (paperless) direct debit authorization form

Required Parameters

Parameter Description
method

This field is case sensitive.
Example: processDDebitAuth

merchantUUID

The value of this parameter is provided to you by Merchant Warrior.
Example: 123456789abcd

apiKey

The value of this parameter is provided to you by Merchant Warrior.
Example: 1a3b5c

customerName

This field can only contain alphanumeric characters, as well as the full stop, comma, apostrophe, ampersand, space and hyphen characters.
Example: Mr. Example Person
Valid length: Between 2 and 255 characters

customerCountry

Two letter ISO 3166-1 alpha-2 country code.
Example: AU
Valid length: 2 characters

customerState

Freeform field, keep consistent for your records and reporting.
Example: Queensland
Valid length: Up to 75 characters

customerCity

Freeform field, keep consistent for your records and reporting.
Example: Brisbane
Valid length: Up to 75 characters

customerAddress

Freeform field.
Example: 123 Test Street
Valid length: Up to 255 characters

customerPostCode

This can also accomodate ZIP/Post codes for international transactions.
Example: 4000
Valid length: Between 4 and 10 characters

customerPhone

Anything other than +,-, space and 0-9 will be stripped.
Example: 0401234567 or 61731234567
Valid length: Up to 25 characters

customerEmail

Sending this optional parameter is highly recommended.
Example: [email protected]
Valid length: Up to 255 characters

paymentAccountBSB

BSB of the account to be debited. This field must contain 6 digits.
Example: 123123
Valid length: 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.
Example: Mr. Example Person or MR E PERSON or Example Person
Valid length: Between 3 and 32 characters

paymentAccountNumber

Account number of the account to be debited. This must be a valid account number.
Example: 234523451
Valid length: 4-10 digits

transactionCurrency

One of the following: AUD or NZD.
Example: AUD

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)
Example: e9ddc296b76b3398934bfc06239073df
Valid length: 32 characters

returnURL

The customer will be redirected to this URL upon completion of the transaction.
Example: https://www.example.com/return.php

notifyURL

Asynchronous POST notifications will be sent to this URL.
Example: https://www.example.com/notify.php

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.
Example: Queensland
Valid Length: Up to 32 characters

hashSalt

Used to salt the return hash used in the 302 Redirect to redirectURL upon the completion of a transaction.
Example: 3x4mpl3s4lt!

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.
Example: 10.00

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.
Example: https://www.example.com/logo.png

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.
Example: 1

custom1

Freeform field. Returned as <custom1> in the XML response.
Valid length: Up to 500 characters

custom2

Freeform field. Returned as <custom2> in the XML response.
Valid length: Up to 500 characters

custom3

Freeform field. Returned as <custom3> in the XML response.
Valid length: Up to 500 characters

Copy
<?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>
Test Field f0ab06f8d69d3dafa06a5abd45460ace DDA approved 123456 da407c1d6ebc1ed405109497d1e0caa5 0 987456123 John Doe [email protected] 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"
}
{ "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" }