Credit

Service Information

The credit web service provides payment processing and methods for both credit and debit cards.

Service Endpoint

https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v45/Credit.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

AdjustTip

The AdjustTip web methods adds or alters the tip amount to a prior transaction.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request TipRequest A TipRequest object containing the transactional data used to perform a tip adjustment.

Response

A TransactionResponse45 object is returned.

Notes

The AdjustTip method changes the tip amount to a prior sale in the current batch. It is not possible to adjust the tip of a transaction settled in a previous batch.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AdjustTip 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>1236559</Token>
            <Amount>1.00</Amount>
         </Request>
      </AdjustTip>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <AdjustTipResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <AdjustTipResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>1236560</Token>
            <AuthorizationCode/>
            <TransactionDate>3/14/2016 7:54:23 PM</TransactionDate>
            <Amount/>
            <RemainingCardBalance/>
            <CardNumber/>
            <Cardholder/>
            <CardType>0</CardType>
            <FsaCard/>
            <ReaderEntryMode>0</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
         </AdjustTipResult>
      </AdjustTipResponse>
   </soap:Body>
</soap:Envelope>

AttachSignature

The AttachSignature web method appends a signature record to an existing transaction. This signature record is applied for a string containing vector drawing instructions.
 

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request SignatureRequest A SignatureRequest object containing the data used to attach a signature to an existing transaction.

Response

A SignatureResponse45 object is returned.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AttachSignature 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>608957</Token>
            <VectorImageData>10,10^110,110^0,65535^10,110^110,10^0,65535^~</VectorImageData>
         </Request>
      </AttachSignature>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <AttachSignatureResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <AttachSignatureResult>
            <UploadStatus>ACCEPTED</UploadStatus>
            <Token>608957</Token>
            <TransactionDate>3/14/2016 7:57:32 PM</TransactionDate>
            <ErrorMessage/>
         </AttachSignatureResult>
      </AttachSignatureResponse>
   </soap:Body>
</soap:Envelope>

Authorize

The Authorize web method applies an authorization to a credit card which can be captured at a later time.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
PaymentData PaymentData A PaymentData object containing the payment details of the card used to process the transaction.
Request AuthorizationRequest An AuthorizationRequest object containing the transactional data used to create the authorization.

Response

A TransactionResponse45 object is returned.

Allowed Payment Data Sources

Reader, Keyed, Vault

Notes

To finish committing a transaction, the token obtained from this method should be used with the Capture web method.

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Authorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <CardVerificationValue>123</CardVerificationValue>
         </PaymentData>
         <Request>
            <Amount>1.05</Amount>
            <InvoiceNumber>1556</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>167901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608958</Token>
            <AuthorizationCode>OK785C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:58:33 PM</TransactionDate>
            <Amount>1.05</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

Example Encrypted Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Authorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <CardVerificationValue>123</CardVerificationValue>
            <EncryptedKeyedData>02B600C037001C101692;4012********0026=1812:***?*126=09876543210=FDB4CAC2FAF2483D4A68A4195273CFEAB03EDFC6819AD552631AAC0E9A47C4A63B14D241942C38F2A07CAFF696AE6387211133EC62994900580004600216713B03</EncrptedKeyedData>
         </PaymentData>
         <Request>
            <Amount>1.05</Amount>
            <InvoiceNumber>1556</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>167901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608958</Token>
            <AuthorizationCode>OK785C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:58:33 PM</TransactionDate>
            <Amount>1.05</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

Example Swiped Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Authorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            
            <!--Reader Fields-->
            <TrackData>%B4012000033330026^TEST CARD/GENIUS^181210054321000000000000000 150 A?;4012000033330026=18121011000012345678?</TrackData>
         </PaymentData>
         <Request>
            <Amount>2.74</Amount>
            <InvoiceNumber>1264</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>137149</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608959</Token>
            <AuthorizationCode>OK788C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:59:58 PM</TransactionDate>
            <Amount>2.74</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>TEST CARD/GENIUS</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>2</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

Example Vault SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Authorize xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Vault</Source>
            
            <!--Vault Fields-->
            <VaultToken>1000000000002AVGMM7Z</VaultToken>
         </PaymentData>
         <Request>
            <Amount>2.05</Amount>
            <InvoiceNumber>1558</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>167903</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Authorize>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608960</Token>
            <AuthorizationCode>OK790C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:02:00 PM</TransactionDate>
            <Amount>2.05</Amount>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </AuthorizeResult>
      </AuthorizeResponse>
   </soap:Body>
</soap:Envelope>

BoardCard

The BoardCard method stored payment information for a credit card into the Merchantware Vault.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
PaymentData PaymentData A PaymentData object containing the payment details of the card used to process the transaction.
Request BoardingRequest A BoardingRequest object containing the transactional data used to board a card.

Response

A VaultBoardingResponse45 object is returned.

