Overview

Please note, Vault transaction info has been moved to it's own section but still retains the same endpoint

Merchantware 4 Services

The documentation for Merchantware services is split up among various domains. Here is a list of the various units composing Merchantware:

  • Overview - Enumerations, structures, types, and any other items shared between various Merchantware services.
  • Credit Transactions - Web services providing payment and processing services for both credit and debit cards.
  • Vault Transactions - Web services providing payment and processing services for both credit and debit cards.
  • EBT Transactions - Web services providing payment and processing services for EBT cards.
  • Gift Card Transactions - Web services providing payment and features for gift cards.
  • LevelUp Transactions - Web services providing payment methods and features for LevelUp.
  • Check Transactions - Web services providing payment methods and features for checks.
  • Reporting - Web services to retrieve data from a merchant's transaction history.

Production Service Endpoints

Service Endpoint Address
Credit Transactions  https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/Credit.asmx
Vault Transactions  https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/Credit.asmx
EBT Transactions  https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/Ebt.asmx
Gift Card Transactions  https://ps1.merchantware.net/Merchantware/ws/ExtensionServices/v4/Giftcard.asmx
LevelUp Transactions  https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/LevelUp.asmx
Check Transactions  https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/Check.asmx
Reporting  https://ps1.merchantware.net/Merchantware/ws/TransactionHistory/v4/Reporting.asmx

Enumerations

CheckType

The CheckType enumeration describes the various types of checks that can be handled.

Enumeration Values

NameDescription
PersonalA personal check is being verified/processed.
CompanyA company check is being verified/processed.
Notes

Future updates to the web service may define additional values not listed here.

CheckVerificationMethod

The CheckVerificationMethod enumeration describes the various types of verification methods available. This verification of the data will be performed based on the specified verification method.

Enumeration Values

NameDescription
DriversLicense Specifying this requires the following fields to be provided:
  • Driver’s License Number
  • State Code
  • Date of Birth
Keyed Specifying this requires the following fields to be provided:
  • Transit Routing Number
  • Checking Account Number
  • Check Number
Swiped Specifying this requires the following fields to be provided:
  • MICR
KeyedWithDriversLicense Specifying this requires the following fields to be provided:
  • Transit Routing Number
  • Checking Account Number
  • Check Number
  • Driver’s License Number
  • State Code
  • Date of Birth
SwipedWithDriversLicense Specifying this requires the following fields to be provided:
  • MICR
  • Driver’s License Number
  • State Code
  • Date of Birth
Notes

Future updates to the web service may define additional values not listed here.

EBTBasisType

The EBTBasisType enumeration describes the various types of EBT payment units known to Merchantware. Some of these types may not be available or applicable to your implementation. Also, some of these basis types may not have a cash equivalent.

Enumeration Values

NameValueDescription
Unknown0This value is reserved.
FoodStamp1The EBT payment unit in use represents a quantity of Food Stamps.
CashBenefit2The EBT payment unit in use represents a quantity Cash or a Cash Equivalent.
Notes

This type is not declared as a type native to the web service. Instead, objects using this type store it as an integer. Future updates to the web service may define additional values not listed here. Some methods that use this type may allow use of the keyword instead of the integer value. However, return values from a web method will always use an integer value.

EMVEntryType

The EMVEntryType describes the various type of EMV entry modes available for EmvAuthorize and EmvComplete.

Enumeration Values

NameDescription
CONTACTAn EMV transaction submitted through a chip card reader.
CONTACTLESSAn EMV transaction submitted from a contactless reader.

GiftTransactionType

The GiftTransactionType enumeration describes the various types of gift transactions known to Merchantware. However, some of these transaction types may not be available. For example, some transaction types may be unavailable due to the type of merchant account, Merchantware setup, or type of payment used in a transaction.

Enumeration Values

