The following sub-sections will outline the various API methods present in the Merchant Warrior Token Payments service
- Endpoints
- Introduction
- Key Management
-
addCard
The addCard method is used to add a new card to the MW Vault
-
removeCard
The removeCard method is the method used to remove a card from the MW Vault once it has been added
-
cardInfo
The cardInfo method is used to perform a query of an existing card
-
changeExpiry
The changeExpiry method is used to modify a card’s expiry after it has been added to the MW Vault
-
processCard
The processCard method is used to perform a purchase transaction using a Token ID that exists in the MW Vault
-
processAuth
The processAuth method is the method used to perform a pre-authorization transaction using a Token ID
Sandbox
POST
https://base.merchantwarrior.com/token/
Copy
Production
POST
https://api.merchantwarrior.com/token/
Copy
Token Payments allows merchants to perform subsequent transactions for a customer without the customer sending their cardholder data to the MW platform more than once. Implementing this feature can reduce PCI DSS scope significanly as merchants are not required to store customer cardholder (PAN) data.
As the Token Payments solution enables merchants to store encryption keys the following key management principles must be taken into consideration:
Key management principles and recommendations provided by NIST should be followed - http://csrc.nist.gov/groups/ST/key_mgmt/
• Strong encryption keys should be generated (pseudo-random data of high entropy)
• Encryption keys must only be transmitted via a Secure Socket Layer (TLS 1.2+) encrypted tunnel
• Encryption keys must be stored securely, only accessible by necessary staff and applications
• Staff with access to encryption keys should acknowledge (in writing or electronically) that they understand and accept their key-custodian responsibilities
• The same cryptographic keys should not be used in production and test environments
The addCard method is used to add a new card to the MW Vault
Required Parameters
Parameter | Description |
---|---|
method | This field is case sensitive. |
cardName | 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. |
cardNumber | Example: 5123456789012346 or 4557012345678902 |
cardExpiryMonth | This must be MM format. The month must be zero padded if it is less than 10. |
cardExpiryYear | This must be YY format. |
Conditional Parameters
Parameter | Description |
---|---|
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. |
accessToken | A single use access token, used in place of your merchant credentials. |
Optional Parameters
Parameter | Description |
---|---|
verifyCard | This parameter is used to indicate if the card details (cardNumber, cardExpiry and optionally the paymentCardCSC) should be verified automatically before being tokenized. Its value must be 0 or 1. |
paymentCardCSC | This is also known as the CVN or CVV/2. If you are verifying the card number during your addCard request we highly recommend you submit this value in your request. |
The removeCard method is the method used to remove a card from the MW Vault once it has been added
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. |
cardID | A unique alphanumeric string returned by addCard, used to identify a specific card. |
Optional Parameters
Parameter | Description |
---|---|
cardKey | A string used as an encryption/decryption key. This should be unique on a per-card basis. It’s used to encrypt the card when we store it. Every time we receive a process card request, the correct cardkey must also be provided – which is known only to you. |
The cardInfo method is used to perform a query of an existing card. This method will return the information added via addCard with the credit card number (PAN) truncated
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. |
cardID | A unique alphanumeric string returned by addCard, used to identify a specific card. |
Optional Parameters
Parameter | Description |
---|---|
cardKey | A string used as an encryption/decryption key. This should be unique on a per-card basis. It’s used to encrypt the card when we store it. Every time we receive a process card request, the correct cardkey must also be provided – which is known only by you. |
The changeExpiry method is used to modify a card’s expiry after it has been added to the MW Vault
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. |
cardID | A unique alphanumeric string returned by addCard, used to identify a specific card. |
cardExpiryMonth | This must be MM format. The month must be zero padded if it is less than 10. |
cardExpiryYear | This must be YY format. |
Optional Parameters
Parameter | Description |
---|---|
cardKey | A string used as an encryption/decryption key. This should be unique on a per-card basis. It’s used to encrypt the card when we store it. Every time we receive a process card request, the correct cardkey must also be provided – which is known only by you. |
The processCard method is used to perform a purchase transaction using a Token ID that exists in the MW Vault
Request-Parameters
These paramaters are practically identical to the Direct API processCard method. The major point of difference is that the card data fields are removed, and in their place the cardID, cardKey & cardKeyReplace parameters have been added.
When this method is run, the value of cardKeyReplace will overwrite cardKey - unless a validation error occurs. In short, if the responseCode >= 0, overwrite cardKey in your database with the value you send for cardKeyReplace. Transactions that do not pass pre-validation (responseCode < 0) will not have their cardKey updated.
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. |
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. |
customerName | This field can only contain alphanumeric characters, as well as the full stop, comma, aposprophe, 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. |
cardID | A unique alphanumeric string returned by addCard, used to identify a specific card. |
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 |
---|---|
transactionReferenceID | This is a merchant's unique reference ID for a transaction sent to Merchant Warrior. The main purpose of this ID is to verify the transaction via the queryCard method in the event a valid response is not received. |
recurringFlag | This parameter is used to indicate if a transaction will be marked as recurring. Its value must be 0 or 1. |
threeDSToken | This parameter is used to indicate if a transaction has been authenticated. Its value is returned by checkPARes method. |
customerPhone | Anything other than +,-, space and 0-9 will be stripped. |
customerEmail | Sending this optional parameter is highly recommended. |
customerIP | Any valid IPv4 or IPv6 address is accepted. Sending this optional parameter is highly recommended. |
storeID | The value of this field is the merchant's store name. Please note that you need to contact Merchant Warrior to enable the storeID feature before you can use this parameter. |
cardKey | A string used as an encryption/decryption key. This should be unique on a per-card basis. It's used to encrypt the card when we store it. Every time we receive a process card request, the correct cardkey must also be provided - which is known only by you. |
cardKeyReplace | This will replace cardKey for subsequent requests for the cardID if the transaction is run successfully (meaning accepted by Merchant Warrior, not necessarily approved by the bank). This cannot be the same as the last 10 cardKey's used for the cardID, and it has to follow the same guidelines as cardkey (16 character alphanumeric string, etc). See the explanation under "Request Parameter" for more information. |
paymentCardCSC | This is also known as the CVN or CVV/2. This is required by some Acquirers if the transaction is initiated by the customer. Please contact Merchant Warrior for more information. |
custom1 | Freeform field. Returned as |
custom2 | Freeform field. Returned as |
custom3 | Freeform field. Returned as |
originalTransactionID | Used when processing subsequent transactions. The transaction ID of the first transaction in the series should be used here. |
The processAuth method is the method used to perform a pre-authorization transaction using an existing card (for capture request, refer to the standard processCapture API method). This method proxies the request through to the standard MWE API, and returns the response directly – including any validation or provider errors. That means that all the validation logic is the same with both functions, although this of course also validates cardID, cardKey & cardKeyReplace.
Method Endpoint
This method’s endpoint is: https://<environment>.merchantwarrior.com/token/processAuth
Request-Parameters
These paramaters are practically identical to the Direct API processAuth method. The major point of difference is that the card data fields are removed, and in their place the cardID, cardKey & cardKeyReplace parameters have been added.
When this method is run, the value of cardKeyReplace will overwrite cardKey – unless a validation error occurs. In short, if the responseCode >= 0, overwrite cardKey in your database with the value you send for cardKeyReplace. Transactions that do not pass pre-validation (responseCode < 0) will not have their cardKey updated.
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. |
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. |
customerName | This field can only contain alphanumeric characters, as well as the full stop, comma, aposprophe, 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. |
cardID | A unique alphanumeric string returned by addCard, used to identify a specific card. |
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 |
---|---|
transactionReferenceID | This is a merchant’s unique reference ID for a transaction sent to Merchant Warrior. The main purpose of this ID is to verify the transaction via the queryCard method in the event a valid response is not received. |
threeDSToken | This parameter is used to indicate if a transaction has been authenticated. Its value is returned by checkPARes method. |
customerPhone | Anything other than +,-, space and 0-9 will be stripped. |
customerEmail | Sending this optional parameter is highly recommended. |
customerIP | Any valid IPv4 or IPv6 address is accepted. Sending this optional parameter is highly recommended. |
storeID | The value of this field is the merchant's store name. Please note that you need to contact Merchant Warrior to enable the storeID feature before you can use this parameter. |
cardKey | A string used as an encryption/decryption key. This should be unique on a per-card basis. It’s used to encrypt the card when we store it. Every time we receive a process card request, the correct cardkey must also be provided – which is known only by you. |
cardKeyReplace | This will replace cardKey for subsequent requests for the cardID if the transaction is run successfully (meaning accepted by Merchant Warrior, not necessarily approved by the bank). This cannot be the same as the last 10 cardKey’s used for the cardID, and it has to follow the same guidelines as cardkey (16 character alphanumeric string, etc). See the explanation under “Request Parameter” for more information. |
paymentCardCSC | This is also known as the CVN or CVV/2. This is required by some Acquirers if the transaction is initiated by the customer. Please contact Merchant Warrior for more information. |
custom1 | Freeform field. Returned as |
custom2 | Freeform field. Returned as |
custom3 | Freeform field. Returned as |