Gratuity

Elements of the flow will vary based on the POS environment or requirements and on the connected terminal.

If the PIN entry device (PED) or card reader (example: Ingenico iCMP, iSC250) supports amount entry:

The PED displays gratuity prompts.
The final amount will be returned to the integrator.

If the PED or card reader (example: ROAM RP457c) does not support amount entry:

The integrator can specify the gratuityAmount value (already pre-determined) when starting the transaction.
Commerce SDK can request the value via callback, as needed.

Code Samples

CWS

Request

Property	Description
parameters JSONObject \| required	All relevant parameters for Gratuity processing.
gratuityFlowEnabled boolean \| required	Gratuity Support and Flow Indicator Indicates whether gratuity support and flow is part of the transaction. Valid values: - true - false (Default)
gratuityAmount JSONObject \| optional	Gratuity Amount Gratuity amount that has already entered into the POS prior to the start of the transaction or used as part of callback request. key: “currencyCode” (“USD”) key: “value” (“2000” - in minor units)
gratuityQuickSelections JSONObject \| optional	Gratuity Quick Selections Enables the overriding of the quick selection option on the PED or callback. key: “curencyCode” (“USD”) key: “value” (“125” - in minor units) key: “type” (“MONETARY_AMOUNT” or “PERCENTAGE”)
gratuityCustomAmountEntryallowed boolean \| required	Allow Custom Gratuity Amount Indicator Indicates whether the user can enter a custom gratuity amount. Valid values: - true - false (Default)

Response

Property	Description
data JSONObject	Object holding various responses.
gratuityAmount JSONObject	Gratuity Amount Gratuity amount selected as part of gratuity flow or callback. This amount is typically returned at the time of the authorization request. key: “currencyCode” (“USD”) key: “value” (“2000” - in minor units)

Example

Request

{
  "method" : "startPaymentTransaction",
  "requestId" : "1016061883",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "paymentGatewayId" : "6da0af71-2e4b-4609-ad18-6a06dbf070fb",
    "transactionType" : "SALE",
    "tenderType" : "CARD",
  .....
    "gratuityFlowEnabled" : true,
    "gratuityAmount" : null,
    "gratuityCustomAmountEntryAllowed" : true,
    "gratuityQuickSelections" : {
      "selection1" : {
        "type" : "PERCENTAGE",
        "currencyCode" : "USD",
        "value" : "15"
      },
      "selection2" : {
        "type" : "PERCENTAGE",
        "currencyCode" : "USD",
        "value" : "20"
      },
      "selection3" : {
        "type" : "MONETARY_AMOUNT",
        "currencyCode" : "USD",
        "value" : "300"
      }
    },
  .....
  }
}

Response

"requestId" : "1016061925",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : true,
      "eventQueue" : [ ],
      "chanId" : "d220e0fc-dbe5-42d8-abd8-e476aa2a1c64",
      "paymentTransactionData" : {
        "result" : "APPROVED",
        "authCode" : "******",
        "date" : "Mon Mar 07 12:09:45 MST 2016",
        "cardEntryType" : "SWIPE",
        "resultMessage" : "APPROVED",
        "cardScheme" : "VISA",
        "amount" : {
          "currencyCode" : "USD",
          "value" : 1300
        },
        "id" : "070316A15-96503D56-5BF3-4944-8A5C-D7A819A44A05",
        "transactionType" : "SALE",
        "approved" : "yes",
        "errors" : [ ],
        "maskedPan" : "******",
        "gratuityAmount" : { 
          "currencyCode" : "USD",
          "value" : 300 
        },
        "signatureBitmap" : {
          "data" : "` *M    _/_ X _/ _& _& _/___ _/ _& _%___ _% _&__^ _&__^ _'___ _'___ _&__^ _&___ _&p`#*K_ P_ Y  !_ X  \"  !  (  !  (  )  (  )  (  1  8  )  8  8  8  8 _/  ( _' _' _/ _'___ _'__^___ _&__W__^__^_____^__W__^____________ _&_ X _/___ _/ _/  ( _/  (  (  (  (  ( _/  (  (  (  (  ( _' _'_ X____ X____ P____ X__W____ P__W____ P____ X__W____ X_ X _'_ Xp`(%\"  !p`,(. _'____ X___ _'_______ X _'___ _'_____^ _'___ _' _&_ X _/ _' _/ _/ _/  0  (  0  0  1  (  1  0  1  1  1  1  )  )  1  \"  1  !  \"  !  !  !  \"_ Y_ Y_ Y_ Y_ Y_ Q_ Y_ P_ P_ Y_ P_ P_ P____ P____ P____ Xp`2).____ X____ X_ X____ X_ X__W____ X_____W__W_____W_____^_________ _'___ _' _'  ( _' _/  ( _7  )  0  0  )  0  9  1  1  )  1  1  1  )  2  )  *  !  *  \"  )  !  \"_ Y  !_ Y_ Z_ Y_ Q_ Q_ X_ I_ P_ P_ P_ Hp",
          "format" : "SIG_BIN_2"
        },
        "tenderType" : "CARD",
        "balanceDue" : {
          "currencyCode" : "UNKNOWN",
          "value" : 0
        }
      }
    }
  }
}

