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