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

PropertyDescription
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

PropertyDescription
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

PropertyDescription
parametersAll 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

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

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()));