Check

Service Information

The check web service provides payment processing and methods for checks.

Service Endpoint

https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v45/check.asmx

SOAP Usage and Notices

All examples in this document use SOAP 1.2. Using SOAP 1.2 requires a Content-Type header of “text/xml; charset=utf-8”. Please do not include the SOAPAction header previous used for SOAP 1.1 transactions.

Methods

Verify

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData CheckData A CheckData object containing the Check information.
Request VerificationRequest A VerificationRequest object containing the transnational data required to support Check Verification.

Response

A CheckTransactionResponse45 object is returned.

Example Verify SOAP Request

Sample Request Packet (raw)
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://schemas.merchantwarehouse.com/merchantware/v45/Verify</Action>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Verify xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <Credentials>
        <MerchantName>(merchant name)</MerchantName>
        <MerchantSiteId>(merchant site id)</MerchantSiteId>
        <MerchantKey>(merchant id)</MerchantKey>
      </Credentials>
      <CheckData>
        <Source>Keyed</Source>
        <VerificationMethod>None</VerificationMethod>
        <Token>05944FB3E1DA4663868455AF630F45BE</Token>
        <Check>
          <AccountType>C</AccountType>
          <CheckType>PE</CheckType>
          <NameOnCheck>Test Sage</NameOnCheck>
          <Amount>1.50</Amount>
          <TransitNumber>490000018</TransitNumber>
          <AccountNumber>12345678</AccountNumber>
          <CheckNumber>123</CheckNumber>
          <MICR>T4900000181234567000123</MICR>
        </Check>
        <PersonalData>
          <PhoneNumber>1234567890</PhoneNumber>
          <DateOfBirth>01011990</DateOfBirth>
          <SocialSecurityNumber>1234</SocialSecurityNumber>
        </PersonalData>
        <HomeAddress>
          <StreetAddress1>1 main street</StreetAddress1>
          <StreetAddress2 />
          <City>boston</City>
          <State>FL</State>
          <ZipCode>12345</ZipCode>
        </HomeAddress>
        <DriverLicense>
          <Number />
          <State />
          <CourtesyCardNumber />
        </DriverLicense>
      </CheckData>
      <Request>
        <CheckImages>
          <Front>(image of the front of the check)</Front>
          <Back>(image of the back of the check)</ Back >
        </CheckImages>
      </Request>
    </Verify>
  </s:Body>
</s:Envelope>

Sample Return Packet
<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">
  <s:Header xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" />
  <soap:Body>
    <VerifyResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <VerifyResult>
        <ActionDescription>APPROVAL</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>AUTH NUM 272-172</AuthorizationCode>
        <ErrorMessage />
        <Token>600000536</Token>
      </VerifyResult>
    </VerifyResponse>
  </soap:Body>
</soap:Envelope>

ForceAuthorize

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request ForceAuthorizationRequest A ForceAuthorizationRequest object containing the transactional data required to support Forcing Check Authorization.

Response

A CheckTransactionResponse45 object is returned.

Example ForceAuthorize Request

Sample Request Packet (raw)
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://schemas.merchantwarehouse.com/merchantware/v45/ForceAuthorize</Action>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ForceAuthorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <Credentials>
        <MerchantName>(merchant name)</MerchantName>
        <MerchantSiteId>(merchant site id)</MerchantSiteId>
        <MerchantKey>(merchant id)</MerchantKey>
      </Credentials>
      <Request>
        <Token>600000194</Token>
      </Request>
    </ForceAuthorize>
  </s:Body>
</s:Envelope>
Sample Return Packet
<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">
  <s:Header xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" />
  <soap:Body>
    <ForceAuthorizeResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <ForceAuthorizeResult>
        <ActionDescription>APPROVAL</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>AUTH NUM 272-172</AuthorizationCode>
        <ErrorMessage />
        <Token>600000197</Token>
      </ForceAuthorizeResult>
    </ForceAuthorizeResponse>
  </soap:Body>
</soap:Envelope>

Authorize


Name
Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData CheckData A CheckData object containing the Check information.
Request AuthorizationRequest A CheckData object containing the Check information.

Response

A CheckTransactionResponse45 object is returned.

Sample Authorize SOAP Request

