# Collecting Tips

Learn how to include tips when processing payments.

Sellers can easily collect tips with Finix while processing both:

- [Online Payments](#tipping-online-payments)
- [In-Person Payments](#tipping-in-person-payments)


## Tipping Online Payments

There are two ways to collect tips while processing Online Payments. Both methods rely on when and how the tip is requested from the cardholder.

- If the seller wants [to collect the tip while the buyer makes their payment,](#time-of-payment) include the tip in `amount` when creating the `Authorization` or `Transfer`. This is the most common method of collecting tips when processing Online Payments.
- If the seller wants [to collect the tip after providing a service or good,](#after-the-payment) first create an `Authorization` to verify funds are available. Then create a `Transfer` that includes the tip in `amount` along with the cost of the transaction.


### Time of Payment

Here's an example of a `Transfer` that processes a $20 transaction with a $2 tip. The `amount` represents the total amount (cost of the goods or services + tip) that's collected from the cardholder.

To track the tip within Finix, create a tag. Include the part of the `amount` that is a tip in the `tags` field like the example below.

Example
API Definition
### After the Payment

To collect the tip after a service or good is provided, first create an `Authorization` to confirm the `Payment Instrument` has enough funds.

Below is an example of a transaction that is $22 and will be collecting a tip of $8.

The first `Authorization` assumes a general tip of $5.


```shell
curl https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "amount": 2700,
    "currency": "USD",
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137"
  }'
```

After the service or good is provided, if the total `amount` with the tip included is:

|  |  |
|  --- | --- |
| Less than the initial `Authorization` | [Capture the initial `Authorization`](/guides/online-payments/payment-features/auth-and-captures#capturing-an-authorization) for that smaller `amount`. |
| Greater than the initial `Authorization` | [Void the initial `Authorization`](/guides/online-payments/payment-features/auth-and-captures#void-an-authorization), and create a `Transfer` for that greater `amount`. |


If the buyer tips $8, here's the `Transfer` you create after voiding the initial `Authorization`.

Include the tip the buyer provided in `amount` (cost of the goods or services + tip).

To track the tip within Finix, create a tag. Include the part of the `amount` that is a tip in the `tags` field like the example below.

Example
API Definition
## Tipping In-Person Payments

There are two ways to collect tips while processing In-Person Payments:

|  |  |
|  --- | --- |
| [Tipping on the Receipt](#tipping-on-the-receipt) | The tip is collected when the initial `Authorization` is captured. The buyer usually writes the tip on the receipt; this is one of the most widely used options to collect tips. |
| [Tipping on Point of Sale Software](#tipping-on-point-of-sale-software) | The buyer enters the tip on your point-of-sale software or app. The buyer usually enters the tip on a tablet like an iPad or an Android device. |


### Tipping on the Receipt

To collect a tip on a receipt:

|  |  |
|  --- | --- |
| 1. [Create an `Authorization`](#create-an-authorization) | Create an `Authorization` for the transaction `amount`. |
| 2. [Collect the buyer's tip](#collect-the-tip) | At a later point, collect the buyer's tip either digitally or from the receipt. |
| 3. [Capture the `Authorization`](#capture-the-authorization) | Capture the `Authorization` for the transaction `amount` including the tip. |


#### Create an Authorization

The following authorizes a `Payment Instrument` for a restaurant bill of $20. This `amount` doesn't include the buyer's tip.


```shell
curl https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "amount": 2000,
    "currency": "USD",
    "device": "DVf2H8sh4LZZC52GTUrwCPPf",
    "operation_key": "CARD_PRESENT_AUTHORIZATION"
  }'
```

A successful response returns a 200 and the newly created `Authorization` resource.


```json
{
    "id": "AUarp7Pz21Low4u2Urw5Ub4W",
    "created_at": "2019-04-29T20:44:00.13Z",
    "updated_at": "2022-10-10T05:59:17.59Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": null,
    "amount": 2000,
    "amount_requested": 2000,
    "application": "APeUbTUjvYb1CdPXvNcwW1wP",
    "capture_amount": null,
    "card_present_details": {
        "emv_data": {
            "application_identifier": "A0000001523010",
            "application_label": "DISCOVER",
            "application_preferred_name": null,
            "application_transaction_counter": "0005",
            "cryptogram": "ARCQ F666F8891F870D33",
            "issuer_code_table_index": null,
            "pin_verified": false,
            "tags": null
        },
        "masked_account_number": "************0059",
        "name": "Test Card 05",
        "brand": "DISCOVER",
        "entry_mode": "CHIP_ENTRY",
        "payment_type": "CREDIT",
        "approval_code": "004839"
    },
    "currency": "USD",
    "device": "DVfKLD9GZtsjcJxLtc2yCcfd",
    "expires_at": "2019-05-06T20:44:00.13Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR",
    "messages": [],
    "raw": null,
    "security_code_verification": null,
    "source": "PImTHaz7XVPx4M7mhu9x8gkU",
    "state": "SUCCEEDED",
    "tags": {
        "TicketNumber": "45878"
    },
    "trace_id": "FNX35FSuraeKKJr65wkGVFJni",
    "transfer": "TRqQCAX7nYHUnkE5YPFTknqd",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}
```

#### Collect the Tip

Collect the dollar amount of the tip from the *Tip* written on the receipt, or from the tip the buyer entered into your app.

If you are using a `FINIX_V1` / `DUMMY` terminal with printing capabilities, you can enable/disable the tip field on the receipt with the below API call:


```shell
curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '{
    "configuration": {
      "display_tip_on_receipt": true
    }
  }'
```

#### Capture the Authorization

Capture the `Authorization` with the tip included in `capture_amount`. The `capture_amount` should include the total amount of funds you’d like to collect from the cardholder.

In this example, the cardholder tipped $2, so the `capture_amount` for a $20 bill will be $22. We also capture the tip amount in the `tags` to track and record.


```shell
curl https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '{
    "capture_amount": 2200,
    "tags": {
      "tip": "200"
    }
  }'
```

A successful response returns a 200 and the `Authorization` resource.


```json
{
    "id": "AUarp7Pz21Low4u2Urw5Ub4W",
    "created_at": "2022-10-06T20:22:42.25Z",
    "updated_at": "2022-10-07T17:09:22.85Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
    "amount": 2200,
    "amount_requested": 2200,
    "tip": 200,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "expires_at": "2022-10-13T20:22:42.25Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": [],
    "raw": null,
    "security_code_verification": "MATCHED",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "state": "SUCCEEDED",
    "tags": {
        "tip": "200"
    },
    "trace_id": "2724719e-6cc4-4cba-a859-2e6ac0bffb9b",
    "transfer": "TRs6APHuUAvSYq2FfTDkb5d8",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}
```

### Tipping on Point of Sale Software

To collect the tip on your point of sale software or while your buyer is checking out, create a `Transfer` (or `Authorization`) and include `tip` in the request. This is common in establishments where buyers want a quick experience or often refuse the receipt.

Here's an example of an `Authorization` where the `tip` is $0.50 and the cost of goods or services (`amount`) is $1.50. We also capture the tip amount in `tags` to track and record.


```shell
curl https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "amount": 200,
    "currency": "USD",
    "device": "DVf2H8sh4LZZC52GTUrwCPPf",
    "operation_key": "CARD_PRESENT_AUTHORIZATION",
    "tags": {
      "tip": "50"
    }
  }'
```

A successful response returns a 200 and the `Authorization` resource.


```json
{
    "id": "AUarp7Pz21Low4u2Urw5Ub4W",
    "created_at": "2019-04-29T20:44:00.13Z",
    "updated_at": "2022-10-10T05:59:17.59Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": null,
    "amount": 200,
    "amount_requested": 200,
    "application": "APeUbTUjvYb1CdPXvNcwW1wP",
    "capture_amount": null,
    "card_present_details": {
        "emv_data": {
            "application_identifier": "A0000001523010",
            "application_label": "DISCOVER",
            "application_preferred_name": null,
            "application_transaction_counter": "0005",
            "cryptogram": "ARCQ F666F8891F870D33",
            "issuer_code_table_index": null,
            "pin_verified": false,
            "tags": null
        },
        "masked_account_number": "************0059",
        "name": "Test Card 05",
        "brand": "DISCOVER",
        "entry_mode": "CHIP_ENTRY",
        "payment_type": "CREDIT",
        "approval_code": "004839"
    },
    "currency": "USD",
    "device": "DVfKLD9GZtsjcJxLtc2yCcfd",
    "expires_at": "2019-05-06T20:44:00.13Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR",
    "messages": [],
    "raw": null,
    "security_code_verification": null,
    "source": "PImTHaz7XVPx4M7mhu9x8gkU",
    "state": "SUCCEEDED",
    "tags": {
        "tip": 50
    },
    "trace_id": "FNX35FSuraeKKJr65wkGVFJni",
    "transfer": "TRqQCAX7nYHUnkE5YPFTknqd",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}
```

After the response is returned, the device screen (if a screen is available) will display the total and ask the cardholder for the `tip` amount.

If the `Authorization` is captured with a different tip amount, then Finix overwrites the previous tip with the new `amount` provided.

Here's an example where a buyer decides to leave a bigger tip ($.50) after a different amount was initially presented:


```shell
curl https://finix.sandbox-payments-api.com/authorizations/AUcP43nwPk6VBjPQBDRBTH5n \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '{
    "capture_amount": 250,
    "tags": {
        "tip": 100
    }
  }'
```

A successful response returns a 200 and the updated `Authorization` resource:


```json
{
    "id": "AUbrumLihwhdLixtbU1mfMiF",
    "created_at": "2022-10-06T20:22:42.25Z",
    "updated_at": "2022-10-07T17:09:22.85Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
    "amount": 250,
    "amount_requested": 250,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "expires_at": "2022-10-13T20:22:42.25Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": [],
    "raw": null,
    "security_code_verification": "MATCHED",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "state": "SUCCEEDED",
    "tags": {
        "tip": "100"
    },
    "trace_id": "2724719e-6cc4-4cba-a859-2e6ac0bffb9b",
    "transfer": "TRs6APHuUAvSYq2FfTDkb5d8",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}
```