Merchantware 4.6

Note: Documentation for Merchantware 4.5 is available here

Service Information

Use the Gift Card web service for gift card and loyalty card processing.

Service Endpoint

https://ps1.merchantware.net/Merchantware/ws/ExtensionServices/v46/Giftcard.asmx

SOAP Usage and Notices

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

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.

Response

A GiftResponse46 is returned.

Example Reader SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <ActivateCard xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>READER</Source>            
                <TrackData>;6033590009112245097=64120000000000000?</TrackData>
            </PaymentData>
            <Request>
                <Amount>10.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </ActivateCard>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <ActivateCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <ActivateCardResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5097</CardNumber>
                <ErrorMessage />
                <ExpirationDate>1264</ExpirationDate>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>2</ReaderEntryMode>
                <ResponseMessage>00GMJK</ResponseMessage>
                <Token>1970128424</Token>
                <TransactionDate>01/22/2020 15:37:01</TransactionDate>
                <Gift>
                    <ApprovedAmount>10.00</ApprovedAmount>
                    <RequestedAmount>10.00</RequestedAmount>
                    <RedeemableBalance>10.00</RedeemableBalance>
                </Gift>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </ActivateCardResult>
        </ActivateCardResponse>
    </soap12:Body>
</soap12:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <ActivateCard xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>
                <CardNumber>6033590009112245099</CardNumber>
            </PaymentData>
            <Request>
                <Amount>10.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </ActivateCard>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <ActivateCardResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <ActivateCardResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5099</CardNumber>
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJL</ResponseMessage>
                <Token>1970130902</Token>
                <TransactionDate>01/22/2020 15:40:18</TransactionDate>
                <Gift>
                    <ApprovedAmount>10.00</ApprovedAmount>
                    <RequestedAmount>10.00</RequestedAmount>
                    <RedeemableBalance>10.00</RedeemableBalance>
                </Gift>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </ActivateCardResult>
        </ActivateCardResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example Reader Add Points By Currency Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>READER</Source>            
                <TrackData>;6033590009112245098=64120000000000000?</TrackData>
            </PaymentData>
            <Request>
                <AmountType>Currency</AmountType>
                <Amount>3.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddPoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <AddPointsResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate>1264</ExpirationDate>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>2</ReaderEntryMode>
                <ResponseMessage>00GMJM</ResponseMessage>
                <Token>1970135177</Token>
                <TransactionDate>01/22/2020 15:45:53</TransactionDate>
                <Loyalty>
                    <PointsType>POINTS</PointsType>
                    <ApprovedPoints>3</ApprovedPoints>
                    <PointsBalance>3003</PointsBalance>
                </Loyalty>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </AddPointsResult>
        </AddPointsResponse>
    </soap12:Body>
</soap12:Envelope>

Example Keyed Add Points By Currency Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>          
                <CardNumber>6033590009112245098</CardNumber>
            </PaymentData>
            <Request>
                <AmountType>Currency</AmountType>
                <Amount>3.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddPoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <AddPointsResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJN</ResponseMessage>
                <Token>1970138323</Token>
                <TransactionDate>01/22/2020 15:49:51</TransactionDate>
                <Loyalty>
                    <PointsType>POINTS</PointsType>
                    <ApprovedPoints>3</ApprovedPoints>
                    <PointsBalance>3006</PointsBalance>
                </Loyalty>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </AddPointsResult>
        </AddPointsResponse>
    </soap12:Body>
</soap12:Envelope>

Example Reader Add Points By Points Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>READER</Source>            
                <TrackData>;6033590009112245098=64120000000000000?</TrackData>
            </PaymentData>
            <Request>
                <AmountType>Points</AmountType>
                <Amount>300</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddPoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>***********5098</CardNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <Loyalty>
                    <PointsType>POINTS</PointsType>
                    <ApprovedPoints>300</ApprovedPoints>
                    <PointsBeforeNextReward>200</PointsBeforeNextReward>
                    <PointsBalance>300</PointsBalance>
                </Loyalty>
            </AddPointsResult>
        </AddPointsResponse>
    </soap12:Body>
</soap12:Envelope>

Example Keyed Add Points By Points Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>          
                <CardNumber>6033590009112245098</CardNumber>
            </PaymentData>
            <Request>
                <AmountType>Points</AmountType>
                <Amount>300</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddPoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddPointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>***********5098</CardNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <Loyalty>
                    <PointsType>POINTS</PointsType>
                    <ApprovedPoints>300</ApprovedPoints>
                    <PointsBeforeNextReward>200</PointsBeforeNextReward>
                    <PointsBalance>300</PointsBalance>
                </Loyalty>
            </AddPointsResult>
        </AddPointsResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example Reader SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddValue xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>READER</Source>            
                <TrackData>;6033590009112245098=64120000000000000?</TrackData>
            </PaymentData>
            <Request>
                <Amount>3.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddValue>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddValueResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <AddValueResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate>1264</ExpirationDate>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>2</ReaderEntryMode>
                <ResponseMessage>00GMJO</ResponseMessage>
                <Token>1970164239</Token>
                <TransactionDate>01/22/2020 16:18:53</TransactionDate>
                <Gift>
                    <ApprovedAmount>3.00</ApprovedAmount>
                    <RequestedAmount>3.00</RequestedAmount>
                    <RedeemableBalance>253.96</RedeemableBalance>
                </Gift>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </AddValueResult>
        </AddValueResponse>
    </soap12:Body>
