Credit Transactions

Credit Transactions

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

Service Information

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

Methods

ApplyTip

The ApplyTip web method adds a tip amount to a prior transaction.

Arguments

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.
token string 1-100 The token identifier returned from a previous sale or post-authorization transaction.
tipAmount string (double) 1-100 The additional tip amount added to the original sale.

Return Values

A CreditResponse4 is returned.

Notes

This adds the tip amount to a prior sale in the current batch. It is not possible to apply a tip to a transaction settled in a previous batch.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/ApplyTip
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ApplyTip xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <token>1236559</token>
      <tipAmount>5.15</tipAmount>
    </ApplyTip>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ApplyTipResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <ApplyTipResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </ApplyTipResult>
    </ApplyTipResponse>
  </soap:Body>
</soap:Envelope>

CaptureSignatureTiff

The CaptureSignatureTiff web method appends a signature record to an existing transaction. This record is attached from a PKZIP-compatible archive file containing a TIFF image file.

Arguments

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.
token string 1-100 The token identifier returned from a previous transaction.
imageData string 1-25000 The base-64 encoded representation of a PKZIP-compatible file containing the signature image data in TIFF format.

Return Values

A SignatureResponse4 is returned.

Notes

There are no guidelines for the internal image's filename when uploading a Zip file on this method beyond what is specified for the Zip file format. However, the Zip file may only contain one file. Zip files containing more than one file are rejected at this time.

The size limit for the imageData argument is enforced for the Base-64 representation of the image. To achieve the best results with this method, use a LZW-encoded TIFF file as your upload media. This helps increase the upper limit on the size of the image data you can upload, as PKZIP compression methods often don't perform as well on image data. Also note, if you use LZW-encoded TIFF files, you are still required to upload them within a Zip file.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/CaptureSignatureTiff
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CaptureSignatureTiff
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <token>1</token>
      <imageData> [Base-64 encoded data] </imageData>
    </CaptureSignatureTiff>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CaptureSignatureTiffResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <CaptureSignatureTiffVectorResult>
        <ErrorMessage></ErrorMessage>
        <SignatureType>2</SignatureType>
        <Token>1</Token>
        <TransactionDate>8/15/2008 8:18:39 PM</TransactionDate>
        <UploadStatus>ACCEPTED</UploadStatus>
      </CaptureSignatureTiffResult>
    </CaptureSignatureTiffResponse>
  </soap:Body>
</soap:Envelope>
 
 

CaptureSignatureVector

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

Arguments

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.
token string 1-100 The token identifier returned from a previous transaction.
imageData string 1-4000 The encoded coordinates defining the drawn ligatures of the signature.

Return Values

A SignatureResponse4 is returned.

Notes

This method 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 a 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.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/CaptureSignatureVector
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CaptureSignatureVector
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <token>321</token>
      <imageData>10,10^110,110^0,65535^10,110^110,10^0,65535^~</imageData>
    </CaptureSignatureVector>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CaptureSignatureVectorResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <CaptureSignatureVectorResult>
        <ErrorMessage></ErrorMessage>
        <SignatureType>1</SignatureType>
        <Token>1</Token>
        <TransactionDate>8/15/2008 8:18:39 PM</TransactionDate>
        <UploadStatus>ACCEPTED</UploadStatus>
      </CaptureSignatureVectorResult>
    </CaptureSignatureVectorResponse>
  </soap:Body>
</soap:Envelope>

DebitSale

The DebitSale web method charges a given amount to a debit card or any other payment card that supports debit.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
cashbackAmount string (double) 0-20 The optional amount the customer received as cash back from the transaction.
forceDuplicate string 0-5 Override duplicate protection and allow the transaction to process normally.
registerNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.

Return Values

A CreditResponse4 is returned.

Notes

Data from Track 2 is required for the trackData parameter. However, the raw swipe may be sent in, 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 forceDuplicate flag may be left blank if desired. Duplicate transaction behavior will default to what was specified at the time the merchant's account was boarded.

This method does not attempt to cleanup Debit-specific parameters. Please note that some pin pads may prepend the KSN or PIN block with extra Zero digits. It is the developer's responsibility to ensure that the KSN and PIN are correctly relayed.

The surcharge amount and cashback amount fields are not checked against the actual amount. It is the developer's responsibility to ensure their validity if these values are specified.

This method identifies all cards simply as 'Debit' when a transaction is complete. This occurs even when other payment methods are available on the payment card, such as the hybrid Debit Mastercards or Visa Check Cards.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/DebitSale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DebitSale xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>SDT10C</invoiceNumber>
      <amount>20.00</amount>
      <trackData> «magnetic stripe data» </trackData>
      <pinBlock>D85B9FB08710F7FE</pinBlock>
      <pinKsn>1289990103800008</pinKsn>
      <surchargeAmount />
      <cashbackAmount />
      <forceDuplicate />
      <registerNumber></registerNumber>
    </DebitSale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DebitSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <DebitSaleResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </DebitSaleResult>
    </DebitSaleResponse>
  </soap:Body>
