Gift Card

Gift Card Transactions

The Gift Card web services provide payment and loyalty operations for gift cards.

 

Service Information

Service Endpoint - https://ps1.merchantware.net/Merchantware/ws/ExtensionServices/v45/Giftcard.asmx

Methods

ActivateCard

The ActivateCard method activates, and adds value to, a new stored value card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request ActivateCardRequest An Activation Request object containing the data used to add value to a new stored value card.

Types - ActivateCardRequest

Name Type Size Required? Description
Amount String (double) 1-100 Yes The dollar amount to be added to the card.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: Reader, Keyed

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <ActivateCard xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>            
            <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </ActivateCard>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <ActivateCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <ActivateCardResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </ActivateCardResult>
    </ActivateCardResponse>
  </soap:Body>
</soap:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <ActivateCard xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>KEYED</Source>            
            <CardNumber>1234567890123456</CardNumber>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </ActivateCard>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <ActivateCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <ActivateCardResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>1</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </ActivateCardResult>
    </ActivateCardResponse>
  </soap:Body>
</soap:Envelope>

AddPoints

The AddPoints method adds points to a card's point balance.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request AddPointsRequest An Add Points Request object containing the data used to add points to a card's point balance.

Types - AddPointsRequest

Name Type Size Required? Description
AmountType String Points OR Currency Yes The type of the amount specified.
Amount String (double) 1-100 Yes

The amount to be added to the card's points balance.

If AmountType is "points", the points balance is incremented.

If AmountType is "currency", the currency amount is converted to points before it is added to the points balance.

InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: Reader, Keyed

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Reader Add Points By Currency Amount SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>        
            <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
         </PaymentData>
         <Request>
            <AmountType>Currency</AmountType>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </AddPoints>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <AddPointsResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Loyalty>
          <PointsType>FREQUENCY</PointsType>
          <ApprovedPoints>1</ApprovedPoints>
          <PointsBeforeNextReward>5</PointsBeforeNextReward>
          <PointsBalance>7</PointsBalance>
        </Loyalty>
      </AddPointsResult>
    </AddPointsResponse>
  </soap:Body>
</soap:Envelope>

Example Keyed Add Points By Points Amount SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>KEYED</Source>          
            <CardNumber>1234567890123456</CardNumber>
         </PaymentData>
         <Request>
            <AmountType>Points</AmountType>
            <Amount>129</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </AddPoints>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <AddPointsResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>1</ReaderEntryMode>
        <Loyalty>
          <PointsType>POINTS</PointsType>
          <ApprovedPoints>129</ApprovedPoints>
          <PointsBeforeNextReward>200</PointsBeforeNextReward>
          <PointsBalance>300</PointsBalance>
        </Loyalty>
      </AddPointsResult>
    </AddPointsResponse>
  </soap:Body>
</soap:Envelope>

AddValue

The Add Value method adds value to a stored value card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request AddValueRequest An Add Value object containing the data used to add value to a stored value card.

Types - AddValueRequest

Name Type Size Required? Description
Amount String (double) 1-100 Yes The dollar amount to be added to the card.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: Reader, Keyed

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AddValue xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </AddValue>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <AddValueResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <AddValueResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </AddValueResult>
    </AddValueResponse>
  </soap:Body>
</soap:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <AddValue xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>KEYED</Source>          
            <CardNumber>1234567890123456</CardNumber>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </AddValue>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <AddValueResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <AddValueResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift> 
      </AddValueResult>
    </AddValueResponse>
  </soap:Body>
</soap:Envelope>

BalanceInquiry

The BalanceInquiry method inquires about balances on a stored value card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request BalanceInquiryRequest A BalanceInquiry object containing the data used to inquire about balances on a stored value card.

Types - BalanceInquiryRequest

Name Type Size Required? Description
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: Reader, Keyed

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Reader SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BalanceInquiry xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>
            <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
         </PaymentData>
         <Request>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </BalanceInquiry>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <BalanceInquiryResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <BalanceInquiryResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <GiftBalance>90.00</GiftBalance>
          <RewardsBalance>10.00</RewardsBalance>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
        <Loyalty>
          <PointsBalance>62346</PointsBalance>
        </Loyalty>
      </BalanceInquiryResult>
    </BalanceInquiryResponse>
  </soap:Body>
</soap:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <BalanceInquiry xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>KEYED</Source>          
            <CardNumber>1234567890123456</CardNumber>
         </PaymentData>
         <Request>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </BalanceInquiry>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <BalanceInquiryResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <BalanceInquiryResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <GiftBalance>90.00</GiftBalance>
          <RewardsBalance>10.00</RewardsBalance>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
        <Loyalty>
          <PointsBalance>62346</PointsBalance>
        </Loyalty>
      </BalanceInquiryResult>
    </BalanceInquiryResponse>
  </soap:Body>
</soap:Envelope>

Refund

