Skip to main content
Skip to main content

Tipping Overview

Aurora includes gratuity and tipping features. This allows clients to add a tip either as a percentage or a fixed amount. Also, at the time of the purchase, such as for online or retail purchases or separately at the end of the purchase, such as a restaurant, service, or hospitality.

API Endpoints for Tip Management

The following endpoints are used for tipping.

POST /pay-api/v1/transactions/auth
This endpoint authorizes a payment transaction. Adjustments to the base amount are available including for discounts, surcharges, and tips. Tips may be specified as either tipAmount (an absolute amount in USD) or tipRate (a percentage of the base amount).

POST /pay-api/v1/transactions/sale
This endpoint completes a transaction in a single step. This represents a basic transaction. Adjustments to the base amount are available including for discounts, surcharges, and tips. Tips may be specified as either tipAmount (an absolute amount in USD) or tipRate (a percentage of the base amount).

POST /pay-api/v1/transactions/tip-adjustment
This endpoint adjusts the tip amount. The request field tipAmount is the only adjustment possible. It represents the absolute amount in USD.

GET /pay-api/v1/transactions/calculate-amount tipAmount, tipRate
This endpoint calculates the transaction amount to be charged to the customer. The calculated amounts are for information only. Selected values may be displayed to the client.

POST /pay-int-api/payment-sessions
This endpoint creates a payment session object. A payment session is temporary context or container for one transaction. Each step is tracked and protected in this container.

Although it is not required, we encourage using payment sessions. Using a payment session :

  • MProtects payments from duplicating charges.
  • manages complex flows, such as those with tips, surcharges, discounts, and authorization steps.
  • Allows fraud protection.

Enabling Tipping

For tipping to be applied to a billing amount, the tipping option must first be activated. The endpoint GET /pay-api/v1/configurations/payments returns the field isTipsEnabled, showing the status of tipping.

Controlling the activation status is is set in the Merchants portal. The Tips option must be activated. To enable Tips:

  1. Navigate to the Aurora Merchant site at https://arise.risewithaurora.com
  2. Select your merchant account, select Settings tab, General tab,
  3. Toggle the Tips control to be on.
  4. Select the checkbox Enable Tips adjustment to be on.

If both are inactivate or unselected, transactions with tip values will fail with a 400 response. This includes for both one- and two-step transactions.

Tip Calculation and Percentage Options

Aurora supports various methods to define and apply a tip.

The values for the tips are specified in one of two ways: tipAmount and tipRate.

tipAmount : The tipAmount is the absolute amount (in USD) of tip to be added. For example, the client specifies the tip amount of $10.

tipRate : The tipRate is the tip rate, or percentage, of the base amount to be added. For example, the client specifies the tip amount of 15%

Values for tipAmount and tipRate are mutually exclusive. Care must be taken to include one or the other but not both.

One- and Two-step Operations​

Tip related endpoints are defined as either one-step operations or two-step operations.

One-step operations
One-step operations are transactions that authorizes and captures the transaction in a single request. This allows processing a payment in one step or action by both approving the card and immediately completing the transaction. This is a common retail situation when the purchase price is finalized and known at the moment of the sale. All adjustments to the base price such as discounts, surcharges, and tips, are applied at the same time as the transaction. No additional consumer involvement is required.

The endpoint POST /pay-api/v1/transactions/sale is an example of a one-step operation.

Two-step operations
Two-step operations are transactions that authorize and capture the transaction in separate requests. A common situation is at a restaurant, service, or hospitality situation. The initial bill is known and a tip is added later. The first step is that the known portion of the bill is authorized with the funds being held for a short while. The first step is that then tip is added The transaction is settled and that completes the transaction.

The following set of endpoints is an example of a two-step operation.:

  • POST /pay-api/v1/transactions/auth
  • POST /pay-api/v1/transactions/tip-adjustment

The two endpoints must be used together to add a tip.

Tipping Methods

The following are workflow example using different methods that include tipping.

Base Transaction Example​

This example represents the the basic one-step transaction that includes tipping.

Client collection occurs at the time of sale. Situations include retail sales, online sales or a restaurant, services, or hospitality when the amount is known ahead of time and the bill is paid at one time. All adjustments to the base price such as discounts, surcharges, and tips, are applied at the same time as the transaction. No additional consumer involvement is required.

That amount is then approved for the entire transaction. This type of transaction cannot be modified after submission.

The following is the request body for POST {{ApiUrl}}/pay-api/v1/transactions/sale:

{
  "amount": 400,
  "accountNumber": "4000007640000003",
  "cardDataSource": 1,
  "currencyId": 1,
  "expirationMonth": 12,
  "expirationYear": 2032,
  "tipAmount": 20
}

The amount charged in returned in the response body field amount.totalAmount.