Merchantware 4.5

Note: Documentation for MerchantWare 4.0 is available here

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 previously 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>Zero Inc</MerchantName>
        <MerchantSiteId>00000000</MerchantSiteId>
        <MerchantKey>00000-00000-00000-00000-00000</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>Zero Inc</MerchantName>
        <MerchantSiteId>00000000</MerchantSiteId>
        <MerchantKey>00000-00000-00000-00000-00000</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

Sends an authorization request for a check or ACH transaction.

There are several steps to the ACH process, which means that ACH transactions do not clear instantly. The ACH process is as follows:

  1. The merchant sends a transaction request to their processor. 
  2. The processor initially approves or declines the transaction. 
  3. The processor sends transactions it approves to the clearing house, as part of its daily batch. 
  4. The clearing house confirms that the customer can successfully make the payment. 
    • If the payment is successful, the ACH approves the transaction and send the funds to the merchant's bank.
    • If the payment is unsuccessful, the ACH sends back an ACH return code to explain why they couldn't process the payment. Depending on the code the merchant receives, they may need to run the transaction again or contact the customer to provide an alternative payment method. You can view unsuccessful transactions by running the AchReturns report.

Name
Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData CheckData An object containing the checking account and customer data you want to store in the vault.
Request AuthorizationRequest An object containing the data about the transaction.

Notes

  • Merchantware ignores the VaultToken in your request if you do not send "Vault" as the Source.
  • Merchantware returns RecurringCheck only if you supply VaultToken.
  • Do not send CheckImages for recurring check transactions.
  • You receive the following in the response only if the transaction is approved and the Source is "Vault":
    • CheckData
    • MerchantVaultTokenReference
    • MerchantTransactionId
    • RecurringCheck

Response

A CheckTransactionResponse45 object is returned.

Sample Keyed Authorize SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
   <soap:Header/>
   <soap:Body>
      <Authorize>
         <Credentials>
            <MerchantName>TEFNorthSageMultiSEC</MerchantName>
            <MerchantSiteId>Z7UV7DJ5</MerchantSiteId>
            <MerchantKey>NJKGQ-GGDOX-IDFHL-AYSK7-TWMKQ</MerchantKey>
         </Credentials>
         <CheckData>
            <Source>Keyed</Source>
            <VerificationMethod>IdentityDriverLicense</VerificationMethod>
            <Check>
               <AccountType>C</AccountType>
               <CheckType>PE</CheckType>
               <NameOnCheck>Test Sage</NameOnCheck>
               <Amount>1.50</Amount>
               <TransitNumber>490000018</TransitNumber>
               <AccountNumber>12345678</AccountNumber>
               <CheckNumber>12345</CheckNumber>
            </Check>
            <PersonalData>
               <PhoneNumber>1234567890</PhoneNumber>
               <DateOfBirth>11112011</DateOfBirth>
               <SocialSecurityNumber>123456789</SocialSecurityNumber>
            </PersonalData>
            <HomeAddress>
               <StreetAddress1>123 Test Avenue</vStreetAddress1>
               <StreetAddress2>Apt. B</StreetAddress2>
               <City>Boston</City>
               <State>MA</State>
               <ZipCode>12345</ZipCode>
            </HomeAddress>
            <DriverLicense>
               <Number>123456789012345678901234567890123</Number>
               <State>AZ</State>
               <CourtesyCardNumber>123456789012345678901234567890123</CourtesyCardNumber>
            </DriverLicense>
         </CheckData>
         <Request>
            <RegisterNumber>1</RegisterNumber>
            <MerchantTransactionId>1</MerchantTransactionId>
            <InvoiceNumber>1</InvoiceNumber>
            <RecurringCheck>false</RecurringCheck>
            <PurchaseOrderNumber>1</PurchaseOrderNumber>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <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>600008631</Token>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

