Surcharge In-App

Some of the card readers Commerce SDK supports do not have either display or pin pad, or both. To support surcharge when connected to those devices, Commerce SDK will send surcharge confirmation to Integrator's POS system through API callbacks instead of sending surcharge confirmation to card reader. This feature is called Surcharge In-App and is introduced into CSDK 4.4.0 release.

The POS system case send one of the following decisions based on the customer's input:

  • Accept - accepts the surcharge and send the transaction for authorization
  • Change Card - start a new transaction on the card reader so the customer can use a different card
  • Decline - decline the surcharge and cancel the transaction

The following card readers require Surcharge In-App:

  • Moby 5500
  • Roam RP457c

The following documents the API changes for different platforms:

CWS

Request to CWS

{
    "requestId":"-23817757",
    "targetType":"paymentGatewayConverge",
    "method":"getPaymentTransactionStatus",
    "parameters":{
        "chanId": "4357f858-59e4-46e6-96f0-a2e724bbba0c",
        "paymentGatewayId": "b9d5db2a-cd04-4dfa-adf3-dbdc6ce21123"
    }
}

Response from CWS

{
   "requestId":"-23817757",
   "statusDetails":"REQUEST_ACCEPTED",
   "data":{
      "paymentGatewayCommand":{
         "completed":false,
         "eventQueue":[
            {
               "timeStamp":"1597261733460",
               "statusDetails":"BIN_LOOKUP_COMPLETED"
            },
            {
               "timeStamp":"1597261733460",
               "statusDetails":"SURCHARGE_CONFIRMATION_STARTED"
            }
         ],
         "chanId":"4357f858-59e4-46e6-96f0-a2e724bbba0c",
         "requiredInformation":[
            "RequireSurchargeConfirmation"
         ],
         "binLookupOutcome":{
            "allowCreditSurcharge":true,
            "creditSurchargePercent":3.0,
            "creditSurchargeAmount":{
               "currencyCode":"USD",
               "amount":60
            },
            "totalAmount":{
               "currencyCode":"USD",
               "amount":2060
            },
            "baseAmount":{
               "currencyCode":"USD",
               "amount":2000
            },
            "surchargeConfirmationOption":"IN_POS"
         }
      }
   }
}

Request to CWS

{
   "requestId":"-23817756",
   "targetType":"paymentGatewayConverge",
   "method":"continuePaymentTransaction",
   "parameters":{
      "RequireSurchargeConfirmation":"Accept",
      "chanId":"4357f858-59e4-46e6-96f0-a2e724bbba0c",
      "paymentGatewayId":"b9d5db2a-cd04-4dfa-adf3-dbdc6ce21123"
   }
}

Java

// A new method transactionRequiresSurchargeConfirmation is introduced to abstract class ECLTransactionProcessingListener

// CSDK will ask integrating POS system to perform surcharge confirmation through this method.

@Override

public void transactionRequiresSurchargeConfirmation(ECLTransactionInterface eclTransactionInterface,

ECLTenderInterface eclTenderInterface,

ECLBinLookupOutcome eclBinLookupOutcome,

ECLSurchargeDecisionListener surchargeDecisionListener)

// Integrating POS system send the surcharge decision back through interface surchargeDecisionListener from the above method.

// The first three parameters are the same ones from the above method,

// and the last one is the decision. Allowed values for the last parameters are

// ECLSurchargeDecision.ACCEPT : consumer accepts surcharge,

// ECLSurchargeDecision.CHANGE_CARD: consumer declines the surcharge and wants to change a card for the ongoing transaction,

// ECLSurchargeDecision.DECLINE: consumer declines the surcharge and cancels the ongoing transaction.

surchargeDecisionListener.setSurchargeDecision(currentTransaction, currentTender, binLookupOutcome, ECLSurchargeDecision.ACCEPT);

Objective-C

// Implementation of [ECLTransactionProcessingDelegate shouldProvideSurchargeDecision:tender:binLookupOutcome:]
// This will get called when surcharge decision must be made by the consumer

+ (void)shouldProvideSurchargeDecision:(id<ECLCurrencyTransactionProtocol>)transaction tender:(id<ECLTenderProtocol>)tender binLookupOutcome:(ECLBinLookupOutcome *)binLookupOutcome {

// set decision to ECLSurchargeDecisionAccept; it can also be set to ECLSurchargeDecisionChangeCard or ECLSurchargeDecisionDecline

((id<ECLCurrencyTransactionProtocol>)transaction).surchargeDecision = ECLSurchargeDecisionAccept;

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

//Suppose we have a payment result object

PaymentTransactionResults paymentResults;

//From payment result we check if surcharge confirmation is needed.

String[] req = paymentResults.GetRequiredInformation();

if (String.Compare(req[i], "RequireSurchargeConfirmation", true) == 0)

{

}

//Later consumer decides to accept surcharge:

Dictionary<string, string> info = new Dictionary<string, string>();

info["RequireSurchargeConfirmation"] = "Accept"; //allowed values are "Accept", "Change_Card" and "Decline"

m_CWS.StartContinuePaymentTransaction(m_PaymentGatewayId, chanId, info, MyNotifyCWSEvent, MyPaymentComplete);