Token Payments

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

Endpoints

Sandbox
POST https://base.merchantwarrior.com/token/ Copy

Production
POST https://api.merchantwarrior.com/token/ Copy

Introduction

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.

Key Management

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

addCard

The addCard method is used to add a new card to the MW Vault

Required Parameters

Parameter Description
method

This field is case sensitive.
Example: addCard

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.
Example: Mr. Example Person or MR E PERSON or Example Person
Valid length: Between 3 and 255 characters

cardNumber

Example: 5123456789012346 or 4557012345678902
Valid length: Between 13 and 16 digits

cardExpiryMonth

This must be MM format. The month must be zero padded if it is less than 10.
Example: 05
Valid length: 2 digits

cardExpiryYear

This must be YY format.
Example: 13
Valid length: 2 digits

Conditional Parameters

Parameter Description
merchantUUID

The value of this parameter is provided to you by Merchant Warrior.
Example: 123456789abcd
Required: If accessToken is not used.

apiKey

The value of this parameter is provided to you by Merchant Warrior.
Example: 1a3b5c
Required: If accessToken is not used.

accessToken

A single use access token, used in place of your merchant credentials.
Example: 82cea7c4f7
Required: If merchantUUID and apiKey is not used.

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.
Example: 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.
Example: 123
Valid length: Between 3 and 4 characters

removeCard

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

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

cardID

A unique alphanumeric string returned by addCard, used to identify a specific card.
Example: NUFM56937091

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.
Example: a84JI2cA12ziZ3Fx
Valid length: 16 characters

cardInfo

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

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

cardID

A unique alphanumeric string returned by addCard, used to identify a specific card.
Example: NUFM56937091

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.
Example: a84JI2cA12ziZ3Fx
Valid length: 16 characters

changeExpiry

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

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

cardID

A unique alphanumeric string returned by addCard, used to identify a specific card.
Example: NUFM56937091

cardExpiryMonth

This must be MM format. The month must be zero padded if it is less than 10.
Example: 05
Valid length: 2 digits

cardExpiryYear

This must be YY format.
Example: 13
Valid length: 2 digits

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.
Example: a84JI2cA12ziZ3Fx
Valid length: 16 characters

processCard

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.
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.

customerName

This field can only contain alphanumeric characters, as well as the full stop, comma, aposprophe, 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

cardID

A unique alphanumeric string returned by addCard, used to identify a specific card.
Example: NUFM56937091

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
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.
Example: A257240023321
Valid length: Up to 40 characters

recurringFlag

This parameter is used to indicate if a transaction will be marked as recurring. Its value must be 0 or 1.
Example: 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.
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

customerIP

Any valid IPv4 or IPv6 address is accepted. Sending this optional parameter is highly recommended.
Example: 123.456.789.012 or 2001:0db8:85a3:0000:0000:8a2e:0370:7334
Valid length: Up to 39 characters

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.
Example: Test store name

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.
Example: a84JI2cA12ziZ3Fx
Valid Length: 16 characters

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.
Example: mbnGHOq86sXTjQgd
Valid Length: 16 characters

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.
Example: 123
Valid length: Between 3 and 4 characters

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

originalTransactionID

Used when processing subsequent transactions. The transaction ID of the first transaction in the series should be used here.
Example: 46871-c26f007a-49fa-4cf9-80f4-52ca55d4fcbc

processAuth


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

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.

customerName

This field can only contain alphanumeric characters, as well as the full stop, comma, aposprophe, 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

cardID

A unique alphanumeric string returned by addCard, used to identify a specific card.
Example: NUFM56937091

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
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.
Example: A257240023321
Valid length: Up to 40 characters

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.
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

customerIP

Any valid IPv4 or IPv6 address is accepted. Sending this optional parameter is highly recommended.
Example: 123.456.789.012 or 2001:0db8:85a3:0000:0000:8a2e:0370:7334
Valid length: Up to 39 characters

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.
Example: Test store name

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.
Example: a84JI2cA12ziZ3Fx
Valid Length: 16 characters

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.
Example: mbnGHOq86sXTjQgd
Valid Length: 16 characters

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.
Example: 123
Valid length: Between 3 and 4 characters

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