NameValueDescription
UNKNOWN0This value is reserved.
REDEMPTION1A REDEMPTION decreases an amount of money from a card.
ADDVALUE2A ADDVALUE increases an amount of money to a card.
REDEEMPOINTS3A REDEEMPOINTS decreases an amount of points from a card.
ADDPOINTS4A ADDPOINTS increases an amount of points to a card.
BALANCEINQUIRY5An BALANCEINQUIRY returns a card's amount balance or points balance.
ACTIVATIONPURCHASE6An ACTIVATIONPURCHASE activates and adds an amount of money to a new card.
ACTIVATIONRETURN7An ACTIVATIONRETURN(reserved) is for returned merchandise. Please use ACTIVATIONPURCHASE instead.
CREDIT8A CREDIT(reserved) increases an amount of money to a card. Please use ADDVALUE instead.
BALANCETRANSFER9A BALANCETRANSFER transfers balance from one card to another.
ADDTIP10A ADDTIP adds the amount of tip to a prior transaction.
VOID11A VOID voids a prior transaction.
TOTALSINQUIRY12A TOTALSINQUIRY returns the current day's aggregate totals for each applicable transaction type up to the time of Totals Inquiry.
REDEMPTIONFORCE19A REDEMPTIONFORCE decreases an amount of money from a card. If the balance of the card is less than the amount, the full balance of the card will be used.
Notes

This type is not declared as a type native to the web service. Instead, objects using this type store it as an integer. Future updates to the web service may define additional values not listed here.

CardType

The CardType enumeration describes the various types of cards known to Merchantware. Some of these card types may not be available or applicable to your implementation. Also, some card types may encapsulate other card types due to industry changes. For example, Diner's Club cards are now handled by Mastercard.

Enumeration Values

NameValueDescription
UNKNOWN0This value is reserved.
AMEX1A card issued by American Express.
DISCOVER2A card issued by Discover or by a network affiliated with Discover.
MASTERCARD3A card issued by Mastercard. Diner's Club cards also fall into this category.
VISA4A card issued by Visa.
DEBIT5A debit card, and depending on context, a card supporting debit or a card used for a debit transaction.
EBT6An electronic balance transfer card. These cards are typically issued by government agencies.
EGC7An electronic gift card.
WEX8A fleet card issued by Wright Express.
VOYAGER9A Voyager fleet card, issued by US Bank.
JCB10A card issued by Japan Credit Bureau.
CUP11A China Union Pay credit card.
LVLUP12A LevelUp transaction.
Notes

This type is not declared as a type native to the web service. Instead, objects using this type store it as an integer. Future updates to the web service may define additional values not listed here.

POSEntryType

The POSEntryType enumeration describes the various methods of card data entry for transactions.

Enumeration Values

NameValueDescription
UNKNOWN0This value is reserved.
KEYED1A transaction keyed in using data read by a person off of a card.
SWIPE2A transaction submitted from data swiped through a magnetic reader.
AUTHORIZATION3A transaction keyed in with a phone or offline authorization from a processor.
PROXIMITY4A transaction submitted from a contactless reader.
LVLUP5A transaction submitted via a LevelUp scanner.
Notes

This type is not declared as a type native to the web service. Instead, objects using this type store it as an integer. Future updates to the web service may define additional values not listed here.

In context, the UNKNOWN value is always used if the method of card data entry is irrelevant or unknown. For example, Voided transactions are applied the same way, regardless of how the original transaction was performed, and thus will return UNKNOWN.

SignatureType

The SignatureType enumeration describes the various signature image formats known to Merchantware.

Enumeration Values

NameValueDescription
UNKNOWN0This value is reserved.
TiffZip1A tiff file packaged in a PKZIP-compatible zip file.
VectorText2A string of text containing coordinates defining the ligatures for the signature text.
Notes

This type is not declared as a type native to the web service. Instead, objects using this type store it as an integer. Future updates to the web service may define additional values not listed here.

TransactionType

The TransactionType enumeration describes the various types of transactions known to Merchantware. However, some of these transaction types may not be available. For example, some transaction types may be unavailable due to the type of merchant account, Merchantware setup, or type of payment used in a transaction.

Enumeration Values