</soap12:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddValue xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>          
                <CardNumber>6033590009112245098</CardNumber>
            </PaymentData>
            <Request>
                <Amount>3.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </AddValue>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <AddValueResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <AddValueResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJP</ResponseMessage>
                <Token>1970165895</Token>
                <TransactionDate>01/22/2020 16:20:38</TransactionDate>
                <Gift>
                    <ApprovedAmount>3.00</ApprovedAmount>
                    <RequestedAmount>3.00</RequestedAmount>
                    <RedeemableBalance>256.96</RedeemableBalance>
                </Gift>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </AddValueResult>
        </AddValueResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example Reader SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <BalanceInquiry xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>READER</Source>            
                <TrackData>;6033590009112245098=64120000000000000?</TrackData>
            </PaymentData>
            <Request>
                <InvoiceNumber>GIFT123</InvoiceNumber>
            </Request>
        </BalanceInquiry>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <BalanceInquiryResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <BalanceInquiryResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate>1264</ExpirationDate>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>2</ReaderEntryMode>
                <Token>1970169847</Token>
                <TransactionDate>01/22/2020 16:24:34</TransactionDate>
                <Gift>
                    <GiftBalance>256.96</GiftBalance>
                    <RewardsBalance>37.00</RewardsBalance>
                    <RedeemableBalance>293.96</RedeemableBalance>
                </Gift>
                <Loyalty>
                    <PointsBalance>3006</PointsBalance>
                </Loyalty>
            </BalanceInquiryResult>
        </BalanceInquiryResponse>
    </soap12:Body>
</soap12:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <BalanceInquiry xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>          
                <CardNumber>6033590009112245098</CardNumber>
            </PaymentData>
            <Request>
                <InvoiceNumber>GIFT123</InvoiceNumber>
            </Request>
        </BalanceInquiry>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <BalanceInquiryResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <BalanceInquiryResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber>***************5098</CardNumber>
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <Token>1970172834</Token>
                <TransactionDate>01/22/2020 16:27:32</TransactionDate>
                <Gift>
                    <GiftBalance>256.96</GiftBalance>
                    <RewardsBalance>37.00</RewardsBalance>
                    <RedeemableBalance>293.96</RedeemableBalance>
                </Gift>
                <Loyalty>
                    <PointsBalance>3006</PointsBalance>
                </Loyalty>
            </BalanceInquiryResult>
        </BalanceInquiryResponse>
    </soap12:Body>
</soap12:Envelope>

Refund

The Refund method returns 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.

Response

A GiftResponse46 is returned.

Example Previous Transaction SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>PREVIOUSTRANSACTION</Source>
                <Token>1970177862</Token>
            </PaymentData>
            <Request>
                <Amount>1.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
            </Request>
        </Refund>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <RefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <RefundResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber />
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJR</ResponseMessage>
                <Token>1970178389</Token>
                <TransactionDate>01/22/2020 16:32:55</TransactionDate>
                <Gift>
                    <ApprovedAmount>1.00</ApprovedAmount>
                    <RequestedAmount>1.00</RequestedAmount>
                    <RedeemableBalance>274.96</RedeemableBalance>
                </Gift>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </RefundResult>
        </RefundResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example Remove Points By Currency Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <RemovePoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>PREVIOUSTRANSACTION</Source>
                <Token>1970177862</Token>
            </PaymentData>
            <Request>
                <AmountType>Currency</AmountType>
                <Amount>3.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </RemovePoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <RemovePointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <RemovePointsResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber />
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJR</ResponseMessage>
                <Token>1970185732</Token>
                <TransactionDate>01/22/2020 16:39:49</TransactionDate>
                <Loyalty>
                    <PointsBalance>200277.96</PointsBalance>
                </Loyalty>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </RemovePointsResult>
        </RemovePointsResponse>
    </soap12:Body>
</soap12:Envelope>