</soap:Envelope>

EmvAuthorize

The EmvAuthorize web method facilitates the online authorisation component of an EMV transaction.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-20 The amount of the sale.
customerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
poNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
taxAmount string (double) 0-100 The declared tax amount of 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.
entryMode string 1-100 The entry mode for this transaction. It can be either CONTACT or CONTACTLESS.
messageCorrelationId string 1-160 A unique identifier used for matching authorize and complete transactions, for example, a GUID which is a 128-bit value, an example can be seen in the request below.
cardAcceptorTerminalId string 1-16 The identifier for the terminal being used in the transaction.
pinBlock string 0-100 The PIN block received from a pinpad device.
pinKsn string 0-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
cashbackAmount string (double) 0-20 The optional amount the customer received as cash back from the transaction.
donationAmount string (double) 0-20 The optional donation amount that the customer submitted as part of the transaction.
userTipAmount string (double) 0-20 The optional tip amount that the customer submitted as part of the transaction.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
kernelSoftwareVersion string 0-20 The software version of the EMV kernel used in the transaction.
tlvData base64binary   The tlvData will conform to rules as set out in EMV Integrated Circuit Card Specifications for Payment Systems - Book 3 - Version 4.3 Annex B - Rules for BER-TLV Data Objects.
transactionType string 1-100 The transaction type for this transaction. It can be either SALE, AUTH or REFUND.

Return Values

A EmvAuthorizeResponse4 is returned.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/EmvAuthorize
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    	<cred:EmvAuthorize>
         <cred:merchantName>Zero Inc.</cred:merchantName>
         <cred:merchantSiteId>00000000</cred:merchantSiteId>
         <cred:merchantKey>00000-00000-00000-00000-00000</cred:merchantKey>
         <cred:invoiceNumber>00001</cred:invoiceNumber>
         <cred:amount>10.00</cred:amount>
         <cred:customerCode>cust-01</cred:customerCode>
         <cred:poNumber>po-01</cred:poNumber>
         <cred:taxAmount>1.00</cred:taxAmount>
         <cred:registerNumber>1</cred:registerNumber>
         <cred:merchantTransactionId>0001</cred:merchantTransactionId>
         <cred:entryMode>CONTACT</cred:entryMode>
         <cred:messageCorrelationID>00000a00-0000-0aa0-0a00-aa0aaa00000a</cred:messageCorrelationID>
         <cred:cardAcceptorTerminalID>123456</cred:cardAcceptorTerminalID>
         <cred:pinBlock></cred:pinBlock>
         <cred:pinKsn></cred:pinKsn>
         <cred:cashbackAmount>1.00</cred:cashbackAmount>
         <cred:donationAmount>1.00</cred:donationAmount>
         <cred:userTipAmount>1.00</cred:userTipAmount>
         <cred:surchargeAmount>1.00</cred:surchargeAmount>
         <cred:kernelSoftwareVersion>2.0</cred:kernelSoftwareVersion>
         <cred:tlvData>5A0847617390010100365F2A0208405F34010182027C008A00950500800080009A031506039B02E8009C01009F02060000000000019F03060000000000009F100706010A03A400029F1A0208409F21031120079F260897BD2C9D14777BA49F2701809F34030403029F360200029F37049AAE676F</cred:tlvData>
         <cred:transactionType>Sale</cred:transactionType>
      </cred:EmvAuthorize>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
      <EmvAuthorizeResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
         <EmvAuthorizeResult>
            <ApprovalStatus>Approved</ApprovalStatus>
            <Token>00000a00-0000-0aa0-0a00-aa0aaa00000a</Token>
            <TransactionDate>27/07/2015 12:55:01</TransactionDate>
            <TlvData>8A023030910835E71BC600820000</TlvData>
            <CashbackAmount>5.00</CashbackAmount>
            <DonationAmount>5.00</DonationAmount>
            <UserTipAmount>5.00</UserTipAmount>
            <SurchargeAmount>5.00</SurchargeAmount>
         </EmvAuthorizeResult>
      </EmvAuthorizeResponse>
  </soap:Body>
</soap:Envelope>

EmvComplete