Sample Reader Authorize SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
   <soap:Header/>
   <soap:Body>
      <Authorize>
         <Credentials>
            <MerchantName>TEFNorthSageMultiSEC</MerchantName>
            <MerchantSiteId>Z7UV7DJ5</MerchantSiteId>
            <MerchantKey>NJKGQ-GGDOX-IDFHL-AYSK7-TWMKQ</MerchantKey>
         </Credentials>
         <CheckData>
            <Source>Reader</Source>
            <VerificationMethod>IdentityDriverLicense</VerificationMethod>
            <Check>
               <AccountType>C</AccountType>
               <CheckType>PE</CheckType>
               <NameOnCheck>Test Sage</NameOnCheck>
               <Amount>1.50</Amount>
               <TransitNumber>490000018</TransitNumber>
               <AccountNumber>12345678</AccountNumber>
               <CheckNumber>12345</CheckNumber>
               <MICR>T490000018A12345678D12345</MICR>
            </Check>
            <PersonalData>
               <PhoneNumber>1234567890</PhoneNumber>
               <DateOfBirth>11112011</DateOfBirth>
               <SocialSecurityNumber>123456789</SocialSecurityNumber>
            </PersonalData>
            <HomeAddress>
               <StreetAddress1>123 Test Avenue</StreetAddress1>
               <StreetAddress2>Apt. B</StreetAddress2>
               <City>Boston</City>
               <State>MA</State>
               <ZipCode>12345</ZipCode>
            </HomeAddress>
            <DriverLicense>
               <Number>123456789012345678901234567890123</Number>
               <State>AZ</State>
               <CourtesyCardNumber>123456789012345678901234567890123</CourtesyCardNumber>
            </DriverLicense>
         </CheckData>
         <Request>
            <RegisterNumber>1</RegisterNumber>
            <MerchantTransactionId>1</MerchantTransactionId>
            <InvoiceNumber>1</InvoiceNumber>
            <RecurringCheck>false</RecurringCheck>
            <PurchaseOrderNumber>1</PurchaseOrderNumber>
            <CheckImages>
                <Front>(PRESENT)</Front>
                <Back>(PRESENT)</Back>
            </CheckImages>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <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>600008637</Token>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

Sample Vault Authorize SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
   <soap:Header/>
   <soap:Body>
      <Authorize>
         <Credentials>
            <MerchantName>TEFNorthSageMultiSEC</MerchantName>
            <MerchantSiteId>Z7UV7DJ5</MerchantSiteId>
            <MerchantKey>NJKGQ-GGDOX-IDFHL-AYSK7-TWMKQ</MerchantKey>
         </Credentials>
         <CheckData>
            <Source>Vault</Source>
            <VaultToken>10000010000128OCIAIX</VaultToken>
            <Check>
               <Amount>1.50</Amount>
            </Check>
         </CheckData>
         <Request>
            <RegisterNumber>1</RegisterNumber>
            <MerchantTransactionId>1</MerchantTransactionId>
            <InvoiceNumber>1</InvoiceNumber>
            <RecurringCheck>false</RecurringCheck>
            <PurchaseOrderNumber>1</PurchaseOrderNumber>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <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>600008641</Token>
            <CheckData>
               <Source>Vault</Source>
               <VerificationMethod>IdentityDriverLicense</VerificationMethod>
               <Check>
                  <AccountType>C</AccountType>
                  <CheckType>PE</CheckType>
                  <NameOnCheck>Test Sage</NameOnCheck>
                  <Amount>1.50</Amount>
                  <TransitNumber>*****0018</TransitNumber>
                  <AccountNumber>****5678</AccountNumber>
               </Check>
               <PersonalData>
                  <PhoneNumber>****7890</PhoneNumber>
                  <SocialSecurityNumber>*****6789</SocialSecurityNumber>
               </PersonalData>
               <HomeAddress>
                  <StreetAddress1>123 Test Avenue</StreetAddress1>
                  <StreetAddress2>Apt. B</StreetAddress2>
                  <City>Boston</City>
                  <State>MA</State>
                  <ZipCode>12345</ZipCode>
               </HomeAddress>
               <DriverLicense>
                  <Number>*****************************0123</Number>
                  <State>AZ</State>
               </DriverLicense>
            </CheckData>
            <RecurringCheck>false</RecurringCheck>
            <MerchantTransactionId>1</MerchantTransactionId>
            <MerchantVaultTokenReference>MyReference</MerchantVaultTokenReference>
         </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>Zero Inc</MerchantName>
        <MerchantSiteId>00000000</MerchantSiteId>
        <MerchantKey>00000-00000-00000-00000-00000</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

