Check

Check Processing

The Check web service provides check processing services.


Service Information

Service Endpoint - https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/Check.asmx

Methods

VerifyCheck

The VerifyCheck method performs check verification.

Arguments

Name Type Size Requirement Description
merchantName string 1-160 Mandatory The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 Mandatory The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 Mandatory The software key or password for the site accessing a Merchantware account.
amount string (double) 1-8 Mandatory The face value of the Check.
verificationMethod string (CheckVerificationMethod)   Mandatory The method to be used for verification, e.g. Keyed. This value is case sensitive.
transitNumber string 0 or 9 Depends on Verification Method The 9 digit transit routing number.
accountNumber string 0-18 Depends on Verification Method The check account number.
checkNumber string 0-6 Depends on Verification Method The check sequence number if it appears on check.
micr string 0 or 36 Depends on Verification Method The Transit Routing (fixed 10 characters), Account (fixed 19 characters) and Check (fixed 7 characters) numbers if swiped.
The format is T000000000A000000000000000000C000000 where:
  • T is followed by the 9 digit transit routing number
  • A is followed by the account number left justified and blank-filled (ASCII space character) to the right to 18 characters
  • C is followed by the check sequence number, padded with leading zeros to 6 characters
For checks without a check sequence number, the format is T000000000A000000000000000000.
nameOnCheck string 0-160 Optional The account holder name as written on the Check.
driversLicenseNumber string 0-33 Depends on Verification Method Drivers license number.
socialSecurityNumber string 0 or 9 Optional Social Security number.
dateOfBirth string 0 or 8 Depends on Verification Method Date of birth in the format MMDDYYYY.
stateCode string 0 or 2 Depends on Verification Method The 2 character USA or Canadian driver's license state code, or other ID code.
checkType string (CheckType)   Mandatory The Check type, 'Personal' or 'Company'. This value is case sensitive.

Return Values

A CheckResponse4 is returned.

Notes

When using a Check reader the micr field can be used otherwise the transitNumber, accountNumber and checkNumber fields should be populated. Do not include any prefix characters(T, A or C respectively) when using the individual fields.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Check/VerifyCheck
Sample Request Packet (raw) - Keyed Verification Method
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VerifyCheck xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Check/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>    
      <amount>0.00</amount>
      <verificationMethod>Keyed</verificationMethod>      
      <transitNumber>0000000000</transitNumber>
      <accountNumber>0000000000000000000</accountNumber>
      <checkNumber>0000000</checkNumber>
      <micr/>
      <nameOnCheck>MR A SMITH</nameOnCheck>
      <driversLicenseNumber/>
      <socialSecurityNumber/>
      <dateOfBirth/>
      <stateCode/>
      <checkType>Personal</checkType>
    </VerifyCheck>
  </soap:Body>
</soap:Envelope>
Sample Request Packet (raw) - SwipedWithDriversLicense Verification Method
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VerifyCheck xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Check/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>    
      <amount>0.00</amount>
      <verificationMethod>SwipedWithDriversLicense</verificationMethod>      
      <transitNumber/>
      <accountNumber/>
      <checkNumber/>
      <micr>T000000000A000000000000000000C000000</micr>
      <nameOnCheck/>
      <driversLicenseNumber>000000000000000000000000000000000</driversLicenseNumber>
      <socialSecurityNumber/>
      <dateOfBirth>12311980</dateOfBirth>
      <stateCode>AL</stateCode>
      <checkType>Personal</checkType>
    </VerifyCheck>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VerifyCheckResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Check/VerifyCheck">
      <VerifyCheckResult>
        <ActionDescription>Approve 0000000</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>00000000</AuthorizationCode>
        <ErrorMessage></ErrorMessage>
        <Token>0000000</token>
      </VerifyCheckResult>
    </VerifyCheckResponse>
  </soap:Body>
</soap:Envelope>

Data Structures

CheckResponse4

The CheckResponse4 structure encapsulates the results of a Merchantware VerifyCheck transaction.

Fields

Name Type Description
ActionDescription string Any action message indicated by the verifier. If populated this value should be displayed to the cashier.
ApprovalStatus string The status of the transaction, whether approved or declined. This value may also have other definitions depending on context.
AuthorizationCode string Authorization Code issued by the processor upon receipt of a transaction.
ErrorMessage string A message describing the reason the transaction could not complete.
Token string The identifier received by the Merchantware client when a transaction has been issued. This value may be used to lookup a specific transaction in the history log.

Notes

In the example responses below the VerifyCheckResult is a SOAP moniker for the CheckReponse4 class.

ApprovalStatus currently may contain the values 'APPROVED', 'DECLINED' or 'FAILED'.

An example of an APPROVED response:

<VerifyCheckResponse>
 <VerifyCheckResult>
  <ActionDescription>08 - CHECK WARRANTED - Approve AB1234</ActionDescription>
  <ApprovalStatus>APPROVED</ApprovalStatus>
  <AuthorizationCode>AC1234</AuthorizationCode>
  <ErrorMessage/>
  <Token>123456</Token>
 </VerifyCheckResult>
</VerifyCheckResponse>

An example of a DECLINED response:

<VerifyCheckResponse>
 <VerifyCheckResult>
  <ActionDescription>09 - OVER DAILY LIMIT - Call Center</ActionDescription>
  <ApprovalStatus>DECLINED;1110;duplicate transaction</ApprovalStatus>
  <AuthorizationCode/>
  <ErrorMessage/>
  <Token>123456</Token>
 </VerifyCheckResult>
</VerifyCheckResponse>

An example of a FAILED response:

<VerifyCheckResponse>
  <VerifyCheckResult>
  <ActionDescription/>
  <ApprovalStatus>FAILED;2000;generic host error</ApprovalStatus>
  <AuthorizationCode/>
  <ErrorMessage>Error - Generic Host Error</ErrorMessage>
  <Token/>
 </VerifyCheckResult>
</VerifyCheckResponse>

An example of a server error response:

<VerifyCheckResponse>
 <VerifyCheckResult>
  <ActionDescription/>
  <ApprovalStatus/>
  <AuthorizationCode/>
  <ErrorMessage>transitNumber should be at least 9 to at most 9 characters in size. Parameter name: transitNumber </ErrorMessage>
  <Token/>
 </VerifyCheckResult>
</VerifyCheckResponse>

A detailed explanation of error status values is available here.

References

A CheckResponse4 is returned by these web methods: