tip records how much of a transaction is gratuity. Card networks want that split reported separately, and some industry categories price differently because of it, so it is worth sending rather than folding silently into the total.
amount is the whole charge. tip says how much of it is a tip.
The two are not added together. A 100.00 meal with a 20.00 tip is:
{
"amount": 12000,
"tip": 2000
}The cardholder is charged 120.00. Sending "amount": 10000, "tip": 2000 charges them 100.00 and reports 20.00 of it as gratuity, which is not what you meant.
Both fields are integers in cents. tip accepts 0, and omitting it means the same thing.
Send both fields with the transaction.
This is the more common shape in hospitality: authorize the bill, let the customer add a tip, capture the total.
Authorize the base amount first, then send the total and the tip together at capture.
{
"amount": 12000,
"tip": 2000
}Two things to get right:
- The capture
amountincludes the tip. It is the total you are taking, the same rule as on a sale. - You cannot capture more than you authorized. A tip that pushes the total above the authorization will not go through. Authorize with enough headroom for the tip you expect — the usual practice is to add a percentage to the bill when you authorize.
Authorize and capture covers the rest of that flow.
The response echoes tip alongside amount, on the transaction and on every later read of it. The settled amount is amount; the tip is reported to the card network separately and does not add to it.