Allowed Payment Data Sources

Reader, Keyed, PreviousTransaction

Notes

Merchant Defined Tokens are no longer supported. If you require use of this feature please contact the Integraion team.

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BoardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
         </PaymentData>
      </BoardCard>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <BoardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardCardResult>
            <VaultToken>1000000000002WSZECPL</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </BoardCardResult>
      </BoardCardResponse>
   </soap:Body>
</soap:Envelope>

Example Encrypted Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BoardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <EncryptedKeyedData>02B600C037001C101692;4012********0026=1812:***?*126=09876543210=FDB4CAC2FAF2483D4A68A4195273CFEAB03EDFC6819AD552631AAC0E9A47C4A63B14D241942C38F2A07CAFF696AE6387211133EC62994900580004600216713B03</EncrptedKeyedData>
         </PaymentData>
      </BoardCard>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <BoardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardCardResult>
            <VaultToken>1000000000002WSZECPL</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </BoardCardResult>
      </BoardCardResponse>
   </soap:Body>
</soap:Envelope>

Example Previous Transaction SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BoardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PreviousTransaction</Source>

            <!--Previous Transaction Field-->
            <Token>608937</Token>
         </PaymentData>
      </BoardCard>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <BoardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardCardResult>
            <VaultToken>138JK7U40X02WSZECPL</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </BoardCardResult>
      </BoardCardResponse>
   </soap:Body>
</soap:Envelope>

Example Swiped Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BoardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            
            <!--Reader Fields-->
            <TrackData>%B4012000033330026^TEST CARD/GENIUS^181210054321000000000000000 150 A?;4012000033330026=18121011000012345678?</TrackData>
         </PaymentData>
      </BoardCard>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <BoardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardCardResult>
            <VaultToken>127MMEIIQVEW2WSZECPL</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </BoardCardResult>
      </BoardCardResponse>
   </soap:Body>
</soap:Envelope>

Example Custom Token SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BoardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
         </PaymentData>
         <Request>
            <MerchantDefinedToken>MYTOKENVALUEX</MerchantDefinedToken>
         </Request>         
      </BoardCard>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <BoardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <BoardCardResult>
            <VaultToken>MYTOKENVALUEX</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </BoardCardResult>
      </BoardCardResponse>
   </soap:Body>
</soap:Envelope>

Capture

The Capture web method completes a transaction for a prior authorization.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request CaptureRequest A CaptureRequest object containing the transactional data used capture a previous authorization and place it into the batch.

Response

A TransactionResponse45 object is returned.

Notes

This method captures a previous authorization and adds it to the current batch for settlement.
If you wish to cancel a transaction created with the Capture method, you may use the Void method. However they cannot be applied once the transaction has been batched.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Capture 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>608939</Token>
            <Amount>1.50</Amount>
            <InvoiceNumber>1556</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>167902</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Capture>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <CaptureResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <CaptureResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608961</Token>
            <AuthorizationCode>OK036C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:09:31 PM</TransactionDate>
            <Amount>1.50</Amount>
            <RemainingCardBalance/>
            <CardNumber/>
            <Cardholder/>
            <CardType>0</CardType>
            <FsaCard/>
            <ReaderEntryMode>3</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </CaptureResult>
      </CaptureResponse>
   </soap:Body>
</soap:Envelope>

FindBoardedCard

The FindBoardedCard method retrieves the payment data stored inside the Merchantware Vault.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VaultTokenRequest A VaultTokenRequest object used to retrieve information about a boarded card from the vault.

Response

A VaultTokenResponse45 object is returned.

Notes

Any returned sensitive information (such as credit card numbers) will be masked and/or truncated.
Any value passed into the vault token field is case-insensitive.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <FindBoardedCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <Request>
            <VaultToken>127MMEIIQVEW2WSZECPL</VaultToken>
         </Request>
      </FindBoardedCard>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <FindBoardedCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <FindBoardedCardResult>
            <CardNumber>0026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <Cardholder/>
            <CardType>4</CardType>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <ErrorCode/>
            <ErrorMessage/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </FindBoardedCardResult>
      </FindBoardedCardResponse>
   </soap:Body>
</soap:Envelope>

UpdateBoardedCard

The UpdateBoardedCard method changes the expiration date for an existing payment method stored inside the Merchantware Vault.

Live Endpoint https://ps1.merchantware.net/MerchantWare/ws/RetailTransaction/v45/Credit.asmx?op=UpdateBoardedCard

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Result UpdateBoardedCardRequest An UpdateBoardedCardRequest object used to update a token from the vault.

Response

A VaultBoardingResponse45 object is returned.

Notes

Any returned sensitive information (such as credit card numbers) will be masked and/or truncated.
Any value passed into the vault token field is case-insensitive.

Example SOAP Request

