MerchantWare 4.6 - Useful Information

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.

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

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)
• Batch & Administrative Errors (2000-2999)
• Vault Errors (1500, 3000-3999)

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

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

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