Refunds a transaction.

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData CheckData An object containing data about the checking account and the customer.
Request RefundRequest An object containing data about the transaction.

Notes

  • Merchantware ignores the VaultToken in your request if you do not send "Vault" as the Source.
  • You receive the following in the response only if the transaction is approved and the Source is "Vault":
    • CheckData
    • MerchantVaultTokenReference
    • MerchantTransactionId

Response

A CheckTransactionResponse45 object is returned.

Example Keyed Refund SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
  <soap:Body>
    <Refund>
      <Credentials>
        <MerchantName>TEFNorthSageMultiSEC</MerchantName>
        <MerchantSiteId>HIRT6K12</MerchantSiteId>
        <MerchantKey>TRJN7-80A3C-RA8T1-6USAT-HTZUV</MerchantKey>
      </Credentials>
      <CheckData>
        <Source>Keyed</Source>
        <VerificationMethod>IdentityDriverLicense</VerificationMethod>
        <Check>
          <AccountType>C</AccountType>
          <CheckType>PE</CheckType>
          <NameOnCheck>Test Sage</NameOnCheck>
          <Amount>1.50</Amount>
          <TransitNumber>490000018</TransitNumber>
          <AccountNumber>12345678</AccountNumber>
          <CheckNumber>12345</CheckNumber>
        </Check>
        <PersonalData>
          <PhoneNumber>1234567890</PhoneNumber>
          <DateOfBirth>09161993</DateOfBirth>
          <SocialSecurityNumber>123456789</SocialSecurityNumber>
        </PersonalData>
        <HomeAddress>
          <StreetAddress1>123 Test Avenue</StreetAddress1>
          <City>Boston</City>
          <State>MA</State>
          <ZipCode>12345</ZipCode>
        </HomeAddress>
        <DriverLicense>
          <Number>123456789</Number>
          <State>FL</State>
          <CourtesyCardNumber>123456789</CourtesyCardNumber>
        </DriverLicense>
      </CheckData>
      <Request>
        <RegisterNumber>1</RegisterNumber>
        <MerchantTransactionId>1</MerchantTransactionId>
        <InvoiceNumber>1</InvoiceNumber>
        <PurchaseOrderNumber>1</PurchaseOrderNumber>
      </Request>
    </Refund>
  </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <RefundResult>
        <ActionDescription>REVERSAL ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>REVERSAL ACCEPTED</AuthorizationCode>
        <ErrorMessage/>
        <Token>600004614</Token>        
      </RefundResult>
    </RefundResponse>
  </soap:Body>
</soap:Envelope>

