Collecting Tips

Learn how to include tips when processing payments.

Sellers can easily collect tips with Finix while processing both:

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.

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.

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

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.

Copy
Copied
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.

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

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.

Copy
Copied
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.

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

Copy
Copied
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.

Copy
Copied
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.

Copy
Copied
{
  "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.

Copy
Copied
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.

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

Copy
Copied
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:

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