Sample Request Packet (raw)
<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>
      <UpdateBoardedCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <Request>
            <VaultToken>127MMEIIQVEW2WSZECPL</VaultToken>
            <ExpirationDate>0118</ExpirationDate>
         </Request>
      </UpdateBoardedCard>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<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>
      <UpdateBoardedCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <UpdateBoardedCardResult>
            <VaultToken>127MMEIIQVEW2WSZECPL</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
         </UpdateBoardedCardResult>
      </UpdateBoardedCardResponse>
   </soap:Body>
</soap:Envelope>

ForceCapture

The ForceCapture web method forces a charge to be issued upon a customer’s credit card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
PaymentData PaymentData A PaymentData object containing the payment 
Request ForceCaptureRequest A ForceCaptureRequest object containing the transactional data used capture a voice authorization and place it into the batch.

Response

A TransactionResponse45 object is returned.

Allowed Payment Data Sources

Keyed

Notes

This method should only be used as a backup to charge a credit card if you are unable to obtain an approval through a normal sale. The authorization code is required for this method, and will typically be received by a voice authorization over the phone.

Forced transactions ALWAYS DOWNGRADE on rates and fees at the processor. If you make this the default charge method in your application, your merchants will end up paying significantly higher transaction rates and fees.

Ideally, you would only use this method as a last resort, or as a follow-up to a REFERRAL notice on a prior sale attempt.

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <ForceCapture xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <!-- AVS and CVV values are not checked as part of a ForceCapture transaction-->
         </PaymentData>
         <Request>
            <Amount>3.06</Amount>
            <AuthorizationCode>V00546C</AuthorizationCode>
            <InvoiceNumber>1559</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>168901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </ForceCapture>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <ForceCaptureResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <ForceCaptureResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608962</Token>
            <AuthorizationCode>V00546C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:11:01 PM</TransactionDate>
            <Amount>3.06</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </ForceCaptureResult>
      </ForceCaptureResponse>
   </soap:Body>
</soap:Envelope>

Example Encrypted Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <ForceCapture xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <EncryptedKeyedData>02B600C037001C101692;4012********0026=1812:***?*126=09876543210=FDB4CAC2FAF2483D4A68A4195273CFEAB03EDFC6819AD552631AAC0E9A47C4A63B14D241942C38F2A07CAFF696AE6387211133EC62994900580004600216713B03</EncrptedKeyedData>
            <!-- AVS and CVV values are not checked as part of a ForceCapture transaction-->
         </PaymentData>
         <Request>
            <Amount>3.06</Amount>
            <AuthorizationCode>V00546C</AuthorizationCode>
            <InvoiceNumber>1559</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>168901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </ForceCapture>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <ForceCaptureResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <ForceCaptureResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608962</Token>
            <AuthorizationCode>V00546C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:11:01 PM</TransactionDate>
            <Amount>3.06</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </ForceCaptureResult>
      </ForceCaptureResponse>
   </soap:Body>
</soap:Envelope>

Refund

The Refund method issues a credit card refund to a customer.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
PaymentData PaymentData A PaymentData object containing the payment 
Request RefundRequest A RefundRequest object containing the transactional data used to perform a refund.

Response

A TransactionResponse45 object is returned.

Allowed Payment Data Sources

Reader, Keyed, PreviousTransaction

Notes

Credit refunds can be partial and are specified by the amount parameter.
The lookup can be performed either by invoice number or token. They cannot both be blank. If both are presented, token is used.

This method issues a refund to a credit or debit card from a prior sale transaction. While it is possible to set a custom amount, this method is limited to the original amount of the sale transaction by default. It is possible to enable an override on a per account basis so that refunds for higher than the original amount can be made. No on-hand credit card information is required to use this method.

For example, with a prior sale for $10.00, you may reuse the token from that sale transaction to issue refunds up until the original total has been met, whether all at once ($10.00) or over several transactions ($5.00, $3.00, $2.00). Unless the account has had refunds for higher than the original amount enabled.

This method is useful in cases where you need to return money to a credit card and you have already batched the original sale. Using this method allows you to better support your customers without having to store card data.

On the other hand, if the original sale has not been batched yet, it is better to void the sale to return money or undo a transaction, as this will prevent activity at the processor and thus avoid incurring transaction fees.
 

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <!-- AVS and CVV values are not checked as part of a Refund transaction-->
         </PaymentData>
         <Request>
            <Amount>4.01</Amount>
            <InvoiceNumber>1701</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>165901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608963</Token>
            <AuthorizationCode/>
            <TransactionDate>3/14/2016 8:12:50 PM</TransactionDate>
            <Amount>4.01</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </RefundResult>
      </RefundResponse>
   </soap:Body>
</soap:Envelope>