NameValueDescription
UNKNOWN0This value is reserved.
SALE1A SALE charges an amount of money to a customer's credit card.
REFUND2A REFUND credits an amount of money to a customer's credit card.
VOID3A VOID removes a SALE, REFUND, FORCE, POSTAUTH, or ADJUST transaction from the current credit card processing batch.
FORCE4A FORCE forces a charge on a customer's credit card. It will not check the balance nor the authorization limit of money on a customer's card.
AUTH5An AUTH reserves or holds an amount of money on a customer's credit card. The amount specified is unavailable for any other purchases until the AUTH expires or a POSTAUTH is issued for the AUTH amount.
CAPTURE6A CAPTURE commits a single transaction as though it were batched. This feature is unsupported and the keyword is reserved for future use.
ADJUST7An ADJUST is an adjustment on the amount of a prior sale or capture. Usually this is employed by restaurants and salons and other businesses where tip-adjust on credit transactions are allowed.
REPEATSALE8A REPEATSALE is a repeated sale of a prior sale transaction. Most accounts and merchants do not use this transaction type.
POSTAUTH9A POSTAUTH completes the transaction process for a prior Authorization and allows it to enter the batch. Once in the batch, a POSTAUTH has no characteristics differing from a SALE other than the transaction type label.
LEVELUPSALE11A LEVELUPSALE charges an amount of money to a customer's LevelUp account.
LEVELUPCREDIT12A LEVELUPCREDIT credits an amount of money to a customer's LevelUp account.

Error Reference

Error Reference Overview

Types of Errors

There are two major types of errors that should be handled when using Merchantware web services.

The first class of errors are those where a given web service call is impossible to complete. These errors become SOAP faults and may be converted into native Exceptions by your development platform. These errors include conditions such as authentication or login failures, validation errors, and system failures. These error conditions are always accompanied by a HTTP error status code such as 400 or 500.

The second class of errors are status errors where the return value of a web service call may be undesirable. Most of these errors come from transaction rejections or failures. Since these errors are not considered service failures, it is up to the consuming application to handle them. The HTTP status code received under these conditions will always be 200.

SOAP Faults & Exceptions

Type Reason
AccessViolationException An Access Violation. A feature or service may be disabled or unavailable for your account.
AuthenticationException Invalid Credentials
ArgumentException Bad argument format, data, or missing parameter.
InvalidOperationException The attempted operation is not allowed or not possible on your account.
Exception General Failure

Reference

AccessViolationException

These exceptions occur whenever an operation is attempted that is unavailable or disabled for your Account. These can be fixed by having your Account reinstated or having the service or feature, that caused these, reinstated.

AuthenticationException

These exceptions occur whenever your credentials fail to validate in Merchantware. To resolve these, check for typos, check for any extra padding characters. Matching of credentials is exact, so any mismatch will cause a failure. This includes invalid characters, upper and lowercase matching.

ArgumentException

Parameters to all web methods are checked for validity. This exception is generated whenever a parameter value is in the wrong format, is missing data, or cannot be converted to the correct type. These exceptions will always contain the name of the parameter that caused the web method failure.

InvalidOperationException

Not all features and capabilities are enabled or available for all accounts. When you receive this exception, check to make sure you are calling the correct web method for the task at hand. Also note that merchants who are migrating from earlier versions of Merchantware may need to have their transaction and service permissions updated.

Exception (Any Unlabeled or Unqualified Exception)

These exceptions should never occur. If you encounter these on a recurring basis, please contact us.

Error Status Information

Basic Transaction and Batch Status Errors

When a transaction or operation is attempted by Merchantware, the return result will contain status keywords followed by extra information. There are seven transaction status keywords defined at this time.

APPROVED

This status keyword indicates that the transaction completed as expected. This status keyword will never have any additional data appended; and any other status keywords encountered may be treated as transaction failures.

SUCCESS

This status keyword indicates that the batch has been committed as expected. This status keyword will never have any additional data appended; just like the APPROVED status.

ACCEPTED

This status keyword indicates that an administrative operation has been completed as expected. This status keyword will never have any additional data appended; just like the APPROVED status.

EMPTY

This status keyword indicates that a batch operation failed because there are no records to be processed. You are free to treat this as a success condition if your point of sale is not concerned about the status of records in a batch.

DECLINED

A decline indicates that a transaction could not be completed. Either the processor rejected the transaction, or there were other failures when attempting to prepare the transaction. This keyword may also be postfixed with the "DUPLICATE" keyword if duplicate transaction protection was triggered.

DUPLICATE

This keyword is appended to a DECLINED status if the transaction failed due to duplicate transaction suppression. Some methods allow you to specify a flag to override this protection, however, some processors may still opt to ignore any value that is set.

REFERRAL