The EmvComplete web method facilitates the completed transaction component of an EMV transaction.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-20 The amount of the sale.
customerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
poNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
taxAmount string 0-100 The declared tax amount of the transaction.
registerNumber string 0-100 The identifier for the register or point of sale device submitting the transaction.
token string 0-100 The identifier created by the terminal for a offline transaction or the the token received in the response from EMV Authorization. This value may be used to lookup a specific transaction in the history log.
merchantTransactionId string 0-100 The merchant-defined identifier for the transaction.
entryMode string 1-100 The entry mode for this transaction. It can be either CONTACT or CONTACTLESS.
messageCorrelationId string 1-160 A unique identifier used for matching authorize and complete transactions, for example, a GUID which is a 128-bit value, an example can be seen in the request below.
cardAcceptorTerminalId string 1-16 The identifier for the terminal being used in the transaction.
pinBlock string 0-100 The PIN block received from a pinpad device.
pinKsn string 0-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
cashbackAmount string (double) 0-20 The optional amount the customer received as cash back from the transaction.
donationAmount string (double) 0-20 The optional donation amount that the customer submitted as part of the transaction.
userTipAmount string (double) 0-20 The optional tip amount that the customer submitted as part of the transaction.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
kernelSoftwareVersion string 0-20 The Kernel software version used in the transaction.
tlvData base64binary   The tlvData will conform to rules as set out in EMV Integrated Circuit Card Specifications for Payment Systems - Book 3 - Version 4.3 Annex B - Rules for BER-TLV Data Objects.
transactionType string 1-100 The transaction type for this transaction. It can be either SALE, AUTH or REFUND.

Return Values

A EmvCompleteResponse4 is returned.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/EmvComplete
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    	<cred:EmvComplete>
         <cred:merchantName>Zero Inc.</cred:merchantName>
         <cred:merchantSiteId>00000000</cred:merchantSiteId>
         <cred:merchantKey>00000-00000-00000-00000-00000</cred:merchantKey>
         <cred:invoiceNumber>00001</cred:invoiceNumber>
         <cred:amount>10.00</cred:amount>
         <cred:customerCode>cust-01</cred:customerCode>
         <cred:poNumber>po-01</cred:poNumber>
         <cred:taxAmount>1.00</cred:taxAmount>
         <cred:registerNumber>1</cred:registerNumber>
         <cred:token>1</cred:token>
         <cred:merchantTransactionId>0001</cred:merchantTransactionId>
         <cred:entryMode>CONTACT</cred:entryMode>
         <cred:messageCorrelationID>00000a00-0000-0aa0-0a00-aa0aaa00000a</cred:messageCorrelationID>
         <cred:cardAcceptorTerminalID>123456</cred:cardAcceptorTerminalID>
         <cred:pinBlock></cred:pinBlock>
         <cred:pinKsn></cred:pinKsn>
         <cred:cashbackAmount>1.00</cred:cashbackAmount>
         <cred:donationAmount>1.00</cred:donationAmount>
         <cred:userTipAmount>1.00</cred:userTipAmount>
         <cred:surchargeAmount>1.00</cred:surchargeAmount>
         <cred:kernelSoftwareVersion>2.0</cred:kernelSoftwareVersion>
         <cred:tlvData>5A0847617390010100365F2A0208405F34010182027C008A00950500800080009A031506039B02E8009C01009F02060000000000019F03060000000000009F100706010A03A400029F1A0208409F21031120079F260897BD2C9D14777BA49F2701809F34030403029F360200029F37049AAE676F</cred:tlvData>
         <cred:transactionType>Sale</cred:transactionType>
      </cred:EmvComplete>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
      <EmvCompleteResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
         <EmvCompleteResult>
            <Status>Success</Status>
         </EmvCompleteResult>
      </EmvCompleteResponse>
  </soap:Body>
</soap:Envelope>

ForceSale

The ForceSale web method forces a charge to be issued upon a customer's credit card.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
authorizationCode string 1-100 The authorization code for the sale, usually received from the processor as a voice authorization.
amount string (double) 1-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
cardholder string 0-100 The cardholder name as it appears on the payment card.
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.

Return Values

A CreditResponse4 is returned.

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.

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.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/ForceSale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ForceSale
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>ZZF15</invoiceNumber>
      <authorizationCode>01234C</authorizationCode>
      <amount>1.15</amount>
      <cardNumber>4005550000000019</cardNumber>
      <expirationDate>1208</expirationDate>
      <cardholder>Visa Test Card</cardholder>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </ForceSale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ForceSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <ForceSaleResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </ForceSaleResult>
    </ForceSaleResponse>
  </soap:Body>
</soap:Envelope>

Level2Sale

The Level2Sale web method performs a Purchase Card Level-2 charge on a credit card using swiped card data.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
customerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
poNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
taxAmount string (double) 0-100 The declared tax amount of the transaction.
forceDuplicate string (bool) 0-5 Override duplicate protection and allow the transaction to process normally.
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.
entryMode string 0-100 The entry mode for this transaction. It can be either MAGNETICSTRIPE or PROXIMITY.

Return Values

A CreditLevel2Response4 is returned.

Notes

To meet the best qualification level possible when processing commercial cards, you should set the customer code, purchase order number, and tax amount. Omitting any of these values may cause your transactions to downgrade, which increases your Merchant's transaction costs.

The trackData should be unaltered raw swipe data from unencrypted readers or from IDTech, IDTech Enhanced, Magtek encrypted readers.

