Service Fee Property Retrieval

A Converge terminal has the following properties related to service fee:

  1. serviceFeeAllowed - Whether or not this terminal has service fee enabled.
  2. serviceFeeType - Type of service fee enabled for the terminal (percentage or fixed amount).
  3. serviceFeePercent - The service fee percent if the service fee type is percentage.
  4. serviceFeeAmount - The service fee amount if the service fee type is fixed amount.
  5. serviceFeeRefundable - Whether or not the service fee will be refunded if the original transaction is refunded. CSDK gets the properties as part of account information retrieval from Converge during initialization. The following code examples demonstrate how a POS system can obtain the service fee properties from CSDK.

The following documents the API changes for different platforms:

Code Samples

CWS

OpenPaymentGateway response. The following is a sample response when the service fee type is percentage.

Note that if the service fee type was fixed amount, you would have the following differences in the response:

  1. “serviceFeeType” would be “FIXED_AMOUNT”
  2. Instead of “serviceFeePercent”, you would have “serviceFeeAmount” (e.g. “serviceFeeAmount” : 300 [for $3.00 fixed amount])

Response (Percentage Based)

{
    "requestId":"836703218",
    "statusDetails":"REQUEST_ACCEPTED",
    "data": {
        "paymentGatewayCommand": {
            "completed":true,
            "eventQueue":[],
            "openPaymentGatewayData": {
                "result":"SUCCESS",
                "paymentGatewayId":"fe2aef5a-7b06-4122-95b9-1d9d95c9424d"
            },
            "accountInfo" : {
                "businessEmail" : "a@b.com",
                "city" : "Atlanta",
                "address1" : "1234 Hello Lane",
                "postalCode" : "30304",
                "isCvvEnabled" : true,
                "stateProvince" : "GA",
                "isServiceFeeAllowed" : true,
                "serviceFeeType" : "PERCENTAGE",
                "serviceFeePercent" : 3.0,
                "serviceFeeAllowRefund" : false,
                "isAvsEnabled" : true,
                "isGratuitySupported" : false,
                "name" : "John Doe",
                "isPinlessDebitEnabled" : false,
                "currencyCode" : "USD",
                "marketSegment" : "RETAIL"
            }
        }
    }
}

Java

// In the following callback interface method ECLAccountInformationRetrievalListener.accountInformationRetrievalDidSucceed(...) implementation
// First get terminal configuration (ECLTerminalConfiguration) from account interface (ECLAccountInterface).
// Then retrieve service fee preference (ECLServiceFeePreference) from the terminal configuration.
@Override
public void accountInformationRetrievalDidSucceed(ECLAccountInterface eclAccountInterface,
    ECLAccountInformation accountInformation)
{
    ECLTerminalConfiguration terminalConfig = eclAccountInterface.getTerminalConfiguration();
    if (terminalConfig != null)
    {
        ECLServiceFeePreference serviceFeePreference = terminalConfig.getServiceFeePreference();
        if (serviceFeePreference != null)
        {
            displayMessageInProgressView("ServiceFee Allowed: " + serviceFeePreference.isAllowServiceFee(), false);
            if (serviceFeePreference.isAllowServiceFee())
            {
                ECLServiceFeeType serviceFeeType = serviceFeePreference.getServiceFeeType();
                switch (serviceFeeType)
                {
                    case PERCENTAGE:
                        displayMessageInProgressView("ServiceFee Percentage: " + serviceFeePreference.getServiceFeePercent().doubleValue(), false);
                        break;
                    case FIXED_AMOUNT:
                        displayMessageInProgressView("ServiceFee (Flat) Amount: " + serviceFeePreference.getServiceFeeAmount().getAmount(), false);
                        break;
                }
                displayMessageInProgressView("ServiceFee Refundable: " + serviceFeePreference.isAllowRefund(), false);
            }
        }
    }
}

Objective-C (iOS)

// In the [ECLAccountInformationRetrievalDelegate accountInformationRetrievalDidSucceed:accountInformation:] method implementation
// Retrieve service fee preference (ECLServiceFeePreference) from the ECLAccountInformation.
- (void)accountInformationRetrievalDidSucceed:(id<ECLAccountProtocol>)account accountInformation:(ECLAccountInformation *)accountInformation {
    ECLServiceFeePreference *serviceFeePreference = accountInformation.serviceFeePreference;
    BOOL serviceFeeAllowed = [serviceFeePreference serviceFeeAllowed];
    [self addStatusString:[NSString stringWithFormat:@"Service Fee: %@\n", serviceFeeAllowed ? @"YES" : @"NO"]];
    if (serviceFeeAllowed) {
        NSString *serviceFeeString;
        switch (serviceFeePreference.serviceFeeType) {
            case ECLServiceFeeTypeFixedAmount:
                serviceFeeString = [NSString stringWithFormat:@"Service Fee Amount: %@\n", [MainViewController formatWithCurrencySymbol:serviceFeePreference.serviceFeeFixedAmount]];
                break;
            case ECLServiceFeeTypePercentage:
                serviceFeeString = [NSString stringWithFormat:@"Service Fee Percent: %.02f%%\n", [[serviceFeePreference serviceFeePercent] doubleValue]];
                break;
            case ECLServiceFeeTypeUnset:
                serviceFeeString = @"Service Fee: Invalid Type";
                break;
        }
        [self addStatusString:serviceFeeString];
        [self addStatusString:[NSString stringWithFormat:@"Service Fee Refundable: %@\n", serviceFeePreference.serviceFeeRefundAllowed ? @"YES" : @"NO"]];
    }
}

C#

// Property AccountInfo of Object OpenPaymentGatewayResults holds properties related to service fee
private void updateAccountInformation(AccountInfo acctInfo)
{
    Log(String.Format("Service Fee Allowed:  {0}", acctInfo.isServiceFeeAllowed));
    if (acctInfo.isServiceFeeAllowed)
    {
        Log(String.Format("Service Fee Type:  {0}", acctInfo.serviceFeeType));
        switch (acctInfo.serviceFeeType)
        {
            case ServiceFeeType.FIXED_AMOUNT:
                Log(String.Format("Service Fee Amount:  {0}", acctInfo.serviceFeeAmount));
                break;
            case ServiceFeeType.PERCENTAGE:
                Log(String.Format("Service Fee Percent:  {0}", acctInfo.serviceFeePercent));
                break;
        }
        Log(String.Format("Service Fee Refund Allowed:  {0}", acctInfo.serviceFeeAllowRefund));
    }
}