Account.redeemGiftCard

The redeemGiftCard method redeems a gift card represented by the input GiftCard object, and grants the resultant amount of credit to the Account. This method should be called after the statusInquiry method is called on the GiftCard object that you provide as input to this method. If the statusInquiry method indicates that status of the GiftCard object is Active, then call this method. For more information, see the Credit Subobject.

For redemption of a gift card, CashBox contacts a gift card processor. (CashBox currently supports InComm.) If the gift card is redeemable, the processor returns an SKU or a UPC number. This number is unique for each type of gift card and is decided by a prior agreement between you and the gift card processor. CashBox uses the number to look up a Product object with the same merchantProductId. CashBox then grants credit to the Account as defined in the creditGranted attribute of the Productobject. For each type of gift card you wish to accept, create Product objects with the appropriate amount of credit specified in their creditGranted attributes.

CashBox currently supports only full redemption of the credit associated with a gift card.

See Credit Grants and Gift Cards in the CashBox Programming Guide for more information on gift card redemption.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

account: an Account object to which credit will be granted if redemption of the gift card is successful. Populate the merchantAccountId or VID in this object so that CashBox can locate it in its database.

giftcard: a GiftCard object encapsulating information about the gift card you wish to redeem. For more information, see The GiftCard Object. Call statusInquiry before calling this method, to return the VID of the GiftCard object. Populate the VID in this object so that CashBox can look it up in its database.

credit: a Credit object specifying the amount and type of credit you wish to redeem. (This input parameter is currently unsupported.)

Output

return: an object of type Return that indicates the success or failure of the call.

giftcard: the GiftCard object with updated credit as granted by the gift card redemption.

account: the Account object to which credit was granted if redemption of the gift card was successful.

Returns

In addition to those listed in Standard Return Codes, this call returns:

Return Code	Return String
400	One of the following: Account not found. Failed to translate gift card error-description. Failed to redeem gift card error-description. Failed to retrieve gift card after redemption attempt. Failed to save Account after gift card redemption attempt. Failed to reload Account after gift card redemption attempt error-description. Redemption attempt failed for Gift Card ID gift-card-ID.

Example

// to redeem a gift card

$acct = new Account();

// account id for a customer's Account object for which the gift card
// will be redeemed, and credit added to the Account.

$acct->setMerchantAccountId('JDOE1234');

$gc = new GiftCard();

// set the VID of the gift card, obtained when we checked the
// status of the gift card, and determined that it is active

$gc->setVID($gcVID);

// Now make the SOAP API call to redeem the gift card

$response = $acct->redeemGiftCard($gc, null);

if ($response['returnCode'] == 200) {

// Redemption successful. Check if credit was added to the account

$updatedAcct = $response['data']->account;
$availableCredits = $updatedAcct->getCredit();
$availableTokens = $availableCredits->getTokenAmounts();

print "Available token credits: \n";
foreach($availableTokens as $tkAmt) {

print "Token type: " . $tkAmt->getMerchantTokenId() . " ";
print "Amount: " . $tkAmt->getAmount() . "\n";

}

// Also make sure status of the gift card is 'Redeemed'

$updatedGc = $response['data']->giftcard;

print "Status of the gift card: ";
print $updatedGc->getStatus()->getStatus() . "\n";

}

else {

// Error while granting credit to the account

print $response['returnString'] . "\n";

}