The purchase order number is optional, and if left blank, is automatically filled in with the invoice number. However, the customer code is not automatically filled in. The intended usage of a customer code is to cross-reference a customer that the merchant can identify when presented with this code. If the invoice number is sufficient for this, the developer may copy the invoice number into this field. Otherwise, use a better identifier such as your integrating system's identifier for the customer or the customer's name for this field.

The tax amount specifies the amount of tax applied in the transaction, but it is not a charge amount. It is assumed by all processing parties that the tax amount has already been included in the transaction amount.

It is a bad idea to use cardholder data for any portion of the customer code or purchase order number. Card data specified in these fields is not masked or truncated and thus may put your customer at risk.

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 entryMode is defaulted to MAGNETICSTRIPE if it is left blank.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/Level2Sale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Level2Sale
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>ZZS8</invoiceNumber>
      <amount>1.08</amount>
      <trackData> [magnetic stripe data] </trackData>
      <customerCode>ref-ABC-Inc</customerCode>
      <poNumber>Invoice2008Sep21</poNumber>
      <taxAmount>.06</taxAmount>
      <forceDuplicate></forceDuplicate>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
      <entryMode></entryMode>
    </Level2Sale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Level2SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <Level2SaleResult>
        <Amount>1.18</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>06911B</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder>Discover Test Card</Cardholder>
        <CardNumber>************1117</CardNumber>
        <CardType>1</CardType>
        <CustomerCode>ref-ABC-Inc</CustomerCode>
        <CvResponse></CvResponse>
        <EntryMode>1</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber>ZZS22</InvoiceNumber>
        <PurchaseOrderNumber>Invoice2008Sep11</PurchaseOrderNumber>
        <TaxAmount>0.07</TaxAmount>
        <Token>981167</Token>
        <TransactionDate>2008-09-19 17:37:13.500</TransactionDate>
        <TransactionType>1</TransactionType>
      </Level2SaleResult>
    </Level2SaleResponse>
  </soap:Body>
</soap:Envelope>

Level2SaleKeyed

The Level2SaleKeyed web method performs a Purchase Card Level-2 charge on a credit card using keyed card information.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
cardholder string 0-100 The cardholder name as it appears on the payment card.
avsStreetAddress string 0-100 The street address associated with the payment card for use in address verification system (AVS) checks.
avsStreetZipCode string 0, 5, or 9 The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
cardSecurityCode string 0-100 The security code (CVD, CVV, CVC, etc.) of the payment card for use in card verification (CV) checks.
customerCode string 0-100 The merchant-defined identifier for the customer involved in the transaction.
poNumber string 0-100 The customer-defined identifier declaring a purchase order for the transaction.
taxAmount string (double) 0-100 The declared tax amount of the transaction.
forceDuplicate string (bool) 0-5 Override duplicate protection and allow the transaction to process normally.
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.

Return Values

A CreditLevel2Response4 is returned.

Notes

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 CV Code is composed of the three extra digits printed on the back of most credit cards, although most American Express cards, instead, have a four digit number displayed on the front of the card.

Although you are not required to send in the invoice number, AVS info, or CV info; it is in your best interest to obtain and send the relevant info. This helps to prevent the transaction from being downgraded at the processor, which in turn saves money on your Merchant's transaction costs.

To meet the best qualification level possible when processing commercial cards, you should set the customer code, purchase order number, and tax amount. Omitting any of these values may cause your transactions to downgrade, which increases your Merchant's transaction costs.

The purchase order number is optional, and if left blank, is automatically filled in with the invoice number. However, the customer code is not automatically filled in. The intended usage of a customer code is to cross-reference a customer that the merchant can identify when presented with this code. If the invoice number is sufficient for this, the developer may copy the invoice number into this field. Otherwise, use an better identifier such as your integrating system's identifier for the customer or the customer's name for this field.

The tax amount specifies the amount of tax applied in the transaction, but it is not a charge amount. It is assumed by all processing parties that the tax amount has already been included in the transaction amount.

It is a bad idea to use cardholder data for any portion of the customer code or purchase order number. Card data specified in these fields is not masked or truncated and thus may put your customer at risk.

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

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/Level2SaleKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Level2SaleKeyed
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>ZZS4</invoiceNumber>
      <amount>1.04</amount>
      <cardNumber>4005550000000019</cardNumber>
      <expirationDate>1208</expirationDate>
      <cardholder>Visa Test Card</cardholder>
      <avsStreetAddress>123 Main Street</avsStreetAddress>
      <avsStreetZipCode>02110</avsStreetZipCode>
      <cardSecurityCode>567</cardSecurityCode>
      <customerCode>ref-ABC-Inc</customerCode>
      <poNumber>Invoice2008Sep20</poNumber>
      <taxAmount>.05</taxAmount>
      <forceDuplicate></forceDuplicate>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </Level2SaleKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Level2SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <Level2SaleResult>
        <Amount>1.18</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>06911B</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder>Discover Test Card</Cardholder>
        <CardNumber>************1117</CardNumber>
        <CardType>1</CardType>
        <CustomerCode>ref-ABC-Inc</CustomerCode>
        <CvResponse></CvResponse>
        <EntryMode>2</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber>ZZS22</InvoiceNumber>
        <PurchaseOrderNumber>Invoice2008Sep11</PurchaseOrderNumber>
        <TaxAmount>0.07</TaxAmount>
        <Token>981167</Token>
        <TransactionDate>2008-09-19 17:37:13.500</TransactionDate>
        <TransactionType>1</TransactionType>
      </Level2SaleResult>
    </Level2SaleResponse>
  </soap:Body>