Example Encrypted Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <EncryptedKeyedData>02B600C037001C101692;4012********0026=1812:***?*126=09876543210=FDB4CAC2FAF2483D4A68A4195273CFEAB03EDFC6819AD552631AAC0E9A47C4A63B14D241942C38F2A07CAFF696AE6387211133EC62994900580004600216713B03</EncrptedKeyedData>
            <!-- AVS and CVV values are not checked as part of a Refund transaction-->
         </PaymentData>
         <Request>
            <Amount>4.01</Amount>
            <InvoiceNumber>1701</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>165901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608963</Token>
            <AuthorizationCode/>
            <TransactionDate>3/14/2016 8:12:50 PM</TransactionDate>
            <Amount>4.01</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </RefundResult>
      </RefundResponse>
   </soap:Body>
</soap:Envelope>

Example Previous Transaction SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PreviousTransaction</Source>
            
            <!--Previous Transaction Field-->
            <Token>608957</Token>
         </PaymentData>
         <Request>
            <InvoiceNumber>1703</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>165902</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608964</Token>
            <AuthorizationCode>OK775C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:13:13 PM</TransactionDate>
            <Amount/>
            <RemainingCardBalance/>
            <CardNumber/>
            <Cardholder/>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </RefundResult>
      </RefundResponse>
   </soap:Body>
</soap:Envelope>

Example Swiped Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            
            <!--Reader Fields-->
            <TrackData>%B4012000033330026^TEST CARD/GENIUS^181210054321000000000000000 150 A?;4012000033330026=18121011000012345678?</TrackData>
         </PaymentData>
         <Request>
            <Amount>1.48</Amount>
            <InvoiceNumber>3141</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>215003</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608967</Token>
            <AuthorizationCode/>
            <TransactionDate>3/14/2016 8:15:59 PM</TransactionDate>
            <Amount>1.48</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>TEST CARD/GENIUS</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>2</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </RefundResult>
      </RefundResponse>
   </soap:Body>
</soap:Envelope>

Example Vault SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Vault</Source>
            
            <!--Vault Fields-->
            <VaultToken>22222222</VaultToken>
         </PaymentData>
         <Request>
            <Amount>1.83</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1559</InvoiceNumber>
            <Amount>1.83</Amount>
            <PurchaseOrderNumber>17809</PurchaseOrderNumber>
            <CustomerCode>23</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166909</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>822621046</Token>
            <AuthorizationCode>OK9999</AuthorizationCode>
            <TransactionDate>9/5/2017 5:46:30 PM</TransactionDate>
            <Amount>1.83</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>Test</Cardholder>
            <CardType>3</CardType>
            <FsaCard>False</FsaCard>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>100GQ4B22C</Rfmiq>
            <DebitTraceNumber/>
         </RefundResult>
      </RefundResponse>
   </soap:Body>
</soap:Envelope>

Sale

The Sale method charges a credit or debit card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
PaymentData PaymentData A PaymentData object containing the payment 
Request SaleRequest A SaleRequest object containing the transactional data used to perform a sale.

Response

A TransactionResponse45 object is returned.

Allowed Payment Data Sources

Reader, Keyed, Vault

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <CardVerificationValue>123</CardVerificationValue>
          </PaymentData>
         <Request>
            <Amount>1.05</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1556</InvoiceNumber>
            <PurchaseOrderNumber>17801</PurchaseOrderNumber>
            <CustomerCode>20</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SaleResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608957</Token>
            <AuthorizationCode>OK775C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:57:22 PM</TransactionDate>
            <Amount>1.05</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </SaleResult>
      </SaleResponse>
   </soap:Body>
</soap:Envelope>

Example Encrypted Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>1218</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
            <AvsStreetAddress>1 Federal Street</AvsStreetAddress>
            <AvsZipCode>02110</AvsZipCode>
            <CardVerificationValue>123</CardVerificationValue>
            <EncryptedKeyedData>02B600C037001C101692;4012********0026=1812:***?*126=09876543210=FDB4CAC2FAF2483D4A68A4195273CFEAB03EDFC6819AD552631AAC0E9A47C4A63B14D241942C38F2A07CAFF696AE6387211133EC62994900580004600216713B03</EncryptedKeyedData>
         </PaymentData>
         <Request>
            <Amount>1.05</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1556</InvoiceNumber>
            <PurchaseOrderNumber>17801</PurchaseOrderNumber>
            <CustomerCode>20</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SaleResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608957</Token>
            <AuthorizationCode>OK775C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:57:22 PM</TransactionDate>
            <Amount>1.05</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </SaleResult>
      </SaleResponse>
   </soap:Body>
</soap:Envelope>

Example Swiped Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            
            <!--Reader Fields-->
            <TrackData>%B4012000033330026^TEST CARD/GENIUS^181210054321000000000000000 150 A?;4012000033330026=18121011000012345678?</TrackData>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1906</InvoiceNumber>
            <PurchaseOrderNumber>12401</PurchaseOrderNumber>
            <CustomerCode>20</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>138401</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SaleResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608970</Token>
            <AuthorizationCode>OK820C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:22:23 PM</TransactionDate>
            <Amount>1.29</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>TEST CARD/GENIUS</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>2</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </SaleResult>
      </SaleResponse>
   </soap:Body>