Sample Request Packet (raw)
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://schemas.merchantwarehouse.com/merchantware/v45/Authorize</Action>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Authorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <Credentials>
        <MerchantName>(merchant name)</MerchantName>
        <MerchantSiteId>(merchant site id)</MerchantSiteId>
        <MerchantKey>(merchant id)</MerchantKey>
      </Credentials>
      <CheckData>
        <Source>Reader</Source>
        <VerificationMethod>Identity</VerificationMethod>
        <Token>05944FB3E1DA4663868455AF630F45BE</Token>
        <Check>
          <AccountType>C</AccountType>
          <CheckType>PE</CheckType>
          <NameOnCheck>Test Sage</NameOnCheck>
          <Amount>1.50</Amount>
          <TransitNumber>490000018</TransitNumber>
          <AccountNumber>12345678</AccountNumber>
          <CheckNumber>123</CheckNumber>
          <MICR>T4900000181234567000123</MICR>
        </Check>
        <PersonalData>
          <PhoneNumber>1234567890</PhoneNumber>
          <DateOfBirth>01011990</DateOfBirth>
          <SocialSecurityNumber>1234</SocialSecurityNumber>
        </PersonalData>
        <HomeAddress>
          <StreetAddress1>1 main street</StreetAddress1>
          <StreetAddress2 />
          <City>boston</City>
          <State>FL</State>
          <ZipCode>12345</ZipCode>
        </HomeAddress>
        <DriverLicense>
          <Number />
          <State />
          <CourtesyCardNumber />
        </DriverLicense>
      </CheckData>
      <Request>
        <CheckImages>
          <Front>(image of the front of the check)</Front>
          <Back>(image of the back of the check)</ Back >
        </CheckImages>
      </Request>
    </Authorize>
  </s:Body>
</s:Envelope>
Sample Return Packet
<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">
  <s:Header xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" />
  <soap:Body>
    <AuthorizeResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <AuthorizeResult>
        <ActionDescription>APPROVAL</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>AUTH NUM 272-172</AuthorizationCode>
        <ErrorMessage />
        <Token>600000045</Token>
      </AuthorizeResult>
    </AuthorizeResponse>
  </soap:Body>
</soap:Envelope>

Void

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VoidRequest A VoidRequest object containing the transactional data required to support Check Void.

Response

A CheckTransactionResponse45 object is returned.

Example Void SOAP Request

Sample Request Packet (raw)
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://schemas.merchantwarehouse.com/merchantware/v45/Void</Action>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Void xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <Credentials>
        <MerchantName>(merchant name)</MerchantName>
        <MerchantSiteId>(merchant site id)</MerchantSiteId>
        <MerchantKey>(merchant id)</MerchantKey>
      </Credentials>
      <Request>
        <Token>600000606</Token>
      </Request>
    </Void>
  </s:Body>
</s:Envelope>
Sample Return Packet
<s:Header xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" />
  <soap:Body>
    <VoidResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <VoidResult>
        <ActionDescription>VOID ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>VOID ACCEPTED</AuthorizationCode>
        <ErrorMessage />
        <Token>600000607</Token>
      </VoidResult>
    </VoidResponse>
  </soap:Body>
</soap:Envelope>

Refund

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData CheckData A CheckData object containing the Check data.
Request RefundRequest A RefundRequest object containing the transactional data required to support Check Refund.

Response

A CheckTransactionResponse45 object is returned.

Example Refund SOAP Request

Sample Request Packet
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://schemas.merchantwarehouse.com/merchantware/v45/Refund</Action>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <Credentials>
        <MerchantName>(merchant name)</MerchantName>
        <MerchantSiteId>(merchant site id)</MerchantSiteId>
        <MerchantKey>(merchant id)</MerchantKey>
      </Credentials>
      <CheckData>
        <Source>Reader</Source>
        <VerificationMethod>Identity</VerificationMethod>
        <Token>05944FB3E1DA4663868455AF630F45BE</Token>
        <Check>
          <AccountType>C</AccountType>
          <CheckType>PE</CheckType>
          <NameOnCheck>Test Sage</NameOnCheck>
          <Amount>1.50</Amount>
          <TransitNumber>490000018</TransitNumber>
          <AccountNumber>12345678</AccountNumber>
          <CheckNumber>123</CheckNumber>
          <MICR>T4900000181234567000123</MICR>
        </Check>
        <PersonalData>
          <PhoneNumber>1234567890</PhoneNumber>
          <DateOfBirth>01011990</DateOfBirth>
          <SocialSecurityNumber>1234</SocialSecurityNumber>
        </PersonalData>
        <HomeAddress>
          <StreetAddress1>1 main street</StreetAddress1>
          <StreetAddress2 />
          <City>boston</City>
          <State>FL</State>
          <ZipCode>12345</ZipCode>
        </HomeAddress>
        <DriverLicense>
          <Number />
          <State />
          <CourtesyCardNumber />
        </DriverLicense>
      </CheckData>
      <Request>
        <CheckImages>
          <Front>(image of the front of the check)</Front>
          <Back>(image of the back of the check)</ Back >
        </CheckImages>
      </Request>
    </Refund>
  </s:Body>
