Terminal API Overview

The Terminal API lets you initiate card-present payments, discover devices, and process terminal operations through the same RevKeen platform used for online billing.

Use this page for the terminal integration model. Use API Reference for endpoint details, schemas, and request examples.

What the terminal surface covers

Device discovery Find the correct device_id before initiating a payment.
Payment lifecycle Initiate sale, refund, and void flows and track the resulting terminal state.
Async results Use webhooks for approved, declined, cancelled, timed-out, and error outcomes.
Operational safety Handle per-device concurrency, stale heartbeats, retries, and idempotency carefully.

Core flow

List terminal devices and choose an online, paired device.
Create a terminal payment against that device_id.
Wait for the result through webhooks or by polling the payment resource.
Reconcile the card-present result with the rest of your billing workflow.

Environment model

Use the same public API environments as the rest of RevKeen:

Environment	Base URL	Use when
Staging	`https://staging-api.revkeen.com/v2`	Integration development, QA, device workflow validation
Production	`https://api.revkeen.com/v2`	Live terminal traffic
Mock	`https://mock-api.revkeen.com/v2`	Response-shape validation only

Operating principles

Always check device status before creating a payment.
Use Idempotency-Key on terminal write operations.
Expect results asynchronously and prefer webhook-driven state updates.
Treat device_busy, offline devices, and timed-out flows as normal operating cases.

Next Steps

Terminal Payments Reference

Use Scalar for payment endpoints, request bodies, and response schemas.

Terminal Devices Reference

Use Scalar for device discovery and device status details.

Webhooks

Handle terminal delivery reliability the same way you handle the rest of RevKeen webhooks.