The Refund method return stored dollar value back to a card.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request GiftRefundRequest A Gift Refund object containing the data used to return stored dollar value back to a card.

Types - GiftRefundRequest

Name Type Size Required? Description
Amount String (double) 1-100 Yes The amount to be refunded.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: PreviousTransaction

Return Values

A GiftResponse45 is returned.

SOAP Information

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/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PREVIOUSTRANSACTION</Source>           
            <Token>12345678</Token>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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/45/Giftcard">
      <RefundResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29<RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </RefundResult>
    </RefundResponse>
  </soap:Body>
</soap:Envelope>

RemovePoints

The RemovePoints method removes points from a card's point balance, which were added on a previous transaction.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request RemovePointsRequest A RemovePoints request object containing the data used to remove points from a card's point balance.

Types - RemovePointsRequest

Name Type Size Required? Description
AmountType String Points OR Currency Yes The type of the amount specified.
Amount String (double) 1-100 Yes

The amount to be removed from the card's point balance.

If AmountType is "points", the points balance is decremented.

if AmountType is "currency", the currency amount is converted to points before the points balance is decremented.

InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: PreviousTransaction

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Remove Points By Currency Amount SOAP Request

Sample Request Packet (raw)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <RemovePoints xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PREVIOUSTRANSACTION</Source>          
            <Token>12345678</Token>
         </PaymentData>
         <Request>
            <AmountType>Currency</AmountType>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </RemovePoints>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <RemovePointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <RemovePointsResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Loyalty>
          <PointsType>Frequency</PointsType>
          <ApprovedPoints>1</ApprovedPoints>
          <PointsBeforeNextReward>5</PointsBeforeNextReward>
          <PointsBalance>62346</PointsBalance>
        </Loyalty>
      </RemovePointsResult>
    </RemovePointsResponse>
  </soap:Body>
</soap:Envelope>

Example Remove Points By Points Amount SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <RemovePoints xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PREVIOUSTRANSACTION</Source>          
            <Token>12345678</Token>
         </PaymentData>
         <Request>
            <AmountType>Points</AmountType>
            <Amount>129</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </RemovePoints>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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>
    <RemovePointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
      <RemovePointsResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>1</ReaderEntryMode>
        <Loyalty>
          <PointsType>Points</PointsType>
          <ApprovedPoints>129</ApprovedPoints>
          <PointsBalance>62346</PointsBalance>
        </Loyalty>
      </RemovePointsResult>
    </RemovePointsResponse>
  </soap:Body>
</soap:Envelope>

Sale

The Sale method withdraws from a card's stored dollar value.

Arguments

Name Type Description
Credentials MerchantCredentials A MerchantCredentials object used to authenticate against MerchantWARE.
PaymentData GiftPaymentData A PaymentData object containing the payment details of the card used to process the transaction
Request GiftSaleRequest A Sale object containing the data used to withdraw from a card's stored dollar value.

Types - SaleRequest

Name Type Size Required? Description
Amount String (double) 1-100 Yes The amount of the sale.
EnablePartialAuthorization String (bool) 0-5 No

An indicator indicating whether to allow the sale to approve for a partial amount.

When set to True - If the balance of the card is less than the amount, the full balance of the card will be used.

When set to False - If the balance of the card is less than the amount, the transaction will decline. This is the default setting if field is not specified.

InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Types - GiftPaymentData

See GiftPaymentData data structure.
Allowed Sources: Reader, Keyed

Return Values

A GiftResponse45 is returned.

SOAP Information

Example Reader SOAP Request w/ Partial Approval

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/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>READER</Source>           
            <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
            <EnablePartialAuthorization>True</EnablePartialAuthorization>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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/45/Giftcard">
      <SaleResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>2</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.00</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </SaleResult>
    </SaleResponse>
  </soap:Body>
</soap:Envelope>

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/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>KEYED</Source>           
            <CardNumber>1234567890123456</CardNumber>
         </PaymentData>
         <Request>
            <Amount>1.29</Amount>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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/45/Giftcard">
      <SaleResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>1</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RequestedAmount>1.29</RequestedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </SaleResult>
    </SaleResponse>
  </soap:Body>
</soap:Envelope>

Void

The Void method voids a prior transaction.

For more guidance, see our Best Practices guide on Void Failure Handling.

Arguments

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

Types - GiftVoidRequest

Name Type Size Required? Description
Token String 1-100 Yes The token identifier returned from a previous transaction.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.

Return Values

A GiftResponse45 is returned.

SOAP Information

Example SOAP Request