Java

ECLCurrencyTransactionInterface

Property	Description
parameters	All relevant parameters for Gratuity processing.
setGratuityRequested boolean \| required	Set Gratuity Requested Enables the collection and tracking of a gratuity amount for the given transaction. Valid values: - true - false (Default)
setGratuityCustomAmountEntryAllowed boolean \| optional	Set Gratuity Custom Amount Entry Allowed Allows the cutomer to enter a custom gratuity amount on the card reader, overriding the default quick value options. Valid values: - true - false (Default)
setGratuityQuickValues long \| optional List<ECLGratuityQuickValue>	Set Gratuity Quick Values Overrides the default quick value options displayed for gratuity amount selection.

Enable Gratuity

Using the same from the Sale transaction with a card tender, the only addition we need to do before processing the transaction is:

((ECLCurrencyTransactionInterface) transaction).setGratuityRequested(true);

Quick Gratuity Selection

By default, there are 3 quick gratuity selections: 15%, 18%, and 20%. Optionally, you can specify up to 3 custom gratuity quick selection values. It can be either percentage or amount. Let’s define a quick gratuity selections of 10%, $2.00, and $5.00

List<ECLGratuityQuickValue> quickValues = new ArrayList<ECLGratuityQuickValue>();
BigDecimal percentage = new BigDecimal(10);
quickValues.add(new ECLGratuityQuickValue(percentage));
ECLMoney quickAmount1 = new ECLMoney(ECLCurrencyCode.USD, Long.valueOf(200));
quickValues.add(new ECLGratuityQuickValue(quickAmount1));
ECLMoney quickAmount2 = new ECLMoney(ECLCurrencyCode.USD, Long.valueOf(500));
quickValues.add(new ECLGratuityQuickValue(quickAmount2));
((ECLCurrencyTransactionInterface) transaction).setGratuityQuickValues(quickValues);

Enter Gratuity Amount Manually

Optionally, by setting the “custom amount entry” flag on, you can manually enter any gratuity amount on the device.

((ECLCurrencyTransactionInterface) transaction).setGratuityCustomAmountEntryAllowed(true);

Objective-C

Enable Gratuity

Using the same code from the Sale transaction with a card tender, the only addition we need to do before processing the transaction is:

[saleTransaction setIsGratuityRequested:YES];

Quick Gratuity Selections

NSMutableArray * tipQuickSelections = [[NSMutableArray alloc] init];
int idx = 0;
ECLGratuityQuickValue *gratuity;
gratuity = [[ECLGratuityQuickValue alloc] initWithPercentage:10];
[tipQuickSelections insertObject:gratuity atIndex:idx++];
gratuity = [[ECLGratuityQuickValue alloc] initWithAmount:[[ECLMoney alloc] initWithMinorUnits:200 withCurrencyCode:_currency]];
[tipQuickSelections insertObject:gratuity atIndex:idx++];
gratuity = [[ECLGratuityQuickValue alloc] initWithAmount:[[ECLMoney alloc] initWithMinorUnits:500 withCurrencyCode:_currency]];
[tipQuickSelections insertObject:gratuity atIndex:idx++];
[saleTransaction setGratuityQuickValues:tipQuickSelections];

Enter Gratuity Amount manually

Optionally, by setting the “custom amount entry” flag on, you can manually enter any gratuity amount on the device.

[saleTransaction setIsCustomAmountEntryAllowed:YES];

Expected Results

The gratuity will be added to the base amount of the transaction and the final amount will be send for authorization.

C#

Gratuity with Percentage

Request

PaymentArgs bea = new PaymentArgs();
...
bea.gratuityFlowEnabled = true;
bea.gratuityCustomAmountEntryAllowed = true;  /* Or false */
 
QuickSelection qa = new QuickSelection();
qs.selection1 = new Dictionary<String, String>();
qs.selection1.Add("type", "PERCENTAGE");
qs.selection1.Add("currencyCode", "USD");
qs.selection1.Add("value", "15");
qs.selection2 = new Dictionary<String, String>();
qs.selection2.Add("type", "MONETARY_AMOUNT");
qs.selection2.Add("currencyCode", "USD");
qs.selection2.Add("value", "300");
 
...
 
bea.gratuityQuickSelections = qs;  /* or null */
 
m_CWS.StartPaymentTransaction(bea, MyNotifyCWSEvent, MyPaymentComplete);

Response

public void MyBackEndComplete(BackEndResults ber)
{
    BackEndTransactionData betd = ber.BackEndTransactionData;
    if (null != betd)
    {
        if ((null != betd.approved)
         && (betd.approved.Equals("yes")))
        {
            Money tip = betd.gratuityAmount;
            if (null != tip)
                Log(String.Format("tip {0}", tip.getAmountInMinorUnits()));