Using Credits with an Account

The read-only credit attribute of the Account object holds the current credits available to the Account. Use the grantCredit and revokeCredit calls to manipulate credit. These methods generate appropriate audit trails of credit changes. Do not set the value of this attribute directly. (For example, when creating a new Account object by calling update().) Note: Use token-related methods such as Account.incrementTokens() or decrementTokens\(\) to manipulate tokens available to the Account. Subscribe can handle tokens both as payment methods outside the credit framework, and as part of the credit system. Although you can use Tokens interchangeably across the two systems, Vindicia recommends that in your implementation, you choose one system, rather than mixing the two. If you have not previously implemented a token-as-payment-method system, choose credit-based token management, because the Credit object allows you to abstract the type of credit, and therefore offers more flexibility for future replacement.

Granting Credit to an `Account`

If a customer performs a specific activity at your site, you may choose to give that customer credit. For example, if a customer redeems a phone card, a cell phone company may add a number of cell phone minutes to the customer’s account. You may also apply currency credits to the account. Use the Credit’s name-value pairs to define the reason for the Grant, and to provide another field by which your Credit activity may be analyzed. Use Account.grantCredit to add credit to an Account:

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('jdoe101');
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that you have already created
// a Token object with this id.)
 
$tok->setMerchantTokenId('ANYTIME_PHONE_MINUTES_2010');
 
$tokAmt = new TokenAmount();
$tokAmt->setToken($tok);
$tokAmt->setAmount(100);
 
$cr = new Credit();
$cr->setTokenAmounts(array($tokAmt));
 
// make the SOAP API call to grant credit to the acct
$response = $acct->grantCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully granted to the account
 
$updatedAcct = $response->['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";
}
}
else {
 
// Error while granting credit to the account
 
print $response['returnString'] . "\n";
}

Note: Subscribe does not allow you to grant time-based credit to an Account object.

Revoking Credit from an `Account`

For some customer activities, you might revoke credit from the customer’s account. For example, if a customer uses airline frequent flier miles to book a flight, an airline company would deduct frequent flier miles from the customer’s account. If you accept currency credits, you may also deduct currency from the account. Use Account.revokeCredit to deduct credit from an Account:

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('ff_flier_101');
 
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that you have already created
// a Token object with this id.)
 
$tok->setMerchantTokenId('UA_FF_MILES');
 
$tokAmt = new TokenAmount();
$tokAmt->setToken($tok);
$tokAmt->setAmount(25000);
 
$cr = new Credit();
$cr->setTokenAmounts(array($tokAmt));
 
// make the SOAP API call to deduct miles
$response = $acct->revokeCredit($cr);
 
if ($response[’returnCode’] == 200) {
 
// Credit successfully revoked from the account
 
$updatedAcct = $response->['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";
}
}
else {
 
// Error while revoking credit from the account
print $response['returnString'] . "\n";
}

Note: If the amount of token-based credit to be revoked results in a negative balance, Subscribe sets the balance to 0.

Using Credits for a One-Time Transaction

One-time transactions may use credit available to an Account. To use Credits for one-time transactions, make certain that the Transaction object includes a PaymentMethod that matches the currency or token type you wish to use to conduct the transaction. If the customer Account has enough credit to support the transaction, Subscribe authorizes the transaction, and adds a new transaction item to the Transaction object returned to you in response to your authCapture() call. This transaction item has its sku attribute set to VIN_Credit, and its price set to a negative value (equivalent to the amount of the transaction), signifying that Subscribe deducted the credit from the customer’s account. Note: You can also have Subscribe process a one-time transaction that does not consume available currency credits. In the Transaction object, populate the name-value pair vin:ignoreCredits = true and the Transaction will charge against the payment method, using no currency credits. Create a one-time credit transaction:

$acct = new Account();
 
// account id for an existing customer
 
$acct->setMerchantAccountId('jdoe101');
 
$tok = new Token();
 
// specify the id of an existing token type.
// (the assumption here is that the customer with
// account id 'jdoe101' has credit available in this
// type of token.)
 
$tok->setMerchantTokenId('ANYTIME_PHONE_MINUTES_2010');
 
// source payment method for the transaction should be
// a token-based payment method
$srcPm = new PaymentMethod();
$srcPm->setType('Token');
$srcPm->setToken($tok);
$srcPm->setMerchantPaymentMethodId('5933054820');
 
$txn = new Transaction();
$txn->setAccount($acct);
$txn->setSourcePaymentMethod($srcPm);
 
// This transaction will deduct 50 credit units from the account
$txn->setAmount(50);
 
$txn->merchantTransactionId('TK00234918'); // must be unique
 
// Add a transaction item describing the transaction detail
 
$txItem = new TransactionItem();
$txItem->setSku('MONTH50');
$txItem->setName('Monthly Anytime Minutes');
$txItem->setPrice(50);
$txItem->setQuantity(1);
 
// set the transaction item into the transaction
$txn->setTransactionItems(array($txItem);
 
$sendEmail = false;
 
// Make the SOAP call to authorize and capture the transaction
$response = $txn->authCapture($sendEmail);
 
if ($response[’returnCode’] == 200) {
 
// the SOAP call succeeded. Now check if the
// transaction was authorized
$retTxn = $response->['transaction'];
if($retTxn->statusLog[0]->status=='Authorized') { 
print "Transaction approved"; 
} 
else if($retTxn->statusLog[0]->status=='Cancelled') { 
print "Transaction not approved \n"; 
} 
else { 
print "Error: Unexpected transaction status\n"; 
}
}
else {
// Error while conducting transaction
print $response['returnString'] . "\n";
}

Fetching `Account` Credit History

Subscribe maintains a log of credit-related events for each Account. This log keeps track of various credit-related events such as credit granted, revoked, consumed, or earned from a gift card redemption. Retrieve the audit log by calling the Account object’s fetchCreditHistory() method. The method includes paging and a time range, so you can limit the number of records returned. It returns an array of CreditEventLog objects. Each CreditEventLog object holds the Credit object, a timestamp, the type of activity performed with the Credit object, and a note text field. Call Account.fetchCreditHistory:

$acct = new Account(); 
 
// account id for an existing customer whose
// credit history you want to retrieve
 
$acct->setMerchantAccountId('jdoe101');
 
$page = 0; // paging begins at 0
$pageSize = 5; // five records 
$startTime = '2010-01-01T22:34:32.265Z'; 
$endTime = '2010-01-30T22:34:32.265Z'; 
 
do { 
$ret = 
$acct->fetchCreditHistory($startTime, $endTime $page, $pageSize); 
$count = 0; 
if ($ret[’returnCode’]== 200) { 
$fetchedLogs = $ret['creditEventLogs']; 
$count = sizeof($fetchedLogs); 
foreach ($fetchedLogs as $log) { 
 $credit = $log->getCredit();
$ts = $log->getTimeStamp();
$eventType = $log->getType();
// process retrieved credit event log
// details here.
} 
$page++; 
} 
} while ($count > 0);

Parent topic:Working with Credit

Home

Guides

APIs

Granting Credit to an `Account`

Revoking Credit from an `Account`

Using Credits for a One-Time Transaction

Fetching `Account` Credit History

​Granting Credit to an Account

​Revoking Credit from an Account

​Using Credits for a One-Time Transaction

​Fetching Account Credit History

Granting Credit to an `Account`

Revoking Credit from an `Account`

Using Credits for a One-Time Transaction

Fetching `Account` Credit History