Example Remove Points By Points Amount SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <RemovePoints xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>PREVIOUSTRANSACTION</Source>
                <Token>1319665708</Token>
            </PaymentData>
            <Request>
                <AmountType>Points</AmountType>
                <Amount>300</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </RemovePoints>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <RemovePointsResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>300</ApprovedPoints>
                    <PointsBalance>62346</PointsBalance>
                </Loyalty>
            </RemovePointsResult>
        </RemovePointsResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example Reader SOAP Request w/ Partial Approval

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>
                <MerchantTransactionId>a1234</MerchantTransactionId>
            </Request>
        </Sale>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>
    </soap12:Body>
</soap12:Envelope>

Example Keyed SOAP Request

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <PaymentData>
                <Source>KEYED</Source>
                <GiftCardPin>1234</GiftCardPin>
                <CardNumber>6033590009112245098</CardNumber>
            </PaymentData>
            <Request>
                <Amount>10.00</Amount>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <EnablePartialAuthorization></EnablePartialAuthorization>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </Request>
        </Sale>
    </soap12:Body>
</soap12:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <SaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/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>10.00</ApprovedAmount>
                    <RequestedAmount>10.00</RequestedAmount>
                    <RedeemableBalance>100.00</RedeemableBalance>
                </Gift>
            </SaleResult>
        </SaleResponse>
    </soap12:Body>
</soap12: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.

Response

A GiftResponse46 is returned.

Example SOAP Request using a Token

Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <Void xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <Credentials>
                <MerchantName>Zero Inc</MerchantName>
                <MerchantSiteId>00000000</MerchantSiteId>
                <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
            </Credentials>
            <Request>
                <Token>1970177862</Token>
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <MerchantTransactionId>TRX123</MerchantTransactionId>
            </Request>
        </Void>
    </soap12:Body>
</soap12:Envelope>

Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <VoidResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/46/Giftcard">
            <VoidResult>
                <ApprovalStatus>APPROVED</ApprovalStatus>
                <CardNumber />
                <ErrorMessage />
                <ExpirationDate />
                <InvoiceNumber>GIFT123</InvoiceNumber>
                <ReaderEntryMode>1</ReaderEntryMode>
                <ResponseMessage>00GMJR</ResponseMessage>
                <Token>1970198881</Token>
                <TransactionDate>01/22/2020 16:51:38</TransactionDate>
                <Gift>
                    <RedeemableBalance>283.96</RedeemableBalance>
                </Gift>
                <Loyalty>
                    <PointsBalance />
                </Loyalty>
                <CustomerEmailAddress>na@yahoo.com</CustomerEmailAddress>
            </VoidResult>
        </VoidResponse>
    </soap12:Body>
</soap12: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-19 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> 

ActivateCardRequest

Name Type Size Required? Description
Amount String (Decimal)  1-20 Yes The amount to be added to the card.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.
MerchantTransactionID String 0-100 No The merchant-defined identifier for the transaction.

AddPointsRequest

Name Type Size Required? Description
AmountType String 1-8 Yes The type of the amount specified. Possible values for AmountType are:
  • Currency
  • Points
Amount String (Decimal) 1-20 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.
MerchantTransactionId String 0-100 No The merchant-defined identifier for the transaction.

AddValueRequest

Name Type Size Required? Description
Amount String (Decimal) 1-20 Yes The amount to be added to the card.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.
MerchantTransactionId String 0-100 No The merchant-defined identifier for the transaction.

BalanceInquiryRequest

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

GiftRefundRequest

Name Type Size Required? Description
Amount String (Decimal) 1-20 Yes The amount to be refunded.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.
MerchantTransactionId String 0-100 No  The merchant-defined identifier for the transaction.

RemovePointsRequest

Name Type Size Required? Description
AmountType String 1-8 Yes The type of the amount specified. Possible values for AmountType are:
  • Currency
  • Points
Amount String (Decimal) 1-20 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.
MerchantTransactionId String 0-100 No The merchant-defined identifier for the transaction.

SaleRequest

Name Type Size Required? Description
Amount String (Decimal) 1-20 Yes The amount of the sale.
EnablePartialAuthorization String (Boolean) 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.
MerchantTransactionId String 0-100 No The merchant-defined identifier for the transaction.

GiftVoidRequest

Name Type Size Required? Description
Token String 0-100 No* The token identifier returned from a previous transaction.
InvoiceNumber String 0-100 No The invoice or order number associated with the transaction.
MerchantTransactionId String 0-100 No* The merchant-defined identifier for the transaction.
Note: You must provide either the Token, the MerchantTransactionId, or both. The payments platform favours the token when you supply both.

GiftResponse46

The GiftResponse46 structure encapsulates the results of Merchantware 4.6 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 Enumeration (ReaderEntryMode)  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, and 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 and 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, and Void

Fields

Name Type Required? Description
ApprovedPoints String (Integer) 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 String  No The type of points. Possible values are:
  • Points
  • Frequency
PointsBeforeNextReward String (Integer) No The number of points before the next reward.
PointsBalance String (Integer) 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.