Skip to main content
Skip to main content

Tipping

Tipping Overview​

Aurora includes tipping features. This allows clients to add a tip either as a percentage or a fixed amount. They may be added 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.

Inline Tips And Tip Adjustments​

Tips may be added in one of two ways: Inline tips and tip adjustments

Inline Tips​

Inline tips are tips collected as part of the payment transaction itself.

For example, using an online payment or retail purchase. Here, the base amount and all other charges are known ahead of time. The full amount is paid and captured at one time. Inline tips are common because of their simplicity.

Inline Tip Code Example
This endpoint completes a transaction in a single step:
POST /pay-api/v1/transactions/sale

Several request fields create the amount paid.

  • amount. This is the base amount. It may be the single field used, combining all the other adjustments into one value. Care must be taken to not also include tipAmount/tipRate values.
  • tipAmount/tipRate. These specify the tip amount, either an absolute dollar amount or as a percentage of the base amount. If either value is included, it is added to the base amount. Care must be taken to not also have included tips in the base amount.

POST /pay-api/v1/transactions/sale
The following is the request payload. It is for a base amount of $100 with a 18.5% tip. The transaction will settle for $118.50.

{
    "amount": 100,
    "tipRate": 18.5,
    "paymentMethodId": "b9cceba7-1cbe-4685-85ae-47b05d86850b",
    "cardDataSource": "Internet",
    "currencyId": 1
}

Tip Adjustments​

Tip adjustments are tips added after the payment transaction. They apply only to credit-card present transactions.

For example, paying the bill at sit-down restaurants. The customer pays the base amount and the transaction is authorized. They are left with the paper receipt that they write the tip amount on. Because of this extra step, the restaurant must later explicitly add the tip to that customer's bill. That is the tip adjustment. This is typically done at the end of the business day and all tip adjustments are made at that time. Finally, the transactions are settled.

Tip adjustments have become less common because of the inconvenience of settling at the end of business and an associated risk. If the bill is settled without adding the tip, the tip is lost. It cannot later be added to the customer's bill.

Tip Adjustment Code Example
The following is a typical tip-adjustment workflow with endpoints.

1) POST /pos-api/v1/pos-transactions
with a transactionTypeId of 1 or Sale. This step authorizes and reserves a fundamental amount on the credit card. This may not be the complete amount because all the expenses might not be known yet. For example, customers of a sit-down restaurant pay for meals are given a paper receipt and write the tip at the bottom.

2) POST /pay-api/v1/transactions/tip-adjustment
This step adds the tip that was written on the paper receipt. This is typically done at the end of the business day and all tip adjustments are made at that time.

3) Settle the Transactions
Settling commits the transaction for payment. All the captured transactions are sent out the payer processor to distribute the funds. At the time of this action, all available, unsettled transactions will be batched. This forms a group of transactions that will be settled at the same time. Settling may occur in one of two ways: Automatic or explicit.

Automatic. The platform performs automatic settlement daily, as an overnight task. Many merchants use this automatic action instead of explicitly running the settling endpoint. Care must still be taken to adjust all bills for tips before settlement occurs.

Explicit. The settle endpoint may be run. This gives the merchant finer control on the settlement time. Use the following endpoint to settle accounts:
POST /pay-api/v1/transactions/settle

Enabling Tipping​

For tipping to be applied to a billing amount, the tipping option must first be activated. Transactions including tips but without this option activated returns an error.

To check the status of that option, use GET /pay-api/v1/configurations/payments. This returns the field isTipsEnabled, displaying the status of tipping being enabled.

If this option needs to be activated:

  1. Log into the Aurora Portal
  2. Navigate to Settings
  3. Select Transactions
  4. Select the General tab
  5. Enable Tips. This enables any the fields tipAmount or 'tipRate' to be used. If tips are not enabled, calls with tipAmount or 'tipRate' value will fail.
  6. Enable Tips Adjustment may be selected.
  • If selected, point of service, credit-card present transactions may have the bill adjusted for tips after the service is provided.
  • If not selected, tips adjustment cannot occur. Any tips adjustment returns an error.

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.

Tipping Methods​

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

Sale Transaction Example​

This example represents 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: It is for a base amount of $100 with a 18.5% tip. The transaction will settle for $118.50.

{
    "amount": 100,
    "tipRate": 18.5,
    "paymentMethodId": "b9cceba7-1cbe-4685-85ae-47b05d86850b",
    "cardDataSource": "Internet",
    "currencyId": 1
}

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

API Tipping Endpoints​

The following endpoints are used for tipping.

POST /pay-api/v1/transactions/auth
This endpoint authorizes a payment transaction.

POST /pay-api/v1/transactions/sale
This endpoint completes a transaction in a single step.

POST /pay-api/v1/transactions/tip-adjustment
This endpoint adjusts the tip amount.

GET /pay-api/v1/transactions/calculate-amount
This endpoint calculates the transaction amount to be charged to the customer.

POST /pay-int-api/payment-sessions
This endpoint creates a payment session object.