Merchantware 4.6

Reasons for Storing Card Details or Using Stored Card Details

The POS must send a StoredCardReason when:

  • Storing a cardholder’s card details in the vault
  • Using a vault token to run a transaction

The StoredCardReason must be one of the following values:

  • RECURRING
  • INSTALLMENT
  • UNSCHEDULEDMIT
  • UNSCHEDULEDCIT

When a POS sends a request to store a cardholder’s card details in the vault, the value for StoredCardReason describes the intended use for stored card details.

When a POS uses a vault token to run a transaction, the value for StoredCardReason describes why the vault token is being used. The value for StoredCardReason does not need to match the value supplied by the POS when the card was saved to the vault by the gateway.

Note: When the POS sends a Refund request, the value for StoredCardReason must be either UNSCHEDULEDMIT or UNSCHEDULEDCIT.

Description of the StoredCardReason values

RECURRING

The transaction relates to a recurring payment schedule for a cardholder, with no predefined end date. For example, if the cardholder subscribes to a service that they pay for monthly that continues until the merchant ends the recurrence, or the card expires.

You must include a function on the POS to allow merchants to manually end the recurring transactions.

INSTALLMENT

The transaction relates to an installment payment schedule for a cardholder, with a set number of installments that add up to a predefined total. For example, a cardholder arranges with the merchant to pay for a product in a total of 12 monthly installments.

If the POS sends INSTALLMENT as the StoredCardReason it must also include the following fields and values:

  • BillingSequenceNumber – The sequence number of the current installment in the cardholder’s installment plan.
  • BillingSequenceCount – The total number of installments in the cardholder’s installment plan.
UNSCHEDULEDMIT

The merchant uses a stored card for a transaction that is not part of a recurring payment schedule or an installment payment schedule. For example, when the merchant issues a refund to a card.

UNSCHEDULEDCIT

The cardholder initiates a transaction that is not part of a recurring billing schedule or an installment billing schedule. For example, the cardholder uses their stored card in the merchant’s online store to purchase an item.

Errors

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

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

Status Code Text
APPROVED    
FAILED 1001 user authenticaion failed
DECLINED 1002 invalid transaction
DECLINED 1003 invalid transaction type
DECLINED 1004 invalid amount
DECLINED 1005 invalid merchant info
DECLINED 1007 field format error
FAILED 1008 not a transaction server
DECLINED 1009 invalid parameter stream
DECLINED 1010 too many line items
FAILED 1011 client timeout waiting for response
DECLINED 1012  
FAILED 1012  
REFERRAL 1013  
FAILED 1014 transaction type not supported by version
DECLINED 1019 original transaction id not found
DECLINED 1020 customer ref num not found
DECLINED 1022 invalid aba num
DECLINED 1023 invalid account num
DECLINED 1024 invalid exp date
FAILED 1025 transaction type not supported by host
DECLINED 1026 invalid ref num
DECLINED 1027 invalid receipt info
DECLINED 1028 invalid check holder name
DECLINED 1029 invalid check num
DECLINED 1030 check dl verification requires dl state
FAILED 1040 transaction did not connect
DECLINED 1050 insufficient funds available
DECLINED 1051 voice authorization required
DECLINED 1051 unable to process
DECLINED 1052 voice authorization required
DECLINED 1052 unable to process
DECLINED 1053 voice authorization required
DECLINED 1053 unable to process
FAILED 1054 unable to process
FAILED 1099 general error
DECLINED 1100 invalid transaction returned from host
FAILED 1101 invalid timeout value
FAILED 1102 processor not available
FAILED 1103 error reading response
FAILED 1104 timeout waiting for processor
FAILED 1105 credit error
FAILED 1106 host not available
FAILED 1107 duplicate suppression timeout
FAILED 1108 void error
FAILED 1109 timeout waiting for host
DECLINED,DUPLICATE 1110 duplicate transaction
FAILED 1111 capture error
DECLINED 1112 failed avs check
FAILED 1113 cannot exceed sales cap
DECLINED 1114 failed cvv check
FAILED 1500 payment information not available

Admin errors

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
Status Code Text
ACCEPTED    
SUCCESS    
FAILED 2000 generic host error
FAILED 2001 invalid login
FAILED 2002 insufficient privilege or invalid amount
FAILED 2003 login blocked
FAILED 2004 login deactivated
DECLINED 2005 transaction type not allowed
FAILED 2006 unsupported processor
DECLINED 2007 invalid request message
FAILED 2008 invalid version
DECLINED 2010 payment type not supported
FAILED 2011 error starting transaction
FAILED 2012 error ending transaction
DECLINED 2013 error checking duplicate
EMPTY 2014 no records to settle
EMPTY 2015 no records to process

Vault errors

These error sets may occur when performing vault management operations. 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
Status Code Text
FAILED 1500 payment information not available
FAILED 3001 invalid merchant defined token
FAILED 3002 token already defined