Collecting Tips
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Learn how to include tips when processing payments.

Sellers can easily collect tips with Finix while processing both:

Online Payments
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, 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, 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.

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 5000,
    "currency": "CAD",
    "merchant": "string",
    "source": "PIxxxxxxxxxxxxxxxxxx",
    "idempotency_id": "string",
    "tags": {
      "property1": "string",
      "property2": "string"
    }
  }'

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.

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` for that smaller `amount`.
Greater than the initial `Authorization`	Void the initial `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.

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 5000,
    "currency": "CAD",
    "merchant": "string",
    "source": "PIxxxxxxxxxxxxxxxxxx",
    "idempotency_id": "string",
    "tags": {
      "property1": "string",
      "property2": "string"
    }
  }'

Tipping In-Person Payments

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


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	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` for the transaction `amount`.
2. Collect the buyer's tip	At a later point, collect the buyer's tip either digitally or from the receipt.
3. 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.

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.

{
    "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:

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.

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.

{
    "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"
        }
    }
}