</s:Envelope>
Sample Return Packet
<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">
  <s:Header xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" />
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <RefundResult>
        <ActionDescription>REVERSAL ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>REVERSAL ACCEPTED</AuthorizationCode>
        <ErrorMessage />
        <Token>600000360</Token>
      </RefundResult>
    </RefundResponse>
  </soap:Body>

 

Data Structures

MerchantCredentials

Name Type Size Description
MerchantName string 1-160  
MerchantSiteId string 8-160  
MerchantKey string 1-160  

VerificationRequest

Name Type Size Description
RegisterNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
MerchantTransactionId string 0-100 The merchant-defined identifier for the transaction.
InvoiceNumber string 0-8 The invoice or order number associated with the transaction.
CustomerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
PurchaseOrderNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
CheckImages
Front Base64 String Contains the image data for the check front. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb. - max size of 150kb.
 
Back Base64 String Contains the image data for the check back. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb. - max size of 150kb.
 

CheckData

Name Type Size Source Description
CheckData
Source string 1-100 ALL The method used to supply the payment data. See sources listed below.
VerificationMethod string   ALL The method to be used for verification . See Verification methods listed below.
Token string 1-100 PREVIOUSTRANSACTION

Allow for a reference to a previous transaction to be submitted and refund, force or void to take place.  

Note: This is only used when performing a refund indicate refund by reference.

CheckData\Check
AccountType string 1 KEYED + READER Contains the Account Type. Verify against the supported Account Type codes.
CheckType string 2 KEYED + READER Contains the type of Check. Verify against the supported Check Type codes.
NameOnCheck string 0-160 KEYED + READER The account holder name as written on the Check.
Amount string (double) 1-100 KEYED + READER The face value of the check. Positive number only.
TransitNumber string 0 or 9 KEYED The nine digit transit routing number.
AccountNumber string 0-18 KEYED The check account number.
CheckNumber string 0-6 KEYED The check sequence number if it appears on check.
MICR string 0-100 READER Contains the Raw MICR data with TOAD substitution and spaces preserved. The Transit symbol will have been replaced with the letter 'T' in either upper or lower case.
The On-US symbol will have been replaced with the letter 'O' in either upper or lower case.
The Amount symbol will have been replaced with the letter 'A' in either upper or lower case.
The Dash symbol will have been replaced with the letter 'D' in either upper or lower case.
CheckData\PersonalData
PhoneNumber string 0-100 ALL The consumer’s contact phone number. The phone number is expected as a 10 digit number without a – or ().
DateOfBirth string 0-8 ALL Date of birth in the format MMDDYYYY.
SocialSecurityNumber string 0-9 ALL Social Security number.
CheckData\PersonalData
StreetAddress1 string 0-200 ALL The first line of the consumer's address.
StreetAddress2 string 0-200 ALL The second line of the consumer's address.
City string 0-50 ALL The city of the consumer's address.
State string 0 or 2 ALL Contains the state or province code of the customer's address. Ensure that the state is validated against the supported US States, Canadian Provinces and Territories and ID Type codes.
ZipCode string 0-5 ALL ZIP code of the consumer's address.
CheckData\DriverLicense
Number string 0-33 ALL Driver license number.
State string 0 or 2 ALL Contains the consumer's driver license state or province code. Ensure that the state is validated against the supported US StatesCanadian Provinces and Territories and ID Type codes.
CourtesyCardNumber string 0-50 ALL Contains the customer's Courtesy Card Number.

ForceAuthorizationRequest