Example Reader Refund SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
    <soap:Body>
      <Refund>
        <Credentials>
          <MerchantName>TEFNorthSageMultiSEC</MerchantName>
          <MerchantSiteId>HIRT6K12</MerchantSiteId>
          <MerchantKey>TRJN7-80A3C-RA8T1-6USAT-HTZUV</MerchantKey>
        </Credentials>
        <CheckData>
          <Source>Reader</Source>
          <VerificationMethod>IdentityDriverLicense</VerificationMethod>
          <Check>
            <AccountType>C</v45:AccountType>
            <CheckType>PE</v45:CheckType>
            <NameOnCheck>Test Sage</NameOnCheck>
            <Amount>1.50</v45:Amount>
            <TransitNumber>490000018</TransitNumber>
            <AccountNumber>12345678</AccountNumber>
            <CheckNumber>12345</CheckNumber>
            <MICR>T490000018A12345678D12345</MICR>
          </Check>
          <PersonalData>
            <PhoneNumber>1234567890</PhoneNumber>
            <DateOfBirth>09161993</DateOfBirth>
            <SocialSecurityNumber>123456789</SocialSecurityNumber>
          </PersonalData>
          <HomeAddress>
            <StreetAddress1>123 Test Avenue</StreetAddress1>
            <City>Boston</City>
            <State>MA</State>
            <ZipCode>12345</ZipCode>
          </HomeAddress>
          <DriverLicense>
            <Number>123456789</Number>
            <State>FL</State>
            <CourtesyCardNumber>123456789</CourtesyCardNumber>
          </DriverLicense>
        </CheckData>
        <Request>
          <RegisterNumber>1</RegisterNumber>
          <MerchantTransactionId>1</MerchantTransactionId>
          <InvoiceNumber>1</InvoiceNumber>
          <PurchaseOrderNumber>1</PurchaseOrderNumber>
          <CheckImages>
            <Front>(Present)</Front>
            <Back>(Present)</Back>
          </CheckImages>
        </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <RefundResult>
        <ActionDescription>REVERSAL ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>REVERSAL ACCEPTED</AuthorizationCode>
        <ErrorMessage/>
        <Token>600004639</Token>
      </RefundResult>
    </RefundResponse>
 </soap:Body>
</soap:Envelope>

Example PreviousTransaction Refund SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
  <soap:Body>
    <Refund>
      <Credentials>
        <MerchantName>TEFNorthSageMultiSEC</MerchantName>
        <MerchantSiteId>3R3Z8MUT</MerchantSiteId>
        <MerchantKey>IR67X-1SXPE-EM4HX-88QRI-6ZP4D</MerchantKey>
      </Credentials>
      <CheckData>
        <Source>PreviousTransaction</Source>
        <Token>600008638</Token>
        <Check>
          <Amount>1.50</Amount>
        </Check>
      </CheckData>
      <Request>
        <RegisterNumber>1</RegisterNumber>
        <MerchantTransactionId>1</MerchantTransactionId>
        <InvoiceNumber>1</InvoiceNumber>
        <PurchaseOrderNumber>1</PurchaseOrderNumber>
      </Request>
    </Refund>
  </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <RefundResult>
        <ActionDescription>REVERSAL ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>REVERSAL ACCEPTED</AuthorizationCode>
        <ErrorMessage/>
        <Token>600008639</Token>
      </RefundResult>
    </RefundResponse>
  </soap:Body>
</soap:Envelope>

Example Vault Refund SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
    <soap:Body>
      <Refund>
        <Credentials>
          <MerchantName>TEFNorthSageMultiSEC</MerchantName>
          <MerchantSiteId>HIRT6K12</MerchantSiteId>
          <MerchantKey>TRJN7-80A3C-RA8T1-6USAT-HTZUV</MerchantKey>
        </Credentials>
        <CheckData>
          <Source>Vault</Source>
          <VaultToken>100000100000E8L9V4SS</VaultToken>
          <Check>
            <Amount>1.50</Amount>
          </Check>
        </CheckData>
        <Request>
          <RegisterNumber>1</RegisterNumber>
          <MerchantTransactionId>1</MerchantTransactionId>
          <InvoiceNumber>1</InvoiceNumber>
          <PurchaseOrderNumber>1</PurchaseOrderNumber>
        </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <RefundResult>
        <ActionDescription>REVERSAL ACCEPTED</ActionDescription>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>REVERSAL ACCEPTED</AuthorizationCode>
        <ErrorMessage/>
        <Token>600004721</Token>
        <CheckData>
          <Source>Vault</Source>
          <VerificationMethod>None</VerificationMethod>
          <Check>
            <AccountType>C</AccountType>
            <CheckType>PE</CheckType>
            <NameOnCheck>Test Sage</NameOnCheck>
            <Amount>1.50</Amount>
            <TransitNumber>*****0018</TransitNumber>
            <AccountNumber>****5678</AccountNumber>
          </Check>
          <PersonalData>
            <PhoneNumber>******7890</PhoneNumber>
            <SocialSecurityNumber>*****6789</SocialSecurityNumber>
          </PersonalData>
          <HomeAddress>
            <StreetAddress1>123 Test Avenue</StreetAddress1>
            <StreetAddress2>Apt. B</StreetAddress2>
            <City>Boston</City>
            <State>MA</State>
            <ZipCode>12345</ZipCode>
          </HomeAddress>
          <DriverLicense>
            <Number>*****************************0123</Number>
            <State>AZ</State>
          </DriverLicense>
        </CheckData>
        <MerchantTransactionId>1</MerchantTransactionId>
        <MerchantVaultTokenReference>MyReference</MerchantVaultTokenReference>
      </RefundResult>
    </RefundResponse>
  </soap:Body>
