Device/adjustTerminalPaymentTip

Adjust the tip on an open authorization

POST/api/v1/terminal/payments/{id}/tip-adjust

Processor-backed, idempotent tip adjustment. The payment remains awaiting capture and its authorized total becomes baseAmountMinor plus tipAmountMinor. Fails when the configured acquirer does not support tip adjustment.

Path parameters

idstringRequired

Request body

application/json

tipAmountMinorintegerRequired

Example 180

tipSourcestring

Example "preset:1800"

Response

application/json

idstringRequired

Stable payment identifier. Payment IDs use the engine's UUID identifier format across every acceptance channel.

Example "0195d46e-7088-7cc4-a9b2-5f9273cd63b8"

merchantIdstringRequired

Owning merchant. Required on every payment: one engine needs one tenancy root, stated rather than implied by the credential used.

Example "mch_123"

acceptanceChannelenumRequired

How the payment was accepted. `EXTERNAL_RAIL` covers sales authorized by a pre-certified terminal app on someone else's rail. kepa records them for reporting and never enters their authorization loop, so they carry no kepa authorization state.

CARD_PRESENTCARD_NOT_PRESENTEXTERNAL_RAIL

statusenumRequired

Where the payment is in its lifecycle. This reconciles two previously separate machines: card-present was terminal-outcome-shaped (`APPROVED`, `REVERSED`) and online was intent-lifecycle-shaped (`REQUIRES_CONFIRMATION`, `SUCCEEDED`). They shared exactly one member. `REQUIRES_CAPTURE` covers both an online uncaptured authorization and a terminal pre-auth awaiting completion: both are authorized, holding funds, and waiting on a second message. Use `type` to tell them apart. `FAILED` means the outcome is unknown, not that no money moved — a payment that failed in flight may still be reversed.

REQUIRES_PAYMENT_METHODREQUIRES_CONFIRMATIONREQUIRES_ACTIONPROCESSINGREQUIRES_CAPTURESUCCEEDEDDECLINEDREVERSEDCANCELEDFAILED

typeenumRequired

What kind of movement this is. A completed pre-authorization stays `PRE_AUTH` — completing it moves the same payment from `REQUIRES_CAPTURE` to `SUCCEEDED` rather than creating a second record. There is no `PRE_AUTH_COMPLETE` type: completion is an operation, not a state a payment can be in.

SALEPRE_AUTHREFUNDVOIDCARD_READBALANCE_INQUIRY

captureMethodenum

`AUTOMATIC` captures on approval. `MANUAL` holds the authorization open for a later capture, and is what distinguishes a completed pre-authorization from a straight sale once both are captured.

AUTOMATICMANUAL

capturedAmountMinorintegernullable

What was actually captured, which may be less than `amountMinor` — a tip adjusted down, a partial fulfilment. Null until capture, so an authorization awaiting capture is distinguishable from one captured for zero.

authExpiresAtstring · ISO 8601nullable

When the issuer's hold lapses. An expired authorization cannot be captured: the funds are no longer reserved.

Example "2026-04-09T09:14:22Z"

amountMinorintegerRequired

Amount in the currency's minor unit — 2500 is NZD 25.00. Named `amountMinor`, not `amount`, because the unit is the field most likely to cause a money bug and the name should carry it.

Example 2500

baseAmountMinorintegerRequired

Subtotal before the tip, in minor units.

Example 2200

currencyCodestringRequired

ISO 4217 currency code.

Example "NZD"

tipAmountMinorintegerRequired

Tip in minor units, where the channel supports it.

Example 0

tipSourcestringnullable

How the terminal collected the tip, such as `preset:1800`, `fixed:100`, `custom`, or `none`.

Example "preset:1800"

cashbackAmountMinorinteger

Cashback in minor units, card-present only.

customerIdstring

Customer this payment belongs to, when one is attached.

Example "cus_123"

referenceIdstring

Caller-assigned reference, echoed back on every read.

Example "POS-INV-20260328-001"

authorizationCodestring

Issuer authorization code.

Example "A12345"

responseCodestring

ISO 8583 response code. `"00"` is approved.

Example "00"

cardSchemeenum

VISAMASTERCARDAMEXDISCOVERJCBUNIONPAYEFTPOSOTHER

Example "VISA"

maskedPanstring

Masked account number. Never more than the first six and last four digits; the engine drops any value revealing more.

Example "************1234"

rrnstring

Retrieval reference number.

Example "262803141422"

declineobject

Why a payment did not succeed, and what to do about it. The engine already computes this taxonomy to drive its own retry and cascade decisions; this exposes it rather than adding new behaviour. It is what makes "retries are automatic" legible to an integrator.

cardPresentobject

Present when `acceptanceChannel` is `CARD_PRESENT`.

cardNotPresentobject

Present when `acceptanceChannel` is `CARD_NOT_PRESENT`.

settlementIdstringnullable

Settlement batch this payment was funded in, once settled.

Example "stl_01JQDAY00042"

metadataobject

Caller-supplied key/value metadata. Max 20 keys, 256 characters per value.

createdAtstring · ISO 8601Required

Example "2026-04-09T09:14:22Z"

updatedAtstring · ISO 8601

Example "2026-04-09T09:14:22Z"

adjustTerminalPaymentTip