Terminal payments
Create and manage card-present payments via VINR terminals.
A terminal payment represents a card-present transaction initiated through a VINR hardware terminal.
You create the payment via the API and, in cloud mode, the terminal executes the reader interaction
automatically. Listen for the terminal_payment.completed webhook to confirm the outcome rather than
polling.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The terminal payment objectAsk
idstringUnique identifier for the terminal payment, e.g. tpy_4Rk9.
terminalIdstringThe ID of the VINR terminal that executed or will execute this payment.
amountintegerAmount intended to be collected, in the smallest currency unit (e.g. cents).
currencystringThree-letter ISO 4217 currency code, e.g. EUR.
statusenumOne of pending, processing, authorized, completed, failed, cancelled, or expired.
captureMethodenumEither automatic (default — authorize and capture in one step) or manual (authorize now,
capture later).
amountCapturedintegerAmount already captured, in the smallest currency unit.
amountCapturableintegerRemaining authorized amount available to capture, in the smallest currency unit.
referencestringYour internal order or transaction reference, echoed back on webhooks and the dashboard.
paymentMethodobjectDetails of the instrument presented at the terminal.
tipobjectTip collected at the terminal, if any.
metadataobjectSet of key-value pairs you can attach to the payment. See Metadata.
createdAtintegerUnix timestamp (seconds) when the payment was created.
completedAtinteger | nullUnix timestamp (seconds) when the payment reached a terminal state. null while still in
progress.
Create a terminal paymentAsk
Pass a terminalId, amount, and currency. In cloud mode the terminal begins the reader
interaction automatically. The returned object has status: "pending" — subscribe to the
terminal_payment.completed webhook for the final outcome.
Retrieve a terminal paymentAsk
Capture a terminal paymentAsk
Required when captureMethod was set to manual at creation. The payment must be in authorized
status. Omit amount to capture the full authorized amount, or pass a lower value to do a partial
capture.
Cancel a terminal paymentAsk
Cancellation is only valid while status is pending — before the terminal begins executing the
reader interaction. Once the terminal is processing or beyond, cancellation is not possible.
List terminal paymentsAsk
Returns a paginated list of terminal payments ordered by createdAt descending.
| Parameter | Type | Description |
|---|---|---|
terminalId | string | Filter by terminal ID. |
locationId | string | Filter by the location the terminal belongs to. |
status | enum | One of pending, processing, authorized, completed, failed, cancelled, expired. |
fromDate | integer | Unix timestamp — return payments created at or after this time. |
toDate | integer | Unix timestamp — return payments created at or before this time. |
limit | integer | Number of results to return. Default 10, max 100. |
starting_after | string | Cursor for forward pagination — the id of the last item from the previous page. |
Next stepsAsk
- Accept an in-person payment — end-to-end integration guide
- Terminals — manage terminal devices and locations
- Refunds — refund a completed terminal payment