</soap:Envelope>

BoardAccount

Stores the details of a customer's checking account to the vault. We refer to this as boarding an account. If you successfully send this request, you receive a VaultToken that represents the data you sent to the vault. You can then send the VaultToken in future requests instead of sending the individual parameters in the CheckData object. You can board the same checking account to the vault multiple times, but you receive a unique token for the account each time you board it.

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
CheckData VaultCheckData An object containing the checking account and customer data you want to store in the vault.
Request BoardingRequest An object containing the MerchantVaultTokenReference.

Notes

  • You must supply a CheckType that matches the type of check a merchant's account is set up to accept. For example, if a merchant's account is set up to run only personal transactions, the CheckType must be "PE".
  • The MerchantVaultTokenReference is a parameter that a merchant can use to add a tag to an account. The merchant can add the same tag to many accounts so that they can group transactions.

Response

A CheckVaultBoardingResponse45 object is returned.

Example BoardAccount SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
   <soap:Header/>
   <soap:Body>
      <BoardAccount>
         <Credentials>
            <MerchantName>TEFNorthSageMultiSEC</MerchantName>
            <MerchantSiteId>Z7UV7DJ5</MerchantSiteId>
            <MerchantKey>NJKGQ-GGDOX-IDFHL-AYSK7-TWMKQ</MerchantKey>
         </Credentials>
         <CheckData>
            <VerificationMethod>IdentityDriverLicense</VerificationMethod>
            <Check>
               <AccountType>C</AccountType>
               <CheckType>PE</CheckType>
               <NameOnCheck>Test Sage</NameOnCheck>
               <AccountNumber>12345678</AccountNumber>
               <TransitNumber>490000018</TransitNumber>
            </Check>
            <PersonalData>
               <PhoneNumber>1234567890</PhoneNumber>
               <DateOfBirth>01011990</DateOfBirth>
               <SocialSecurityNumber>123456789</SocialSecurityNumber>
            </PersonalData>
            <HomeAddress>
               <StreetAddress1>123 Test Avenue</StreetAddress1>
               <StreetAddress2>Apt. B</StreetAddress2>
               <City>Boston</City>
               <State>MA</State>
               <ZipCode>12345</ZipCode>
            </HomeAddress>
            <DriverLicense>
               <Number>123456789012345678901234567890123</Number>
               <State>AZ</State>
               <CourtesyCardNumber>123456789012345678901234567890123</CourtesyCardNumber>
            </DriverLicense>
         </CheckData>
         <Request>
            <MerchantVaultTokenReference>MyReference</MerchantVaultTokenReference>
         </Request>
      </BoardAccount>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <BoardAccountResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardAccountResult>
            <VaultToken>1000001000012A9EAGD9</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
         </BoardAccountResult>
      </BoardAccountResponse>
   </soap:Body>
</soap:Envelope>

FindBoardedAccount

You can view the: 

  • Method the merchant used to verify the customer’s account
  • Data about the customer’s checking account
  • Customer’s personal data
  • Customer’s address 
  • Data about the customer’s driver’s license
Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VaultTokenRequest An object containing the VaultToken.

Notes