Name Type Size Description
RegisterNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
MerchantTransactionId string 0-100 The merchant-defined identifier for the transaction.
InvoiceNumber string 0-8 The invoice or order number associated with the transaction.
CustomerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
PurchaseOrderNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
Token string 1-100 Allow for a reference to a previous transaction to be submitted and refund, force or void to take place.

AuthorizationRequest

Name
Type
Size
Description
RegisterNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
MerchantTransactionId string 0-100 The merchant-defined identifier for the transaction.
InvoiceNumber string 0-8 The invoice or order number associated with the transaction.
CustomerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
PurchaseOrderNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
RecurringCheck string (bool) 0-5 Contains an indicator to the transaction being recurring. A transaction cannot be forced when it's recurring and cannot be have a payroll check type.
CheckImages
CheckImages\Front Base64 String   Contains the image data for the check front. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb.
CheckImages\Back Base64 String   Contains the image data for the check back. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb.

VoidRequest

Name Type Size Description
Token string 1-100 Allow for a reference to a previous transaction to be submitted and refund, force or void to take place.
RegisterNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
MerchantTransactionId string 0-100 The merchant-defined identifier for the transaction.

RefundRequest

Name Type Size Description
RegisterNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
MerchantTransactionId string 0-100 The merchant-defined identifier for the transaction.
InvoiceNumber string 0-8 The invoice or order number associated with the transaction.
CustomerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
PurchaseOrderNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
CheckImages
CheckImages\Front Base64 String   Contains the image data for the check front. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb.
CheckImages\Back Base64 String   Contains the image data for the check back. The image:
  • Either tiff or png;
  • Dimensions of 800 X 600
  • Resolution of 200dpi
  • Color depth of one bit (black and white);
  • base64 encrypted
  • Preferably under 100kb.

CheckResponse45

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.

Source

Name Description
Reader The following information to be provided:
  • MICR
  • Transit Number
  • Account Number
  • Check Number
Keyed The following information to be provided:
  • Transit Number
  • Account Number
  • Check Number
Where the Check is marked as recurring do not provide Check Number.
PreviousTransaction The following information to be provided:
  • Token

VerificationMethod

Name Description
DriverLicense Specifying this requires the following information to be provided:
  • Driver’s License Details
Identity Specifying this requires the following information to be provided:
  • Personal Data
  • Home Address
IdentityDriverLicense  Specifying this requires the following information to be provided:
  • Personal Data
  • Home Address
  • Driver’s License Details
None  If neither DriverLicense nor Identity are required.

Check Type

Code Check Type
PE Personal
CO Company
PA Payroll

US States

Code
State
AL Alabama
AK Alaska
AZ Arizona
AR Arkansas
CA California
CO Colorado
CT Connecticut
DE Delaware
DC District of Columbia
FL Florida
GA Georgia
HI Hawaii
ID Idaho
IL Illinois
IN Indiana
IA Iowa
KS Kansas
KY Kentucky
LA Louisiana
ME Maine
MD Maryland
MA Massachusetts
MI Michigan
MN Minnesota
MS Mississippi
MO Missouri
MT Montana
NE Nebraska
NV Nevada
NH New Hampshire
NJ New Jersey
NM New Mexico
NY New York
NC North Carolina
ND North Dakota
OH Ohio
OK Oklahoma
OR Oregon
PA Pennsylvania
RI Rhode Island
SC South Carolina
SD South Dakota
TN Tennessee
TX Texas
UT Utah
VT Vermont
VA Virginia
WA Washington
WV West Virginia
WI Wisconsin
WY Wyoming
AS American Samoa
GU Guam
PR Puerto Rico
VI Virgin Islands

Canadian Provinces and Territories

Code Province\Territory
AB Alberta
BC British Columbia
MB Manitoba
NB New Brunswick
NF Newfoundland
NT Northwest Territories
NS Nova Scotia
NU Nunavut
ON Ontario
PE Prince Edward Island
QC Quebec
SK Seskatchewan
YT Yukon Territory

ID Types

Code
ID Type
AA Armed Forces Americas
AE Armed Forces Europe
AP Armed Forces Pacific

Account Types

Code Account Type
S Savings
C Checking

Error Responses

Response Message
General_Error Processing Error
Error_Reading_Response_From_Host Request timed out at Processor
Host_Not_Available Communication Error
Invalid_Merchant_Info Terminal Settings Error
Invalid_Request_Msg Unable to build data packet from request
Invalid_Transaction_type Invalid transaction type
OK  
Declined