</soap:Envelope>

Example Vault SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Vault</Source>
            
            <!--Vault Fields-->
            <VaultToken>1000000000002AVGMM7Z</VaultToken>
         </PaymentData>
         <Request>
            <Amount>1.83</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1559</InvoiceNumber>
            <PurchaseOrderNumber>17809</PurchaseOrderNumber>
            <CustomerCode>23</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166909</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SaleResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608969</Token>
            <AuthorizationCode>OK818C</AuthorizationCode>
            <TransactionDate>3/14/2016 8:22:13 PM</TransactionDate>
            <Amount>1.83</Amount>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </SaleResult>
      </SaleResponse>
   </soap:Body>
</soap:Envelope>


Example Healthcare SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Keyed</Source>
            
            <!--Keyed Fields-->
            <CardNumber>4012000033330026</CardNumber>
            <ExpirationDate>0416</ExpirationDate>
            <CardHolder>John Doe</CardHolder>
         </PaymentData>
         <Request>
            <Amount>202.00</Amount>
            <HealthCareAmountDetails>
               <CopayAmount>60.00</CopayAmount>
               <ClinicalAmount>0.00</ClinicalAmount>
               <DentalAmount>0.00</DentalAmount>
               <HealthCareTotalAmount>80.00</HealthCareTotalAmount>
               <PrescriptionAmount>0.00</PrescriptionAmount>
               <VisionAmount>0.00</VisionAmount>
            </HealthCareAmountDetails>
            <InvoiceNumber>1556</InvoiceNumber>
            <PurchaseOrderNumber>17801</PurchaseOrderNumber>
            <CustomerCode>20</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>True</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>
Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SaleResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>609015</Token>
            <AuthorizationCode>OK775C</AuthorizationCode>
            <TransactionDate>3/14/2016 7:57:22 PM</TransactionDate>
            <Amount>1.05</Amount>
            <RemainingCardBalance/>
            <CardNumber>************0026</CardNumber>
            <Cardholder>John Doe</Cardholder>
            <CardType>4</CardType>
            <FsaCard/>
            <ReaderEntryMode>1</ReaderEntryMode>
            <AvsResponse>Y</AvsResponse>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
            <Rfmiq>10000ABCDE</Rfmiq>
         </SaleResult>
      </SaleResponse>
   </soap:Body>
</soap:Envelope>

SettleBatch

The SettleBatch method batches out a merchant’s outstanding transactions for settlement.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.

Response

A BatchResponse45 object is returned.

Notes

Please note that it is possible for a batch to return a negative settlement amount.
Avoid batching more than once a day unless the merchant's account or business rules require it. Almost all merchant accounts incur a fee when an account batch is settled, and merchant accounts typically require only one batch per 24 hours.

Conversely, some merchant accounts may already be setup to automatically batch. However, you should not explicitly avoid writing code to batch out an account. Most merchant accounts are not setup this way, and there may be times when your merchant needs to settle before a typical end-of-day.
 

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <SettleBatch xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
      </SettleBatch>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <SettleBatchResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <SettleBatchResult>
            <BatchStatus>SUCCESS</BatchStatus>
            <AuthorizationCode>0314160001</AuthorizationCode>
            <BatchAmount>2.19</BatchAmount>
            <TransactionCount>8</TransactionCount>
            <TransactionDate>3/14/2016 8:28:30 PM</TransactionDate>
            <ErrorMessage/>
            <ExtraData/>
         </SettleBatchResult>
      </SettleBatchResponse>
   </soap:Body>
</soap:Envelope>

UnboardCard

The UnboardCard method removes existing payment information from the Merchantware Vault.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VaultTokenRequest A VaultTokenRequest object used to remove a token from the vault.

Response

A VaultBoardingResponse45 object is returned.

Notes

Any value passed into the vault token field is case-insensitive.
Any returned sensitive information (such as credit card numbers) will be masked and/or truncated.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header/>
   <soap:Body>
      <UnboardCard xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <Request>
            <VaultToken>MYTOKENVALUEX</VaultToken>
         </Request>
      </UnboardCard>
   </soap:Body>
</soap:Envelope>

Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <UnboardCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <UnboardCardResult>
            <VaultToken>MYTOKENVALUEX</VaultToken>
            <ErrorCode/>
            <ErrorMessage/>
         </UnboardCardResult>
      </UnboardCardResponse>
   </soap:Body>
</soap:Envelope>


Void

The Void method voids a prior unsettled transaction.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against Merchantware.
Request VoidRequest A VoidRequest object containing the transactional data used to void a previous transaction.

Response

A TransactionResponse45 object is returned.

