Post Auth Tip Adjust

You can update the tip (gratuity) for a credit card transaction after the transaction is authorized. You will need to use the unique transaction identifier returned in the response to the original sale transaction.

You can also indicate if an online authorization should be performed for the tip adjust transaction.

note

  • This transaction is supported in the Service market segment.
  • Tips are updated or added after the transaction has been processed, typically at the end of the day prior to Settlement.
  • Tips can only be adjusted for credit card transactions.

Code Samples

CWS

Request

PropertyDescription
method
string | required
tipAdjust
requestId
string | required
Transaction Request ID
targetType
string | required
paymentGatewayConverge
parameters
JSONObject | required
All relevant parameters for Tip Adjust transactions.
paymentGatewayId
string | required
Payment Gateway ID
Unique identifier of the payment gateway as returned in the openPaymentGateway transaction response.
originalTransId
string | required
Transaction ID
Unique transaction identifier of the sale transaction.
verifyTipAdjustByIssuer
boolean | required
Indicates if an online authorization should be obtained for the tip adjust.
If false, the tip adjust will get authorized when the transaction is settled.
gratuityAmount
JSONObject | required
The amount of the Tip Adjust transaction
“gratuityAmount” : { “currencyCode” : “USD”, “value” : 200 }

Start the transaction:

{
  "method" : "tipAdjust",
  "requestId" : "832364634",
  "targetType" : "paymentGatewayConverge",
  "parameters" : {
    "paymentGatewayId" : "11b0032b-eb0d-4d9a-8664-eb430684cb92",
    "originalTransId" : "040316A15-F48AB876-9635-4933-B773-136888A3D972",
    "verifyTipAdjustByIssuer" : false,
    "gratuityAmount" : {
      "value" : 200,
      "currencyCode" : "USD"
    }
  }
}

Later to query the status of the transaction:

{
  "method" : "getPaymentTransactionStatus",
  "requestId" : "832364635",
  "targetType" : "paymentGatewayConverge",
  "parameters" : {
    "paymentGatewayId" : "11b0032b-eb0d-4d9a-8664-eb430684cb92",
    "chanId" : "42b81c6a-f7eb-481c-bdff-0349cc84f296"
  }
}

Response

Initial response to tipAdjust request:

{
  "requestId" : "832364634",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : false,
      "eventQueue" : [],
      "chanId" : "42b81c6a-f7eb-481c-bdff-0349cc84f296"
    }
  }
}

Complete response:

{
  "statusDetails" : "REQUEST_ACCEPTED",
  "requestId" : "832364635",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : true,
      "chanId" : "42b81c6a-f7eb-481c-bdff-0349cc84f296",
      "eventQueue" : [
        {
          "timeStamp" : "1645758897519",
          "statusDetails" : "TRANSACTION_QUERY_COMPLETE"
        },
        {
          "timeStamp" : "1645758897519",
          "statusDetails" : "STARTING"
        }
      ],
      "paymentTransactionData" : {
        "amountAuthorized" : {
          "value" : 700,
          "currencyCode" : "USD"
        },
        "gratuityAmount" : {
          "value" : 200,
          "currencyCode" : "USD"
        },
        "transactionType" : "TIP_ADJUST",
        "result" : "APPROVED",
        "tenderType" : "CARD",
        "approved" : "yes",
        "id" : "040316A15-F48AB876-9635-4933-B773-136888A3D972",
        "isFallback" : false,
        "errors" : []
      }
    }
  }
}

Java

  1. Initialize Commerce SDK and receive an ECLAccountInterface instance named account.

  2. Create a money object by specifying a currency code and an amount.

    ECLMoney amount = new ECLMoney(ECLCurrencyCode.USD, 200L);
    
  3. Add the unique transaction identifier of the original sale transaction and create a transaction interface. Also specify if an online authorization should be obtained.

    ECLTipAdjustTransactionInterface transaction = account.getTransactionProcessor().createTipAdjustTransaction(originalTxnId, amount, false);
    
  4. Create a card tender interface.

    ECLCardTenderInterfaceECLCardTenderInterface tender = account.getTransactionProcessor().createCardTender();
    

Objective-C

  1. Initialize Commerce SDK and receive an ECLAccountProtocol instance named account.

  2. Create a money object by specifying a currency code and an amount.

    ECLMoney *amount = [[ECLMoney alloc] initWithMinorUnits:200 withCurrencyCode:ECLCurrencyCode_USD];
    
  3. Add the unique transaction identifier of the original sale transaction and create a transaction protocol. Also specify if an online authorization should be obtained.

    id<ECLTipAdjustTransactionProtocol> transaction = [[_account transactionProcessor] createTipAdjustTransactionWithTotal:amount transactionID:originalTxnId verify:NO];
    
  4. Create a card tender protocol.

    id<ECLCardTenderProtocol> tender = [[_account transactionProcessor] createCardTender];
    

C#

Money amount = new Money(Money.CurrencyCodefromString("USD"), myAmount);
bool verifyTipAdjustByIssuer = false;
 
m_CWS.StartTipAdjust(m_PaymentGatewayId, m_OriginalTransId, amount, verifyTipAdjustByIssuer, MyNotifyCWSEvent, MyPaymentComplete);