Sample Request Packet (raw)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Void xmlns="http://schemas.merchantwarehouse.com/merchantware/45/Giftcard">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <Request>
            <Token>1234567890</Token>
            <InvoiceNumber>Transaction1000</InvoiceNumber>
         </Request>
      </Void>
   </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<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/45/Giftcard">
      <VoidResult>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <ResponseMessage>928061</ResponseMessage>
        <Token>MC0110</Token>
        <InvoiceNumber>Transaction1000</InvoiceNumber>
        <TransactionDate>10/10/2008 1:13:55 PM</TransactionDate>
        <ExpirationDate>080729</ExpirationDate>
        <CardNumber>***********3456</CardNumber>
        <ReaderEntryMode>0</ReaderEntryMode>
        <Gift>
          <ApprovedAmount>1.29</ApprovedAmount>
          <RedeemableBalance>100.00</RedeemableBalance>
        </Gift>
      </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.

GiftPaymentData

Name Type Size Source Description
Source String 1-100 ALL

The method used to supply the payment data.

READER or KEYED or PREVIOUSTRANSACTION

GiftCardPin String (integer) 0-4 ALL PIN printed on gift card. Required by some gift card providers.
TrackData String 1-500 READER The complete track data (all tracks) for the payment card returned from a card reader.
CardNumber String 13-19 KEYED The PAN or card number of the payment card.
Token String 1-100 PREVIOUSTRANSACTION The token identifier returned from a previous transaction.

Notes

You must define a "Source" type for all PaymentData. Depending on the source, please follow the information below..

Reader Payment Source

The TrackData should be unaltered raw swipe data from an unencrypted reader or from an IDTECH, IDTECH Enhanced, or Magtek encrypted reader.

Reader Example

<PaymentData>
   <Source>READER</Source>           
   <TrackData>%1234567890123456^GIFTCARD/TEST^00000000000000000?;1234567890123456=00000000000000000?</TrackData>
   <GiftCardPin>1234</GiftCardPin>
</PaymentData>

Keyed Example

<PaymentData>
   <Source>Keyed</Source>           
   <CardNumber>4012000033330026</CardNumber>
   <GiftCardPin>1234</GiftCardPin>
</PaymentData> 

GiftResponse45

The GiftResponse45 structure encapsulates the results of MerchantWARE 4.5 gift and loyalty transactions.

Fields

Name Type Required? Description
ApprovalStatus String Yes (Empty, String if none) The status of the transaction, whether approved or declined. This value may also have other definitions depending on CardType and context.
CardNumber String Yes (Empty, String if none) Represents the truncated card number of the payment card used in a transaction.
ExpirationDate String (Date) Yes (Empty, String if none) The expiration date of the card. MMDDYYYY format.
ErrorMessage string Yes (Empty, String if none) Contains a message describing the reason the transaction could not complete.
InvoiceNumber String Yes (Empty, String if none) The invoice or order number associated with the transaction.
ResponseMessage String Yes (Empty, String if none) Describes the result of an ApprovalStatus.
ReaderEntryMode Int (ReaderEntryMode Enumeration) Yes A value from the ReaderEntryMode enumeration indicating the reader mode used to capture data.
Token String Yes The identifier issued for the transaction. This value may be used to lookup a specific transaction in the history log.
TransactionDate String (DateTime, UTC) Yes The date and time when a transaction is issued, in UTC time.
Gift GiftDetail No

Details specific to a gift card transaction.

This is returned on the following methods: Activate, AddValue, ApplyTip, Refund, Sale, BalanceInquiry, Void.

Loyalty LoyaltyDetail No

Details specific to a loyalty transaction.

This is returned on the following methods: Activate, AddPoints, RemovePoints, BalanceInquiry, Void.

Notes

Card numbers are always truncated when methods return data in this structure.

ApprovalStatus currently may contain the values 'APPROVED' and 'DECLINED'.

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

The 'DECLINED' value may be returned on a decline or other failure.

DECLINED

GiftDetail

A GiftDetail structure encapsulates results specific to gift.  Returned on the following methods: Activate, AddValue, ApplyTip, Refund, Sale, TransferBalance, Void, BalanceInquiry.

Fields

Name Type Required? Description
ApprovedAmount String (double) No The amount of the approved transaction.
GiftBalance String (double) No Represents the truncated card number of the payment card used in a transaction.
RedeemableBalance String (double) Yes (Empty, String if none) The balance amount that can be redeemed: GiftBalance + RewardsBalance.
RequestedAmount String (double) No The amount of the requested transaction.
RewardsBalance String (double) No The balance amount earned from rewards.

LoyaltyDetail

A LoyaltyDetail structure encapsulates results specific to loyalty.  Returned on the following methods: AddPoints, RemovePoints, BalanceInquiry, Void

Fields

Name Type Required? Description
ApprovedPoints string (int) No

The number of points approved.

For Add points, this is the number of points added.

For Void/Remove, this is the number of points deducted.

PointsType Points or Frequency No The type of points.
PointsBeforeNextReward String (int) No The number of points before the next reward.
PointsBalance String (int) Yes (Empty, String if none) The points balance.

Enumerations

ReaderEntryMode

Value Name Description
0 Unknown This value is reserved.
1 Keyed A transaction submitted from a manual keyed entry.
2 Magneticstripe A transaction submitted from data swiped through a magnetic stripe reader.