Processing Payments

Once your terminal is set up and online, you can start accepting card-present payments. Payments can be initiated from the RevKeen dashboard or programmatically via the API.

What you'll learn

How to initiate a payment from an invoice
Walk-in payments without an invoice
Terminal selection with multiple devices
Payment progress and live status updates
Card entry modes and what they mean

From the Dashboard

Paying an Invoice

Navigate to the invoice you want to collect payment for
Click Pay via Terminal
If you have more than one terminal, select the device from the dropdown
The terminal will display the amount and prompt the customer to present their card
The customer taps, inserts, or swipes their card
Once approved, the invoice is automatically marked as paid

A progress overlay shows real-time status updates as the payment moves through each stage:

Stage	What's Happening
Sending to terminal	The payment command is being sent to the device
Waiting for payment	The terminal is displaying the amount and waiting for the card
Processing	The terminal is communicating with the payment processor
Approved	Payment succeeded -- the overlay auto-dismisses after 3 seconds

Walk-in Payments

For ad-hoc or walk-in payments where no invoice exists:

Go to Terminal > New Payment in the dashboard
Enter the amount and currency
Select the target terminal
The payment is processed and recorded as a standalone transaction

Business tip

Walk-in payments are ideal for retail counters, pop-up events, or any scenario where you are collecting payment without a pre-created invoice.

Terminal Selection

When you have multiple terminals connected, you'll be prompted to choose which device to send the payment to. The selection shows:

Device name (e.g., "Front Desk Terminal")
Terminal serial number
Status (online/offline)

Only terminals with an Online status can accept payments. If a terminal shows as offline, check that the connector is running and the terminal is powered on.

Via the API

You can initiate terminal payments programmatically using the Terminal Payments API:

const payment = await revkeen.terminalPayments.create({
  device_id: 'd1e2f3a4-b5c6-7890-abcd-ef1234567890',
  amount_minor: 5000,  // £50.00
  currency: 'GBP',
  invoice_id: 'inv_xxxxxxxx',  // Optional
});

The API returns immediately with a requested status. Use webhooks to receive the result asynchronously.

See the full Terminal Payments API documentation for all endpoints and options.

Payment Lifecycle

Every terminal payment moves through a defined set of statuses:

requested → in_progress → approved / declined / error / timed_out
                        → cancelled (if cancelled before completion)

Status	Description
`requested`	Payment command sent to terminal. Waiting for card presentation.
`in_progress`	Terminal is processing the transaction.
`approved`	Payment succeeded. Card was charged.
`declined`	Card was declined by the issuer or processor.
`cancelled`	Payment was cancelled before the customer presented their card.
`error`	Terminal encountered an error (hardware failure, connection issue).
`timed_out`	Terminal did not respond within 3 minutes.

Cancelling a Payment

If a payment is still in the requested or in_progress state, you can cancel it:

From the dashboard: Click Cancel on the payment progress overlay
Via the API: POST /v2/terminal-payments/{id}/cancel

Cancelling a payment that has already been approved has no effect -- use a void or refund instead.

Handling Declines

When a payment is declined, the progress overlay shows the decline reason with guidance:

Scenario	Guidance
Insufficient funds	Ask the customer to try a different card
Card expired	Ask for a different card
Invalid PIN	Ask the customer to re-enter their PIN
Card read error	Ask to try again or use a different entry method

You can click Try Again to re-initiate the payment on the same terminal.

Refunds and Voids -- Reverse terminal transactions
Terminal API: Payments -- Full API documentation for terminal payments
Troubleshooting -- Common issues and solutions

Processing Payments

On this page