Surcharge In-App

Some of the card readers Commerce SDK supports do not have a display or pin pad. 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.

The POS system can send one of the following decisions to Commerce SDK based on the customer’s input:

• Accept - accept 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:

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.

Request

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

Response

{
    "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"],
            "extraChargeLookupOutcome": {
                "allowExtraCharge": true,
                "extraChargeType": "CREDIT_SURCHARGE",
                "extraChargePercent": 3.0,
                "extraChargeAmount": {
                    "currencyCode": "USD",
                    "amount": 60
                },
                "totalAmount": {
                    "currencyCode": "USD",
                    "amount": 2060
                },
                "baseAmount": {
                    "currencyCode": "USD",
                    "amount": 2000
                },
                "extraChargeConfirmationOption": "IN_POS"
            }
        }
    }
}

After getting surcharge decision from the cardholder, integrating POS system can make continuePaymentTransaction request with decision Accept, Change_Card, or Decline. If Decline is set or the field is empty, the transaction will be canceled.

Request

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

Java

// Method transactionRequiresExtraChargeConfirmation is introduced to abstract class ECLTransactionProcessingListener
// CSDK will ask integrating POS system to perform surcharge confirmation through this method.
@Override
public void transactionRequiresExtraChargeConfirmation(ECLTransactionInterface transaction,
                                                       ECLTenderInterface tender,
                                                       ECLExtraChargeLookupOutcome extraChargeLookupOutcome,
                                                       ECLTransactionProcessingCallbackListener transactionProcessingCallbackListener)
{
    // Integrating POS system sends the surcharge decision back through interface transactionProcessingCallbackListener 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 parameter are
    // ECLExtraChargeDecision.ACCEPT : consumer accepts surcharge,
    // ECLExtraChargeDecision.CHANGE_CARD: consumer declines the surcharge and wants to change the card for the ongoing transaction,
    // ECLExtraChargeDecision.DECLINE: consumer declines the surcharge and cancels the ongoing transaction.
    transactionProcessingCallbackListener.setExtraChargeDecision(transaction, tender, extraChargeLookupOutcome, ECLExtraChargeDecision.ACCEPT);
}

Objective-C (iOS)

// Implementation of [ECLTransactionProcessingDelegate shouldProvideExtraChargeDecision:tender:extraChargeLookupOutcome:]
// CSDK will ask integrating POS system to perform surcharge confirmation through this method.
- (void)shouldProvideExtraChargeDecision:(id<ECLCurrencyTransactionProtocol>)transaction tender:(id<ECLTenderProtocol>)tender extraChargeLookupOutcome:(ECLExtraChargeLookupOutcome *)extraChargeLookupOutcome {
    // set decision to ECLExtraChargeDecisionAccept; it can also be set to ECLExtraChargeDecisionChangeCard or ECLExtraChargeDecisionDecline
    transaction.extraChargeDecision = ECLExtraChargeDecisionAccept;
    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)
    {
        Dictionary<string, string> info = new Dictionary<string, string>();
        for (int i = 0; i < req.Length; i++)
        {
            if (String.Compare(req[i], "RequireSurchargeConfirmation", true) == 0)
            {
                info["RequireSurchargeConfirmation"] = "Accept"; // can also set to "Change_Card" or "Decline"
            }
        }
   
        if (info.Count != 0)
        {
            // Continue the transaction
            cws.StartContinuePaymentTransaction(m_PaymentGatewayId, chanId, info, MyNotifyCWSEvent, MyPaymentComplete);
        }
    }
}