Merchantware makes all digits except the last four for the following response parameters:
  • Transit number
  • Account number
  • Phone number
  • Date of birth
  • Social security number
  • Driver license number
  • Courtesy card number

Response

A CheckVaultTokenResponse45 object is returned.

Example FindBoardedAccount SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
  <soap:Body>
    <FindBoardedAccount>
      <Credentials>
        <MerchantName>TEFNorthSageMultiSEC</MerchantName>
        <MerchantSiteId>Z7UV7DJ5</MerchantSiteId>
        <MerchantKey>NJKGQ-GGDOX-IDFHL-AYSK7-TWMKQ</MerchantKey>
      </Credentials>
      <Request>
        <VaultToken>1000001000012A9EAGD9</VaultToken>
        </Request>
    </FindBoardedAccount>
  </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <FindBoardedAccountResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <FindBoardedAccountResult>
        <ErrorMessage/>
        <ErrorCode/>
        <CheckData>
          <VerificationMethod>IdentityDriverLicense</VerificationMethod>
          <Check>
            <AccountType>C</AccountType>
            <CheckType>PE</CheckType>
            <NameOnCheck>Test Sage</NameOnCheck>
            <TransitNumber>*****0018</TransitNumber>
            <AccountNumber>*****6789</AccountNumber>
          </Check>
          <PersonalData>
            <PhoneNumber>******7890</PhoneNumber>
            <DateOfBirth>****1990</DateOfBirth>
            <SocialSecurityNumber>*****6789</SocialSecurityNumber>
          </PersonalData>
          <HomeAddress>
            <StreetAddress1>123 Test Avenue</StreetAddress1>
            <StreetAddress2>Apt. B</StreetAddress2>
            <City>Boston</City>
            <State>MA</State>
            <ZipCode>12345</ZipCode>
          </HomeAddress>
          <DriverLicense>
            <Number>*****************************0123</Number>
            <State>AZ</State>
            <CourtesyCardNumber>*****************************0123</CourtesyCardNumber>
          </DriverLicense>
        </CheckData>
        <TokenData>
          <Status>Boarded</Status>
          <MerchantVaultTokenReference>MyReference</MerchantVaultTokenReference>
        </TokenData>
      </FindBoardedAccountResult>
    </FindBoardedAccountResponse>
  </soap:Body>
</soap:Envelope>

UnboardAccount

When you send an UnboardAccount request, Merchantware unboards the account, which means that you can no longer use the account’s VaultToken in transaction requests that you send.

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VaultTokenRequest An object containing the VaultToken.

Notes

You cannot reactivate an account after you unboard it.

Response

A CheckVaultBoardingResponse45 object is returned.

Example FindBoardedAccount SOAP Request

Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:v45="http://schemas.merchantwarehouse.com/merchantware/v45/">
  <soap:Header/>
    <soap:Body>
      <UnboardAccount>
        <Credentials>
          <MerchantName>merchant name</MerchantName>
          <MerchantSiteId>merchant site id</MerchantSiteId>
          <MerchantKey>merchant key</MerchantKey>
        </Credentials>
        <Request>
          <VaultToken>1000000000000000KUN7</VaultToken>
        </Request>
      </UnboardAccount>
    </soap:Body>
</soap:Envelope>
Sample Request Packet
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
    <BoardAccountResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
      <BoardAccountResult>
        <VaultToken>1000000000000000KUN7</VaultToken>
        <ErrorCode/>
        <ErrorMessage/>
        </BoardAccountResult>
      </BoardAccountResponse>
    </soap:Body>
</soap:Envelope>
	

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 you use to process the transaction, which includes:
  • KEYED
  • READER
  • PREVIOUSTRANSACTION
  • VAULT
For the parameters to include for each Source type, see Source.
VerificationMethod string   KEYED, READER, PREVIOUSTRANSACTION The method for verifying the customer. See Verification methods.
Token string 1-100 PREVIOUSTRANSACTION

The token representing a transaction you previously ran. Use this only for Refund transactions to refer to the original transaction that you are refunding.  

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

VaultToken string 1-20 VAULT