Notes

This removes a transaction from the current batch. It is not possible to void a transaction settled in a previous batch.
For more guidance, see our Best Practices guide on Void Failure Handling.

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header/>
   <soap:Body>
      <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>608973</Token>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>167901</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Void>
   </soap:Body>
</soap:Envelope>


Sample Return Packet
<soap:Envelope xmlns:soap="http://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>
      <VoidResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <VoidResult>
            <ApprovalStatus>APPROVED</ApprovalStatus>
            <Token>608974</Token>
            <AuthorizationCode>VOID</AuthorizationCode>
            <TransactionDate>3/14/2016 8:30:18 PM</TransactionDate>
            <Amount/>
            <RemainingCardBalance/>
            <CardNumber/>
            <Cardholder/>
            <CardType>0</CardType>
            <FsaCard/>
            <ReaderEntryMode>0</ReaderEntryMode>
            <AvsResponse/>
            <CvResponse/>
            <ErrorMessage/>
            <ExtraData/>
         </VoidResult>
      </VoidResponse>
   </soap:Body>
</soap:Envelope>



Data Structures

MerchantCredentials

Name Type Size Description
MerchantName String 1-160 The name of the business or organization owning the Merchantware account.
MerchantSiteId String 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
MerchantKey String 1-160 The software key or password for the site accessing a Merchantware account.

PaymentData

Name Type Size Source Description
Source String (Payment Data Source) 1-100 ALL The method used to supply the payment data.

READER or KEYED or PREVIOUSTRANSACTION or VAULT
TrackData String 1-500 READER The complete track data (all tracks) for the payment card returned from a card reader. 
PinBlock String 0-100 READER The PIN block received from a pinpad device.
PinKsn String 0-100 READER The key serial number (KSN) associated with the PIN block received from a pinpad device.
ReaderEntryMode String 0-100 READER The reader entry mode for this transaction. It can be either MAGNETICSTRIPE or PROXIMITY.
CardNumber String 13-19 KEYED The PAN or card number of the payment card.
ExpirationDate String 4 KEYED The expiration date of the payment card in MMYY format.
Cardholder String 0-100 KEYED The cardholder name as it appears on the payment card.
AvsStreetAddress String 0-100 KEYED The street address associated with the payment card for use in address verification system (AVS) checks.
AvsZipCode String 0, 5, or 9 KEYED The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
CardVerificationValue String 0-100 KEYED The security code (CVD, CVV, CVC, etc.) of the payment card for use in card verification (CV) checks.
EncryptedKeyedData String 1-540 KEYED The output generated by an encrypted keypad.
Token String 1-100 PREVIOUSTRANSACTION The token identifier returned from a previous transaction.
VaultToken String 1-40 VAULT The token used to identify the payment method within the Merchantware Vault.

Notes

For all PaymentData, a “Source” type must be defined.  Depending on the source, please follow the information below.

Reader Payment Source

Data from Track 2 is required for the TrackData parameter. However, you may send in the raw swipe, as long as it has not been altered since it was read from the payment card. This method will separate Track 2 data by itself.
The TrackData should be unaltered raw swipe data from an unencrypted reader or from an IDTECH, IDTECH Enhanced, or Magtek encrypted reader.
The ReaderEntryMode is defaulted to MAGNETICSTRIPE if it is left blank.

Keyed Payment Source

The expiration date should be specified in the form "MMYY", the same ordering as a card holder would physically see on their card. For example, a card expiring in November 2008 would be specified as 1108.
The card security code is composed of the three extra digits printed on the back of most credit cards, although most American Express cards have a four digit number displayed on the front of the card.
It is in your best interest to always send in the address verification information and Card Security Code whenever possible.  You can use this information to contest chargebacks and disputes.

Encrypted Keyed Payment Source

When using an encrypted keypad, the following apply:
  • If you supply the EncryptedKeyedData element, the transaction is identified as being sent from an encrypted keyed reader. The EncryptedKeyedData element contains the encrypted keyed data sent from the encrypted keypad.
  • The Source element is 'Keyed' when using an encrypted keypad for data capture.
  • In some cases the AVS and CVV is sent as part of the encrypted keyed data. In these cases you do not need to send the AVS and CVV elements.


 

AuthorizationRequest