This status keyword indicates a warning and a decline from the processor. The point of sale software should instruct its user to call the processor for further instructions. This status keyword usually indicates cardholder issues such as over-balance limits, fraud, or card cancellation.

FAILED

This status keyword indicates that a transaction or administrative operation encountered a general failure. If you were attempting a transaction, it is safe to assume that the transaction could not be forwarded to the processor, and your point of sale should consider attempting the transaction one more time before giving up.

Extended Transaction and Batch Status Errors

When an error occurs during processing, the status field will also contain an error code and may also have description of the error. Each field is separated by semicolons.

FAILED;99999;undefined error

For some errors, the keyword field may have more than one keyword. When this occurs, each keyword will be separated by commas.

DECLINED,DUPLICATE;1110;duplicate transaction

Defined Error Codes

Here are links to the lists of all the error codes that are defined. Also note that in the future, there may be new codes defined. Your software should always treat any non-zero value as an error, even if the value is not listed here.

Transaction Errors (1000 - 1999)

These error sets may occur during transaction processing. Please note that the error text is subject to change; and may be localized in the future. However, the error codes will not change from their definitions here.

Error Codes

StatusCodeText
APPROVED
FAILED1001user authenticaion failed
DECLINED1002invalid transaction
DECLINED1003invalid transaction type
DECLINED1004invalid amount
DECLINED1005invalid merchant info
DECLINED1007field format error
FAILED1008not a transaction server
DECLINED1009invalid parameter stream
DECLINED1010too many line items
FAILED1011client timeout waiting for response
DECLINED1012
FAILED1012
REFERRAL1013
FAILED1014transaction type not supported by version
DECLINED1019original transaction id not found
DECLINED1020customer ref num not found
DECLINED1022invalid aba num
DECLINED1023invalid account num
DECLINED1024invalid exp date
FAILED1025transaction type not supported by host
DECLINED1026invalid ref num
DECLINED1027invalid receipt info
DECLINED1028invalid check holder name
DECLINED1029invalid check num
DECLINED1030check dl verification requires dl state
FAILED1040transaction did not connect
DECLINED1050insufficient funds available
DECLINED1051voice authorization required
DECLINED1051unable to process
DECLINED1052voice authorization required
DECLINED1052unable to process
DECLINED1053voice authorization required
DECLINED1053unable to process
FAILED1054unable to process
FAILED1099general error
DECLINED1100invalid transaction returned from host
FAILED1101invalid timeout value
FAILED1102processor not available
FAILED1103error reading response
FAILED1104timeout waiting for processor
FAILED1105credit error
FAILED1106host not available
FAILED1107duplicate suppression timeout
FAILED1108void error
FAILED1109timeout waiting for host
DECLINED,DUPLICATE1110duplicate transaction
FAILED1111capture error
DECLINED1112failed avs check
FAILED1113cannot exceed sales cap
FAILED1500payment information not available

Admin Errors (2000-2999)

These error sets may be encountered when processing batches, or during administrative operations such as transaction history or signature capture. Please note that the error text is subject to change; and may be localized in the future. However, the error codes will not change from their definitions here.

Error Codes

StatusCodeText
ACCEPTED
SUCCESS
FAILED2000generic host error
FAILED2001invalid login
FAILED2002insufficient privilege or invalid amount
FAILED2003login blocked
FAILED2004login deactivated
DECLINED2005transaction type not allowed
FAILED2006unsupported processor
DECLINED2007invalid request message
FAILED2008invalid version
DECLINED2010payment type not supported
FAILED2011error starting transaction
FAILED2012error ending transaction
DECLINED2013error checking duplicate
EMPTY2014no records to settle
EMPTY2015no records to process

Vault Errors (3000 - 3999)

These error sets may occur when performing vault management operations such as board credit card or delete token. Please note that the error text is subject to change; and may be localized in the future. However, the error codes will not change from their definitions here.

Error Codes

StatusCodeText
FAILED1500payment information not available
FAILED3001invalid merchant defined token
FAILED3002token already defined

Emv Errors

These error sets may occur during an EmvAuthorize or EmvComplete credit sale. [method] corresponds to either "Authorize" or "Complete"

Error Codes