A token for a specific checking account that the merchant boarded to the vault.
If you send both CheckData and VaultToken in the request, Merchantware ignores CheckData and uses the CheckData referenced by the VaultToken.

Note: To use the VaultToken, make sure the source is "VAULT".

CheckData\Check
AccountType string 1 KEYED + READER The type of account the customer is using for the transaction. Verify against the Account Type codes.
CheckType string 2 KEYED + READER The type of check or checking account. Verify against the Check Type codes.
NameOnCheck string 0-160 KEYED + READER The customer's name that appears on the check.
Amount string (double) 1-100 KEYED, READER, VAULT The dollar amount of the transaction.
TransitNumber string 0 - 9 KEYED The nine digit transit routing number.
Note: Merchantware masks all digits except the last four in responses.
AccountNumber string 0-18 KEYED The number of the customer's bank account.
Note: Merchantware masks all digits except the last four in responses.
CheckNumber string 0-6 KEYED The number of the check.
Do not send this parameter for recurring check transactions.
MICR string 0-100 READER The raw Magnetic Ink Character Recognition (MICR) data.
Note: You should keep the substitution for the check symbols and spaces:
  • The Transit symbol is replaced with an uppercase or lowercase 'T'.
  • The On-US symbol is replaced with an uppercase or lowercase 'O'.
  • The Amount symbol is replaced with an uppercase or lowercase 'A'.
  • The Dash symbol is replaced with an uppercase or lowercase 'D'.
CheckData\PersonalData
PhoneNumber string 0-100 KEYED, READER, PREVIOUSTRANSACTION The consumer’s contact phone number. The phone number is expected as a 10 digit number without a – or ().
DateOfBirth string 0-8 KEYED, READER, PREVIOUSTRANSACTION The customer's date of birth in MMDDYYYY format.
SocialSecurityNumber string 0-9 KEYED, READER, PREVIOUSTRANSACTION The customer's Social Security number.
CheckData\HomeAddress
StreetAddress1 string 0-200 KEYED, READER, PREVIOUSTRANSACTION The first line of the customer's address.
StreetAddress2 string 0-200 KEYED, READER, PREVIOUSTRANSACTION The second line of the customer's address.
City string 0-50 KEYED, READER, PREVIOUSTRANSACTION The city of the customer's address.
State string 0 or 2 KEYED, READER, PREVIOUSTRANSACTION A code representing the state or province of the customer's address. For a list of codes you can use, see:
ZipCode string 0-5 KEYED, READER, PREVIOUSTRANSACTION The ZIP code of the customer's address.
CheckData\DriverLicense
Number string 0-33 KEYED, READER, PREVIOUSTRANSACTION The number of the driver's license.
State string 0 or 2 KEYED, READER, PREVIOUSTRANSACTION A code representing the state or province of the customer's address on the driver's license. For a list of codes you can use, see:
CourtesyCardNumber string 0-50 KEYED, READER, PREVIOUSTRANSACTION A number the merchant assigns to the customer if they do not have a driver's license.

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.

CheckTransactionResponse45

Name
Type
Source
Description
ActionDescription string ALL Any action message indicated by the verifier. If populated this value should be displayed to the cashier.
ApprovalStatus string ALL The status of the transaction, whether approved or declined. This value may also have other definitions depending on context.
AuthorizationCode string ALL Authorization Code issued by the processor upon receipt of a transaction.
ErrorMessage string ALL A message describing the reason the transaction could not complete.
Token string ALL 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.
CheckData Object KEYED, READER, VAULT An object containing data about the check. See CheckData.
RecurringCheck String KEYED, READER, VAULT Indicates if the transaction is recurring. The vaule is either:
  • True - the transaction is recurring
  • False - the transaction is not recurring
MerchantTransactionId String KEYED, READER, VAULT The identifer that the merchant gave the transaction.
MerchantVaultTokenReference String VAULT A parameter that a merchant can use to add a tag to a customer's account. The merchant can add the same tag to many accounts so that they can group transactions.

