Terminal API Overview
Programmatically initiate card-present payments, manage devices, and handle terminal events
The Terminal API lets you programmatically initiate card-present payments on a merchant's PAX terminal, query terminal devices, and manage the lifecycle of terminal transactions (cancel, refund, void). All terminal operations flow through the same V2 API and use the same authentication, idempotency, and webhook patterns as online payments.
- How to authenticate and scope API keys for terminal operations
- Terminal API resource model (Devices and Payments)
- Base URLs and environments
- How the
payment_channelfield distinguishes terminal from online payments
Version note: This documentation covers Connector v0.1.x and Terminal API v2.
Authentication and Scopes
Terminal endpoints require an API key with the appropriate scopes:
| Scope | Access |
|---|---|
terminal:read | List and retrieve terminal devices and payments |
terminal:write | Initiate, cancel, refund, and void terminal payments |
Create an API key with these scopes from Dashboard > Developers > API Keys.
curl -H "x-api-key: rk_live_your_api_key" \
https://api.revkeen.com/v2/terminal-devicesBase URLs
| Environment | Base URL |
|---|---|
| Production | https://api.revkeen.com/v2 |
| Sandbox | https://sandbox-api.revkeen.com/v2 |
| Mock Server | localhost:4010 (run cd packages/openapi && pnpm mock) |
Resource Model
The Terminal API has two main resources:
Terminal Devices
Represents a physical PAX terminal connected through a connector. Each device has:
- A unique device ID
- A terminal serial number
- Connection status (online/offline/pairing)
- Heartbeat timestamp
Endpoints: GET /v2/terminal-devices, GET /v2/terminal-devices/{id}
Terminal Payments
Represents a card-present payment attempt. Each payment has:
- A type:
sale,refund, orvoid - A status lifecycle:
requested→approved/declined/error/timed_out/cancelled - Card-present metadata: entry mode, card scheme, masked PAN, auth code
Endpoints: POST /v2/terminal-payments, GET /v2/terminal-payments, GET /v2/terminal-payments/{id}, POST /v2/terminal-payments/{id}/cancel, POST /v2/terminal-payments/{id}/refund, POST /v2/terminal-payments/{id}/void
Payment Channel
Every transaction in RevKeen includes a payment_channel field:
| Value | Meaning |
|---|---|
card_present | Payment was collected at a physical terminal (tap, chip, swipe) |
card_not_present | Payment was collected online (checkout, API, recurring billing) |
bank_transfer | ACH or direct debit |
manual | Manually recorded payment |
The entry_mode field provides additional detail for card_present payments:
| Value | Description |
|---|---|
contactless | Customer tapped their card or phone (NFC) |
emv_chip | Customer inserted their card into the chip reader |
magnetic_stripe | Customer swiped their card |
manual_entry | Card number was entered manually on the terminal keypad |
fallback | Terminal fell back from chip to magnetic stripe due to chip read failure |
Rate Limiting
Terminal endpoints share the same rate limits as other V2 API endpoints:
- Standard tier: 1,000 requests per minute
- Pro tier: 5,000 requests per minute
Check X-RateLimit-Remaining and X-RateLimit-Reset headers in responses.
Interactive Reference
Explore the Terminal API endpoints interactively:
- Scalar API Reference -- Try terminal endpoints directly from the browser
- Mock Server -- Test with realistic mock responses locally
Next Steps
- Devices API -- Query and monitor terminal devices
- Payments API -- Initiate, cancel, refund, and void payments
- Webhook Events -- Subscribe to terminal payment events
- Best Practices -- Idempotency, error handling, and testing