</soap:Envelope>

PostAuthorization

The PostAuthorization web method completes the transaction process for a prior pre-authorization.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the prior pre-authorization.
token string 1-100 The token identifier returned from a previous pre-authorization transaction..
amount string (double) 1-100 The final transaction amount.
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.

Return Values

A CreditResponse4 is returned.

Notes

This method captures a previous pre-authorization and adds it to the current batch for settlement.

If you wish to cancel a transaction created with the PostAuthorization method, you may use the Void method. However they cannot be applied once the transaction has been batched.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/PostAuthorization
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PostAuthorization
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>PA0098</invoiceNumber>
      <token>1567894</token>
      <amount>1.56</amount>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </PostAuthorization>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PostAuthorizationResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <PostAuthorizationResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </PostAuthorizationResult>
    </PostAuthorizationResponse>
  </soap:Body>
</soap:Envelope>

PreAuthorization

The PreAuthorization web method applies an authorization to a credit card using swiped card data.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The desired amount for the transaction.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
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.
entryMode string 0-100 The entry mode for this transaction. It can be either MAGNETICSTRIPE or PROXIMITY.

Return Values

A CreditResponse4 is returned.

Notes

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 unencrypted readers or from IDTech, IDTech Enhanced, Magtek encrypted readers.

To finish committing a transaction, the token obtained from this method should be used with the PostAuthorization web method. Do not use the ForceSale method to complete transactions, as this will cause downgrades and increased fees.

The entryMode is defaulted to MAGNETICSTRIPE if it is left blank.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/PreAuthorization
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PreAuthorization
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>YYY003</invoiceNumber>
      <amount>1.00</amount>
      <trackData> [magnetic stripe data] </trackData>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
      <entryMode></entryMode>
    </PreAuthorization>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PreAuthorizationResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <PreAuthorizationResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </PreAuthorizationResult>
    </PreAuthorizationResponse>
  </soap:Body>
</soap:Envelope>

PreAuthorizationKeyed

The PreAuthorizationKeyed web method applies an authorization to a credit card using keyed card information.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The desired amount for the transaction.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
cardholder string 0-100 The cardholder name as it appears on the payment card.
avsStreetAddress string 0-100 The street address associated with the payment card for use in address verification system (AVS) checks.
avsStreetZipCode string 0, 5, or 9 The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
cardSecurityCode string 0-100 The security code (CVD, CVV, CVC, etc.) of the payment card for use in card verification (CV) checks.
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.

Return Values

A CreditResponse4 is returned.

Notes

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

Although you are not required to send in the invoice number, AVS info, or CV info; it is in your best interest to obtain and send the relevant info. This helps prevent the transaction from being downgraded at the processor.

To finish committing a transaction, the token obtained from this method should be used with the PostAuthorization web method. Do not use the Force method to complete transactions, as this will cause downgrades and increased fees.

Authorizations become invalid after being batched, so ensure that all desired transactions are completed before issuing a batch.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/PreAuthorizationKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PreAuthorizationKeyed
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>TT0017</invoiceNumber>
      <amount>1.00</amount>
      <cardNumber>4005550000000019</cardNumber>
      <expirationDate>1210</expirationDate>
      <cardholder>Visa Test Card</cardholder>
      <avsStreetAddress>123 Main Street</avsStreetAddress>
      <avsStreetZipCode>02110</avsStreetZipCode>
      <cardSecurityCode>567</cardSecurityCode>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </PreAuthorizationKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PreAuthorizationKeyedResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <PreAuthorizationKeyedResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </PreAuthorizationKeyedResult>
    </PreAuthorizationKeyedResponse>
  </soap:Body>
</soap:Envelope>

Refund

The Refund web method issues a credit card refund to a customer from a prior transaction reference.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
token string 1-100 The token identifier returned from a previous transaction.
overrideAmount string (double) 0-100 The desired refund amount if different from the amount of the original 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.

Return Values

A CreditResponse4 is returned.

Notes

Credit and LevelUp refunds are supported.

  • Credit refunds can be partial and are specified by the overrideAmount parameter.
  • LevelUp only supports full refunds. overrideAmount parameter should be empty or full amount.

Only full refunds are supported by LevelUp

The lookup can be performed either by invoiceNumber or token. They cannot both be blank. If both are presented, token is used.

