Prompt for a tip | Run Developers

Shows the tip screen on the terminal for the given base amount and returns the customer’s choice. This endpoint doesn’t read or charge a card. Returns an interaction_id immediately. Get the result with Get tip status or over WebSocket by subscribing to terminal_job:{interaction_id}.

Requires a terminal where capabilities.tip is true (see List terminals). Otherwise the request returns 400 not supported.

To prompt for a tip and charge the tip-inclusive total in one call, use Charge a card with include_tip set to true.

amount must include a decimal point. An amount without one is read as cents, so "10" is ten cents. Send "10.00" for ten dollars.

Tip interactions expire about 3 minutes after the last activity. A finished result is kept for 2 minutes.

400 error messages

Message	Cause
`not supported`	The terminal doesn’t support tipping.
`Field amount is required`	`amount` is missing.
`Field amount is invalid`	`amount` is zero, negative, non-numeric, or has more than two decimal places.
`Field tip_percent_presets is invalid`	A preset isn’t a whole number.

Authentication

AuthorizationBearer

Use a Payments API key as the bearer token: Authorization: Bearer <api_key>. Get a fresh key from Refresh API Keys.

Path parameters

device_idstringRequired

Hardware Serial Number (HSN) of the terminal, provided by your Integration Delivery lead.

Query parameters

midstringOptional

Merchant ID. Required when your bearer token is an ISV token acting on behalf of a merchant. If the mid can’t be resolved to an authorized account, the request returns 400.

Request

This endpoint expects an object.

amountstringRequiredformat: "^\d+\.\d{1,2}$"

Base amount before tip, in decimal dollars. Must be greater than zero with at most two decimal places. Include a decimal point: an amount without one is read as cents, so "10" is ten cents.

tip_promptstringOptionalDefaults to Add a tip?

Text shown above the tip options on the terminal.

tip_percent_presetslist of stringsOptional

Percentage buttons shown on the terminal, as whole numbers.

include_custom_tip_amountbooleanOptionalDefaults to true

Show a button for the customer to enter their own tip amount.

Response

Interaction accepted. Use the interaction_id to poll for status or subscribe over WebSocket.

interaction_idstringformat: "uuid"

Identifier for the queued interaction.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

503

Service Unavailable Error