Name Type Size Description
Amount String (Double) 1-100 The desired amount for the transaction.
CardAcceptorTerminalId String (numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 
MerchantKey String 0-8 The invoice or order number associated with the transaction.
MerchantTransactionId String 0-100 The merchant-defined identifier for the transaction.
RegisterNumber String 0-100 The identifier for the register or point of sale device submitting the transaction.

BoardingRequest

Name Type Size Description
MerchantDefinedToken String 0-40 This field is no longer supported.

CaptureRequest

Name Type Size Description
Token String 1-100 The token identifier returned from a previous pre-authorization transaction.
Amount String (Double) 1-100 The final transaction amount.
InvoiceNumber String 0-8 The invoice or order number associated with the transaction.
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.
CardAcceptorTerminalId String (Numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 

UpdateBoardedCardRequest

Name Type Size Description
VaultToken String 1-40 The token used to identify the payment method within the Merchantware Vault.
ExpirationDate String 4 The new expiration date of the payment card in MMYY format.

ForceCaptureRequest

Name Type Size Description
Amount String (Double) 1-100 The amount of the sale.
AuthorizationCode String 1-100 The authorization code for the sale, usually received from the processor as a voice authorization.
InvoiceNumber String 0-8 The invoice or order number associated with the transaction.
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.
CardAcceptorTerminalId String (Numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 

RefundRequest

Name Type Size Description
Amount String (Double) 0-100 The amount to refund.
InvoiceNumber String 0-8 The invoice or order number associated with the transaction.
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.
CardAcceptorTerminalId String (Numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 

Notes

The amount of the refund is not specified when performing a refund against a previous transaction, the full amount of the previous transaction is refunded.

SaleRequest

Name Type Size Description
Amount String (Double) 0-100 The amount of the sale.
CashbackAmount String (Double) 0-20 The optional amount the customer received as cash back from the transaction when performing sales using a debit card.
SurchargeAmount String (Double) 0-20 The optional surcharge fee or amount charged for the transaction when performing sales using a debit card.
TaxAmount String (Double) 0-100 The declared tax amount of the transaction.
HealthCareAmountDetails HealthCareAmountDetails (Not Required) The health care amount details used when processing FSA cards.
InvoiceNumber String 0-8 The invoice or order number associated with the transaction.
PurchaseOrderNumber String 0-100 The customer-defined identifier declaring a purchase order for the transaction.
CustomerCode String 0-100 The merchant-defined identifier for the customer involved in the transaction.
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.
CardAcceptorTerminalId String (Numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 
EnablePartialAuthorization String (bool) 0-5 Allow for only part of the total Amount to be authorized during the sale.
ForceDuplicate String (bool) 0-5 Overrides duplicate protection and allow the transaction to process normally.

Notes

The ForceDuplicate flag may be left blank if desired. Duplicate transaction behavior defaults to what was specified when the merchant's account was boarded.

The EnablePartialAuthorization flag may be left blank if desired.  If set to false or left unspecified, the transaction will decline if the full requested amount cannot be captured.
 

SignatureRequest

Name Type Size Description
Token String 1-100 The token identifier returned from a previous transaction.
ImageData String 1-20000 The encoded coordinates defining the drawn ligatures of the signature.

Notes

This ImageData field uses a simple format to denote ligatures from a drawn signature. A coordinate is defined by an integer, followed by a comma, followed by another integer, and then finally terminated with a caret. The first coordinate specifies the X or horizontal position. The second coordinate specifies the Y or vertical position. 0,0 is the top-left most coordinate. 65535,65535 is the bottom-right most coordinate.

100,100^

To specify the end of a segment, use the special coordinate 0,65535^ (Pen-up) in the string of text. At the very end of the list of coordinates, append a tilde at the end. Your data should resemble the following output.
10,10^110,110^0,65535^10,110^110,10^0,65535^~

The aforementioned string results in an X being drawn. It contains first the top-left corner to the bottom right corner, then a pen-up coordinate, then the bottom-left to the top-right coordinate, and then a pen-up coordinate.
A pen-up coordinate is not required at the very end, but for your own purposes, it may be useful to specify one when replaying the string for screen drawing or for an image.

The size limit for this method may be increased in the future. For the time being, if you find the size limit on this method is too restrictive, try reducing your sampling frequency when recording a signature, particularly if you are recording a signature from a desktop application. Most POS devices do not have nearly the same resolution as a windowed application on a PC, so a finely detailed signature is not required to create a comparable image.

For best results, the signature coordinates should fall within a 240 by 240 range of dimensions.
Negative coordinates and coordinates outside of 65535 for any dimension are rejected by the web service.
 

TipRequest

Name Type Size Description
Token String 1-100 The token identifier returned from a previous sale transaction.
Amount String (Double) 1-100 The tip amount used to adjust the total amount of the original sale.

VaultTokenRequest

Name Type Size Description
VaultToken String 1-40 The token used to identify the payment method within the Merchantware Vault.

VoidRequest

Name Type Size Description
Token String 1-100 The token identifier returned from a previous transaction.
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.
CardAcceptorTerminalId String (Numeric) 0-16 The Mastercard Card Acceptor Terminal Identifierused to uniquely identify the terminal to the processor. 

BatchResponse45

The BatchStatus45 response encapsulates the results of a retail batch operation in Merchantware.
Name Type Description
BatchStatus String The status of a batch; indicates success or failure.
AuthorizationCode String The Authorization Code or other batch identifier issued by the processor.
BatchAmount String (Double) The sum of all transactions within the batch.
TransactionCount Integer The number of transactions within the batch.
TransactionDate String (DateTime, UTC) The date and time when the batch was received, in UTC time.
ErrorMessage String A message indicating why the transaction could not be processed.
ExtraData String Contains extra information about the transaction, when applicable.

Used By

SettleBatch

SignatureResponse45

The SignatureResponse45 contains information about a signature appended to an existing transaction record. 
Name Type Description
UploadStatus String This value describes the upload result of the signature. This value is ACCEPTED if the signature was uploaded without errors, and FAILED if it could not be saved or if there were any other errors.
Token String The transaction reference identifier receiving the associated signature.
TransactionDate String (DateTime, UTC) The date of the signature upload attempt, as a string, in UTC time. This value is not stored by the server.
ErrorMessage Integer A message indicating why the transaction could not be processed.

Used By

AttachSignature

TransactionResponse45

Name Type Description
ApprovalStatus String The status of the transaction, whether approved or declined. This value may also have other definitions depending on CardType and context.
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.
AuthorizationCode String Authorization Code issued by the processor upon receipt of a transaction.
TransactionDate String (DateTime, UTC) The date and time when a transaction is issued, in UTC time.
Amount String (Double) The amount of the transaction. If partial authorizations are enabled, this will be the authorized amount and may be different than the requested amount.
RemainingCardBalance String (Double) The amount of money that remains on a card branded gift card or FSA card.
CardNumber String A string representing the truncated card number of the payment card used in the transaction.
Cardholder String The cardholder associated with the payment card used in a transaction.
CardType String (CardType Enumeration) A value from the CardType enumeration indicating the type of payment card used in a transaction.
FsaCard String (Boolean) A value indicating if the transaction was processed against an FSA card.
ReaderEntryMode String (ReaderEntryMode Enumeration) A value from the ReaderEntryMode enumeration indicating the reader mode used to capture data.
AvsResponse String This is a string describing the result of an Address Verification System lookup.
CvResponse String A string describing the result of a Card Verification check.
ErrorMessage String A message indicating why the transaction could not be processed.
ExtraData String Contains extra information, when applicable.
FraudScoring String Contains fraud scoring information, including:
  • ExternalReference: Kount's unique transaction ID
  • Recommendation: Can be Decline, Approve, Review, or Escalate
  • Score: Risk score between 1-99, the higher the risk score, the greater the risk of fraud
  • Status: Can be Success or Failure
Rfmiq String Recency-Frequency-Monetary IQ. An anonymized identifier representing the payment card used in the transaction. This field is optional and may not be returned.

Used By

AttachSignature, AdjustTip, Authorize, Capture, ForceCapture, Refund, Sale, Void

VaultBoardingResponse45

Name Type Description
VaultToken String The token used to identify the payment information within the Merchantware Vault.
ErrorCode String An error code associated with any problems that may have occurred when managing the boarding of payment information.
ErrorMessage String A message indicating why the boarding changes for a token failed.
Rfmiq String Recency-Frequency-Monetary IQ. An anonymized identifier representing the payment card used in the transaction. This field is optional and may not be returned.

Used By

BoardCard, UnboardCard, UpdateBoardedCard

VaultTokenResponse45

Name Type Description
CardNumber String A string representing the truncated card number of the payment card.
ExpirationDate String The expiration date of the payment card in MMYY format.
Cardholder String The owner or cardholder associated with the payment information.
CardType String (CardType) A value from the CardType enumeration indicating the type of payment card.
AvsStreetAddress String The street address associated with the payment card for use in address verification system (AVS) checks.
AvsZipCode String The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
ErrorCode String An error code associated with any problems that may have occurred during the retrieval of payment information.
ErrorMessage String A message indicating why the retrieval of payment information failed.
Rfmiq String Recency-Frequency-Monetary IQ. An anonymized identifier representing the payment card used in the transaction. This field is optional and may not be returned.

Used By

FindBoardedCard

Enumerations

ReaderEntryMode

Value Name Description
0 Unknown This value is reserved.
1 Keyed A TipRequest object containing the transactional data used to perform a tip adjustment.
2 Magneticstripe A transaction submitted from data swiped through a magnetic stripe reader.
3 Capture A transaction is a capture from a previous transaction or a forced capture.
4 Proximity A transaction submitted from a contactless reader.
5 LevelUpScanner A transaction submitted via a LevelUp scanner.
6 ICC A transaction submitted from data using an integrated circuit card.

CardType

Value Name
0 Unknown
1 American Express
2 Discover
3 Mastercard
4 Visa
5 Debit
6 EBT
7 Giftcard
8 Wright Express (Fleet Card)
9 Voyager (Fleet Card / USBank Issued)
10 JCB
11 China Union Pay
12 LevelUp