This method issues a refund to a credit 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. 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).

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.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/Refund
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>rbr0100</invoiceNumber>
      <token>654982</token>
      <overrideAmount>1.01</overrideAmount>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </Refund>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <RefundResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </RefundResult>
    </RefundResponse>
  </soap:Body>
</soap:Envelope>

RepeatSale

The RepeatSale web method charges a customer's credit card from a prior transaction.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
token string 1-100 The token identifier returned from a previous transaction.
overrideAmount string (double) 0-100 The amount of the sale if different from the original transaction amount.
expirationDate string 4 The expiration date of the payment card in MMYY format.
avsStreetAddress string 0-100 The street address associated with the payment card for use in address verification system (AVS) checks.
avsStreetZipCode string 0, 5, or 9 The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
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.

Return Values

A CreditResponse4 is returned.

Notes

This method causes another sale transaction to be issued against a customer's card. This method uses information from a prior transaction to issue the sale. No on-hand credit card information is required to use this method.

Please note that using this method more than once in the same batch may cause duplicate transaction failures. This can also be caused by any other transaction method attempting to perform a sale for the same amount against the same card of the same customer.

It is acceptable to store AVS information and reuse it for future Repeat Sales, as you would be retrieving this information from other customer data that is already stored outside of payment scope.

Regardless of how the initial transaction was created, new transactions created through this method will appear at the processor as Keyed transactions. Thus, depending on the type of account, additional sale transactions that are created through this method may qualify at a worse rate than normal sales. This will always be the case when your primary method of card acceptance is through swiped transactions.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/RepeatSale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <RepeatSale xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>rs030109</invoiceNumber>
      <token>164682</token>
      <overrideAmount>1.15</overrideAmount>
      <expirationDate>1208</expirationDate>
      <avsStreetAddress>25</avsStreetAddress>
      <avsStreetZipCode>02110</avsStreetZipCode>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </RepeatSale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <RepeatSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <RepeatSaleResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </RepeatSaleResult>
    </RepeatSaleResponse>
  </soap:Body>
</soap:Envelope>

Sale

The Sale web method charges a credit card using swiped card data.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
forceDuplicate string (bool) 0-5 Override duplicate protection and allow the transaction to process normally.
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.
entryMode string 0-100 The entry mode for this transaction. It can be either MAGNETICSTRIPE or PROXIMITY.

Return Values

A CreditResponse4 is returned.

Notes

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 unencrypted readers or from IDTech, IDTech Enhanced, Magtek encrypted readers.

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 entryMode is defaulted to MAGNETICSTRIPE if it is left blank.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/Sale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Sale
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>ZZS20</invoiceNumber>
      <amount>1.20</amount>
      <trackData> [magnetic stripe data] </trackData>
      <forceDuplicate></forceDuplicate>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
      <entryMode></entryMode>
    </Sale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <SaleResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </SaleResult>
    </SaleResponse>
  </soap:Body>
</soap:Envelope>

SaleKeyed

The SaleKeyed web method charges a credit card using keyed card information.

Arguments

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.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
cardholder string 0-100 The cardholder name as it appears on the payment card.
avsStreetAddress string 0-100 The street address associated with the payment card for use in address verification system (AVS) checks.
avsStreetZipCode string 0, 5, or 9 The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
cardSecurityCode string 0-100 The security code (CVD, CVV, CVC, etc.) of the payment card for use in card verification (CV) checks.
forceDuplicate string (bool) 0-5 Override duplicate protection and allow the transaction to process normally.
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.

Return Values

A CreditResponse4 is returned.

Notes

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

Although you are not required to send in the invoice number, AVS info, or CV info; it is in your best interest to obtain and send the relevant info. This helps prevent the transaction from being downgraded at the processor.

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

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/SaleKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SaleKeyed
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>ZZS17</invoiceNumber>
      <amount>1.17</amount>
      <cardNumber>4005550000000019</cardNumber>
      <expirationDate>1208</expirationDate>
      <cardholder>Visa Test Card</cardholder>
      <avsStreetAddress>123 Main Street</avsStreetAddress>
      <avsStreetZipCode>02110</avsStreetZipCode>
      <cardSecurityCode>567</cardSecurityCode>
      <forceDuplicate></forceDuplicate>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </SaleKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SaleKeyedResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <SaleKeyedResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </SaleKeyedResult>
    </SaleKeyedResponse>
  </soap:Body>
</soap:Envelope>

SettleBatch

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

Arguments

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.

Return Values

A BatchResponse4 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.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/SettleBatch
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SettleBatch
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
    </SettleBatch>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SettleBatchResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <SettleBatchResult>
        <AuthorizationCode>155</AuthorizationCode>
        <BatchAmount>7.15</BatchAmount>
        <BatchStatus>SUCCESS</BatchStatus>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <Token></Token>
        <TransactionCount>6</TransactionCount>
        <TransactionDate>2008-09-01 13:10:00.000</TransactionDate>
      </SettleBatchResult>
    </SettleBatchResponse>
  </soap:Body>
</soap:Envelope>

Void