Error MessageDescription
Credentials were nullNo merchant credentials were passed in the request.
Request was nullNo request XmlDocument was passed in the request.
Unexpected error in EmvServices.Emv[method]()An unexpected error occurred when calling EmvServices.Emv[method] e.g. problems navigating through the Xml request document.
Merchant Account not LoadedUnable to load merchant account using merchant credentials.  Could be caused by a database error or by invalid/inactive credentials.
Unknown error in Emv[method]An unknown error occurred in EmvServices.
$field contains unqualified or invalid dataEnforces that no unusual characters are present in the field.
$field should be at most $fieldMaxLength characters in sizeEnforces the max length of the string value being passed in.
Note you will also get the Soap Error message stating the following:
pinBlock should be at least 1 to at most 100 characters in size.
Parameter name: pinBlock.
$amount could not be recognized as a valid transaction valueParsing of the amount failed, not a value amount.
$field cannot not be nullThrown when a mandatory field is not present in the request.
$field contains invalid dataThrown when a field does not contain correct values.
Argument $field failed to parse to enum type $EnumThrown when the the incoming parameter is not one of the accepted values.

Examples:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <EmvCompleteResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
         <EmvCompleteResult>
            <Status>Error</Status>
            <ErrorMessage>invoiceNumber should be at most 8 characters in size.
Parameter name: invoiceNumber</ErrorMessage>
         </EmvCompleteResult>
      </EmvCompleteResponse>
   </soap:Body>
</soap:Envelope>


<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <EmvCompleteResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/"> <EmvCompleteResult> <Status>Failure</Status> <ErrorMessage>Merchant Account not Loaded</ErrorMessage> </EmvCompleteResult> </EmvCompleteResponse> </soap:Body> </soap:Envelope>


<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <EmvCompleteResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/"> <EmvCompleteResult> <Status>Duplicate</Status> <ErrorMessage>Duplicate EMVComplete message.</ErrorMessage> </EmvCompleteResult> </EmvCompleteResponse> </soap:Body> </soap:Envelope>

LevelUp Errors

These error sets may occur when performing LevelUp operations such as sale and refund. If you encounter these errors, please contact Merchantware customer support.

Errors

Status Text
FAILED An error has occurred while trying to process the Level Up transaction.
FAILED invalid_client
FAILED The email address or password you provided is incorrect.
FAILED Invalid Credentials.

Miscellaneous Errors

These error sets are reserved, and if you encounter them on a regular basis, you should contact us for further investigation. Please note that the error text is subject to change; and may be localized in the future. However, the error codes will not change from their definitions here.

Error Codes

StatusCodeText
FAILED99999host error transaction not processed
FAILED99999payment information not available
FAILED99999undefined error

Code Tables

USA State Codes

These are the supported State Codes for the USA and territories.

State Codes

CodeState
ALAlabama
AKAlaska
AZArizona
ARArkansas
CACalifornia
COColorado
CTConnecticut
DCDistrict of Columbia
DEDelaware
FLFlorida
GAGeorgia
HIHawaii
IDIdaho
ILIllinois
INIndiana
IAIowa
KSKansas
KYKentucky
LALouisiana
MEMaine
MDMaryland
MAMassachusetts
MIMichigan
MNMinnesota
MSMississippi
MOMissouri
MTMontana
NENebraska
NVNevada
NHNew Hampshire
NJNew Jersey
NMNew Mexico
NYNew York
NCNorth Carolina
NDNorth Dakota
OHOhio
OKOklahoma
OROregon
PAPennsylvania
RIRhode Island
SCSouth Carolina
SDSouth Dakota
TNTennessee
TXTexas
UTUtah
VTVermont
VAVirginia
WAWashington
WVWisconsin
WYWyoming
ASAmerican Samoa
GUGuam
PRPuerto Rico
VIU.S. Virgin Islands

Canadian State Codes

These are the supported State Codes for Canada.

State Codes

CodeState
ABAlberta
BCBritish Columbia
MBManitoba
NBNew Brunswick
NFNewfoundland
NTNorthwest Territories
NSNova Scotia
ONOntario
PEPrince Edward Island
PQQuebec
SKSaskatchewan
YTYukon Territory

ID Codes

These are the supported ID type codes.

ID Codes

CodeDescription
CZMilitary ID