Token Transaction for Surcharge
Card readers are not used for token transactions. To comply with PCI rules, Commerce SDK will notify the Integrator’s POS system through API callbacks for surcharge confirmation.
The POS system can send one of the following decisions to Commerce SDK:
- Accept - accept the surcharge and send the transaction for authorization
- Decline - decline the surcharge and cancel the transaction
The following documents the API changes for different platforms:
Code Samples
CWS
When surcharge confirmation is needed from the POS application, CWS sets property requiredInformation to “RequireSurchargeConfirmation” in the response to getPaymentTransactionStatus. CWS also sets property extraChargeLookupOutcome with the surcharge details.
Response
{
"requestId": "2101936246",
"statusDetails": "REQUEST_ACCEPTED",
"data": {
"paymentGatewayCommand": {
"completed": false,
"eventQueue": [],
"chanId": "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9",
"requiredInformation": ["RequireSurchargeConfirmation"],
"extraChargeLookupOutcome": {
"allowExtraCharge": true,
"extraChargeType": "CREDIT_SURCHARGE",
"extraChargePercent": 3.0,
"extraChargeAmount": {
"currencyCode": "USD",
"amount": 30
},
"totalAmount": {
"currencyCode": "USD",
"amount": 1030
},
"baseAmount": {
"currencyCode": "USD",
"amount": 1000
}
}
}
}
}
Request
After getting surcharge decision from consumer, integrating POS system can make continuePaymentTransaction request with decision Accept or Decline. If Decline is set or the field is empty, the transaction will be canceled.
{
"method" : "continuePaymentTransaction",
"requestId" : "2101936247",
"targetType" : "paymentGatewayConverge",
"version" : "1.0",
"parameters" : {
"RequireSurchargeConfirmation" : "Accept",
"paymentGatewayId" : "4c45c792-0513-4218-8b6d-c5ff7039a22e",
"chanId" : "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9"
}
}
Java
// Suppose there is an instance of interface ECLTransactionProcessingListener
ECLTransactionProcessingListener theListener = new ECLTransactionProcessingListener() { /* implementation of the inteface *? };
// And start a transaction with the listener passed in.
...
// later on CSDK needs the service fee decision and calls requireExtraChargeDecision on theListener
public void requireExtraChargeDecision(ECLTransactionInterface transaction,
ECLTenderInterface tender,
ECLExtraChargeLookupOutcome extraChargeLookupOutcome,
ECLTransactionProcessingCallbackListener transactionProcessingCallbackListener)
{
// POS application should prompt consumer for surcharge confirmation with a UI element
// object extraChargeLookupOutcome contains attributes for total amount, surcharge amount and surcharge percentage
// One example of the message to be displayed can be the following:
// --------------------------------------------------------------------------------
// Total Amount: formatted_version_of extraChargeLookupOutcome.getTotalAmount()
// You will be assessed a extraChargeLookupOutcome.getExtraChargePercent()
// surcharge amount of formatted_version_of extraChargeLookupOutcome.getExtraChargeAmount()
// for using a credit card.
// ---------------------------------------------------------------------------------
//
// The UI element should allow consumer to either accept or decline the surcharge
// Assume boolean variable "accepted" records the decision from consumer
ECLExtraChargeDecision extraChargeDecision = accepted ? ECLExtraChargeDecision.ACCEPT : ECLExtraChargeDecision.DECLINE;
transactionProcessingCallbackListener.setExtraChargeDecision(transaction, tender, extraChargeLookupOutcome, extraChargeDecision)
}
Objective-C (iOS)
// Implementation of [ECLTransactionProcessingDelegate shouldProvideExtraChargeDecision:tender:extraChargeLookupOutcome:]
// This will get called when surcharge decision must be made by the consumer
- (void)shouldProvideExtraChargeDecision:(id<ECLCurrencyTransactionProtocol>)transaction tender:(id<ECLTenderProtocol>)tender extraChargeLookupOutcome:(ECLExtraChargeLookupOutcome *)extraChargeLookupOutcome {
// POS application should prompt consumer for surcharge confirmation with a UI element
// object extraChargeLookupOutcome contains attributes for total amount, surcharge amount and surcharge percentage
// One example of the message to be displayed can be the following:
// --------------------------------------------------------------------------------
// [NSString stringWithFormat:@"Total Amount: %@ \n\nYou will be assessed a %.02f%% surcharge amount of %@ for using a credit card. Accept?",
// [MainViewController formatWithCurrencySymbol:extraChargeLookupOutcome.totalAmount], extraChargeLookupOutcome.extraChargePercent,
// [MainViewController formatWithCurrencySymbol:extraChargeLookupOutcome.extraChargeAmount]];
// ---------------------------------------------------------------------------------
//
// The UI element should allow consumer to either accept or decline the surcharge
// Assume BOOL variable "accepted" records the decision from consumer
transaction.extraChargeDecision = accepted ? ECLExtraChargeDecisionAccept : ECLExtraChargeDecisionDecline;
dispatch_async(dispatch_get_main_queue(), ^() {
// use dispatch_async and call continueProcessingTransaction using your account reference (see sample app for more details)
[[_account transactionProcessor] continueProcessingTransaction:transaction using:tender delegate:self];
});
}
C#
// Assume a CWS object cws is created and we have a delegate MyPaymentComplete to receive transaction update.
cws.StartPaymentTransaction(bea, MyNotifyCWSEvent, MyPaymentComplete);
// The following code demonstrates how to handle surcharge confirmation
public void MyPaymentComplete(PaymentTransactionResults paymentResults)
{
// get required information
String[] req = paymentResults.GetRequiredInformation();
if (null != req)
{
for (int i = 0; i < req.Length; i++)
{
// if required information string is 'RequireSurchargeConfirmation'
// surcharge confirmation should be prompted
Dictionary<string, string> info = new Dictionary<string, string>();
info["RequireSurchargeConfirmation"] = "Decline";
if (String.Compare(req[i], "RequireSurchargeConfirmation", true ) == 0)
{
var extraChargeLookupOutcome = paymentResults.GetExtraChargeLookupOutcome();
if (extraChargeLookupOutcome != null && extraChargeLookupOutcome.allowExtraCharge)
{
// Display surcharge confirmation
// This is only an example for displaying surcharge confirmation message
string caption = "Surcharge Confirmation";
double totalAmount = ((double)extraChargeLookupOutcome.totalAmount.getAmountInMinorUnits()) / 100;
double surchargeAmount = ((double)extraChargeLookupOutcome.extraChargeAmount.getAmountInMinorUnits()) / 100;
string message = "Total Amount: $" + totalAmount + "\n\n"
+ "You will be assessed a " + extraChargeLookupOutcome.extraChargePercent
+ "% surcharge"
+ "for using a credit card";
MessageBoxButton buttons = MessageBoxButton.OKCancel;
MessageBoxResult result = MessageBox.Show(message, caption, buttons);
//update attribute 'RequireSurchargeConfirmation' with either Accept or Decline (case insensitive)
info["RequireSurchargeConfirmation"] = result == MessageBoxResult.OK ? "Accept" : "Decline";
}
// Continue the transaction
cws.StartContinuePaymentTransaction(m_PaymentGatewayId, chanId, info, MyNotifyCWSEvent, MyPaymentComplete);
}
}
}
}