The Void web method voids a prior transaction.

Arguments

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

Return Values

A CreditResponse4 is returned.

Notes

This removes a transaction from the current batch. It is not possible to void a transaction settled in a previous batch.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Credit/Void
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Void
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <token>768450</token>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </Void>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VoidResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <VoidResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </VoidResult>
    </VoidResponse>
  </soap:Body>
</soap:Envelope>

VoidPreAuthorization

deprecated

This method is deprecated and is no longer supported for new integrations. If you have questions, please contact our Integrations Team at integrations@cayan.com.

The VoidPreAuthorization web method voids a prior authorization.

Arguments

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

Return Values

A CreditResponse4 is returned.

Notes

This removes a transaction from the current batch. It is not possible to void a transaction settled in a previous batch.

SOAP Information

SOAPAction
    http://schemas.merchantwarehouse.com/merchantware/40/Credit/VoidPreAuthorization
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VoidPreAuthorization
     xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <token>768450</token>
      <registerNumber></registerNumber>
      <merchantTransactionId></merchantTransactionId>
    </VoidPreAuthorization>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <VoidPreAuthorizationResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Credit/">
      <VoidPreAuthorizationResult>
        <Amount>5.00</Amount>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>MC0110</AuthorizationCode>
        <AvsResponse></AvsResponse>
        <Cardholder></Cardholder>
        <CardNumber></CardNumber>
        <CardType>0</CardType>
        <CvResponse></CvResponse>
        <EntryMode>0</EntryMode>
        <ErrorMessage></ErrorMessage>
        <ExtraData></ExtraData>
        <InvoiceNumber></InvoiceNumber>
        <Token>1236564</Token>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <TransactionType>7</TransactionType>
      </VoidPreAuthorizationResult>
    </VoidPreAuthorizationResponse>
  </soap:Body>
</soap:Envelope>

Data Structures

BatchResponse4

The BatchResponse4 structure encapsulates the results of a retail batch operation in the Merchantware system.

Fields

Name Type Description
AuthorizationCode string The Authorization Code or other batch identifier issued by the processor.
BatchAmount string (double) The sum of all transactions within the batch.
BatchStatus string The status of a batch; indicates success or failure.
ErrorMessage string A message indicating why the transaction could not be processed.
ExtraData string Contains extra information, when applicable.
Token string The identifier received by the Merchantware client when a batch has been issued. If present, this value may be used to lookup a specific batch in the history log. Depending on the processor, this value may be blank.
TransactionCount int The number of transactions within the batch.
TransactionDate string (DateTime, UTC) The date and time when a batch was received, in UTC time.

Notes

Some fields in this structure may be blank depending on the processor and type of account.

A detailed explanation of error status values is available here.

References

A BatchResponse4 is returned by these web methods:

Credit Responses

CreditLevel2Response4

The CreditLevel2Response4 structure encapsulates the results of a retail Merchantware Purchase-Card Level 2 transaction.

Fields

Name Type Description
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.
ApprovalStatus string The status of the transaction, whether approved or declined. This value may also have other definitions depending on CardType and context.
AuthorizationCode string Authorization Code issued by the processor upon receipt of a transaction.
AvsResponse string This is a string describing the result of an AVS lookup.
Cardholder string The Cardholder associated with the payment card used in a transaction.
CardNumber string A string representing the truncated card number of the payment card used in a transaction.
CardType int (CardType) A value from the CardType enumeration indicating the type of payment card used in a transaction.
CustomerCode string This is client-defined string of the reference code declaring the customer involved in the transaction.
CvResponse string A string describing the result of a Card Verification or CVD check.
EntryMode int (POSEntryType) A value from the POSEntryType enumeration indicating the method used to submit a transaction.
ErrorMessage string A message indicating why the transaction could not be processed.
ExtraData string Contains extra information, when applicable.
InvoiceNumber string The invoice or order number associated with the transaction.
PurchaseOrderNumber string This is a client-string declaring the purchase order number for this customer and transaction.
TaxAmount string The declared tax amount of the transaction.
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.
TransactionDate string (DateTime, UTC) The date and time when a transaction is issued, in UTC time.
TransactionType int A value from the TransactionType enumeration indicating the type of transaction.

Notes

When an instance of this structure is received from a credit sale, the purchase order number is automatically filled in with a copy of the invoice number if it was not specified.

Card numbers are always truncated when methods return data in this structure. Some items may not be applicable to all applications, such as the AVS and CV response.

ApprovalStatus currently may contain 'APPROVED', 'DECLINED', 'REFERRAL'. In addition, it may have 'DUPLICATE' appended with a comma when it is known that duplicate transactions were the reason for the decline.

Only the value 'APPROVED' will be returned on any approval. It is safe to assume that no charge, refund, or any other action or transfer of value has occurred if you do not receive this return value.

APPROVED

Any of these values and possibly other values may be returned on a decline or other failure.

DECLINED DECLINED,DUPLICATE REFERRAL