BoardingRequest

Name Type Size Description
MerchantVaultTokenReference string 1-100 A parameter that a merchant can use to add a tag to a customer's account. The merchant can add the same tag to many accounts so that they can group transactions.

CheckVaultBoardingResponse45

Name Type Description
VaultToken String A token for a specific checking account that a merchant boarded to the vault.
ErrorCode String A code representing a specific error. The code can be one of the following:
  • 1500 - Paymnet information not found
  • 99999 - Payment information not available.
Note: Not all errors have an error code.
ErrorMessage String A message describing the error.

CheckVaultTokenResponse45

Name Type Description
CheckData Object An object that contains VaultCheckData. See VaultCheckData.
ErrorCode String A code representing a specific error. The code can be one of the following:
  • 1500 - Payment information not found.
  • 99999 - Payment information not available.
Note: Not all errors have an error code.
ErrorMessage String A message describing the error.
TokenData Object An object containing data about the token. See TokenData.

VaultCheckData

Name Type Size Description
VaultCheckData
VerificationMethod string - The method you use to verify the customer's identity. See Verification method.
VaultCheckData\VaultCheck
AccountType string 1 The type of account the customer used for the transaction. See Account Type.
CheckType string 2 Contains the type of check or checking account. See Check Type.
NameOnCheck string 0-160 The account holder name as written on the check.
TransitNumber string 0 or 9 The nine digit transit routing number.
Note: Merchantware masks all digits except the last four in the response. 
AccountNumber string 0-18 The check account number.
Note: Merchantware masks all digits except the last four in the response. 
VaultCheckData\PersonalData
PhoneNumber string 0-100 The customer's contact phone number. The phone number is expected as a 10 digit number without a – or ().
DateOfBirth string 0-8 The customer's date of birth in the format MMDDYYYY.
SocialSecurityNumber string 0-9 The customer's Social Security Number.
VaultCheckData\HomeAddress
StreetAddress1 string 0-200 The first line of the customer's address.
StreetAddress2 string 0-200 The second line of the customer's address.
City string 0-50 The city of the customer's address.
State string 0 or 2  A code representing the state or province code of the customer's address. For a list of codes, see:
ZipCode string 0-5 The ZIP code of the customer's address.
CheckData\DriverLicense
Number string 0-33 The number of the customer's driver's license
State string 0 or 2 A code representing the consumer's driver license state or province code. For a list of codes, see:
CourtesyCardNumber string 0-50 A number the merchant assigned the customer if they do not have a driver's licnese..

VaultTokenRequest

Name Type Size Description
VaultTokenRequest string 1-40 A token for a specific checking account that a merchant boarded to the vault.

TokenData

Name Type Description
MerchantVaultTokenReference String A parameter that a merchant can use to add a tag to an account. The merchant can add the same tag to many accounts so that they can group transactions.
Status String Indicates the status of the VaultToken, which can be either "Boarded" or "Unboarded".
The VaultToken is "Boarded" if the following are true:
  • The vault token exists in the Merchantware vault.
  • The vault token is active.
  • The vault token belongs to either the merchant sending the request or another merchant in the same merchant group.
  • You are sending a vault token from the Check vault.
The VaultToken is "Unboarded" if the following are true:
  • The vault token exists in the Merchantware vault.
  • You deactivated the merchant's account using the UnboardAccount method.
  • The vault token belongs to either the merchant sending the request or another merchant in the same merchant group.
  • You are sending a vault token from the Check vault.

Source

Name Description
Reader If the source is reader, you need to include the following parameters in your request:
  • MICR
  • Transit Number
  • Account Number
  • Check Number
Keyed If the source is keyed, you need to include the following parameters in your request:
  • Transit Number
  • Account Number
  • Check Number
Note: Do not provide CheckNumber if the check is recurring.
PreviousTransaction If the source is a previous transaction, you need to include the following parameters in your request:
  • Token
Vault If the source is vault token, you need to include the following parameters in your request:
  • VaultToken
  • Amount

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
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