A detailed explanation of error status values is available here.

References

A CreditLevel2Response4 is returned by these web methods:

CreditResponse4

The CreditResponse4 structure encapsulates the results of a retail Merchantware transaction.

Fields

Name Type Description
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.
ApprovalStatus string The status of the transaction, whether approved or declined. This value may also have other definitions depending on CardType and context.
AuthorizationCode string Authorization Code issued by the processor upon receipt of a transaction.
AvsResponse string A string describing the result of an AVS lookup.
Cardholder string The Cardholder associated with the payment card used in a transaction.
CardNumber string A string representing the truncated card number of the payment card used in a transaction.
CardType int (CardType) The issuer type of payment card used in a transaction. This value matches up with the CardType enumeration.
CvResponse string A string describing the result of a Card Verification or CVD check.
EntryMode int (POSEntryType) A value from the POSEntryType enumeration indicating the method used to submit a transaction.
ErrorMessage string A message indicating why the transaction could not be processed.
ExtraData string Contains extra information, when applicable.
InvoiceNumber string The invoice or order number associated with the transaction.
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.
TransactionDate string (DateTime, UTC) The date and time when a transaction is issued, in UTC time.
TransactionType int The type of transaction, and this value matches up with the TransactionType enumeration.

Notes

Card numbers are always truncated when methods return data in this structure. Some items may not be applicable to all applications, such as the AVS and CV response.

ApprovalStatus currently may contain the values 'APPROVED', 'DECLINED', and 'REFERRAL'. In addition, it may have 'DUPLICATE' appended with a comma; when it is known that duplicate transactions were the reason for the decline. A 'REFERRAL' response indicates that the processor should be contacted for an authorization code or for further instructions regarding balance limits or fraud.

Only the value 'APPROVED' will be returned on any approval. It is safe to assume that no charge, refund, or any other action or transfer of value has occurred if you do not receive this return value.

APPROVED

Any of these values and possibly other values may be returned on a decline or other failure.

DECLINED DECLINED,DUPLICATE REFERRAL

A detailed explanation of error status values is available here.

References

A CreditResponse4 is returned by these web methods:

EMV Responses

EmvAuthorizeResponse4

The EmvAuthorizeResponse4 structure encapsulates the results of a retail EmvAuthorize Merchantware transaction.

Fields

Name Type Description
ApprovalStatus string The status of the EMV Authorization message.  Please see the breakdown below.
ErrorMessage string An error message which describes why the EMV Authorization method could not proceed.
Token string The identifier received by the Merchantware client. This value may be used to lookup a specific transaction in the history log.
TransactionDate string (DateTime, UTC) The date and time when a transaction is issued, in UTC time.
TlvData base64Binary tlvData will conform to rules as set out in EMV Integrated Circuit Card Specifications for Payment Systems - Book 3 - Version 4.3 Annex B - Rules for BER-TLV Data Objects.
CashbackAmount string (double) The authorized Cash Back amount.
DonationAmount string (double) The authorized Donation amount.
UserTipAmount string (double) The authorized Tip amount.
SurchargeAmount string (double) The authorized Surcharge amount.

Notes

ApprovalStatus currently may contain the values 'Unknown', 'Approved', 'Failed', 'Declined', 'DeclinedDuplicate' and 'Referral'.

Approved

Any of these values and possibly other values may be returned on a decline or other failure.

Unknown, Failed, Declined, DeclinedDuplicate, Referral

A detailed explanation of error status values is available here.

References

An EmvAuthorizeResponse4 is returned by the following web methods:

EmvCompleteResponse4

The EmvCompleteResponse4 structure encapsulates the results of a retail EmvComplete Merchantware transaction.

Fields

Name Type Description
Status string The Status of the EMV Complete message.  It can be either Success, Duplicate, Failure or Error.
ErrorMessage string An error message which describes why the EMV Complete method could not proceed.

Notes

ApprovalStatus currently may contain the values 'Success', 'Duplicate', 'Failure' or 'Error'.

Only the value 'Success' will be returned on a successful completion.

Success

Any of these values and possibly other values may be returned on a decline or other failure.

Duplicate, Failure, Error

On a 'Failure' reponse, there is a possibility for a retry, e.g. if an unknown error occurs.

A detailed explanation of error status values is available here.

References

An EmvCompleteResponse4 is returned by the following web methods:

SignatureResponse4

The SignatureResponse4 structure contains information about a signature appended to an existing transaction record.

Fields

Name Type Description
ErrorMessage string A message indicating why the transaction could not be processed.
Token string The transaction reference ID receiving the associated signature.
TransactionType int (SignatureType) This value denotes the format of the signature.
UploadDate string (DateTime, UTC) The date of the signature upload attempt, as a string, in UTC time. This value is not stored by the server.
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.

Notes

This method sets the UploadStatus to error status keywords as defined in the error handling update, but does not return any extended error information.

References

A SignatureResponse4 is returned by these web methods: