Terminal Reference
Objects, statuses, errors, and webhook events for Terminal.
Read the overview and the integration page first.
Reader object
| Field | Type | Description |
|---|---|---|
id | string | Reader id. |
label | string | What the cashier calls this device. Free text. |
status | enum | ACTIVE, BLOCKED, COMPROMISED, or REVOKED. |
connection_status | enum | online or offline. |
created_at | timestamp | When the Reader first registered. |
updated_at | timestamp | When the Reader row last changed. |
Reader status
A Reader has one of four statuses.
| Status | Meaning |
|---|---|
ACTIVE | The Reader can take payments. |
BLOCKED | The Reader is temporarily stopped. |
COMPROMISED | The Reader is permanently stopped for a security reason. |
REVOKED | The Reader is permanently stopped by request. |
A Reader leaves ACTIVE in one direction only. To use the device again, approve it as a new Reader. Deleting a Reader sets it to REVOKED. Its past payments stay on record.
Connection status
| Value | Meaning |
|---|---|
online | The Reader sent a signal recently. |
offline | The Reader has not sent a signal recently. |
Terminal object
| Field | Type | Description |
|---|---|---|
id | string | Terminal id. |
merchant_id | string | The merchant this Terminal belongs to. |
location_id | string, nullable | The Location this Terminal trades from. |
name | string | What the merchant calls this Terminal. |
type | enum | softpos. |
status | enum | pending, active, or deleted. |
capabilities | array | Payment methods this Terminal may take. |
permissions | object | What this Terminal is allowed to do. |
Terminal status
| Status | Meaning |
|---|---|
pending | The Terminal is registered but not yet ready to take payments. |
active | The Terminal can take payments. |
deleted | The merchant withdrew this Terminal. |
Capability entry
| Field | Type | Description |
|---|---|---|
name | enum | card_present, napas_qr, or visa_qr. |
status | enum | active, pending, restricted, or unsupported. |
Only an active capability is accepted. A Terminal takes a payment method when the capability for that method is active.
Permissions
| Field | Type | Description |
|---|---|---|
accept_payment | bool | The Terminal may accept a payment. |
export_invoice | bool | The Terminal may export an invoice. |
view_history | bool | The Terminal may view payment history. |
Errors
| Error code | Type | HTTP status | Cause | Action |
|---|---|---|---|---|
terminal_reader_busy | api_error | 500 | The Reader already runs an action. | Wait until the action ends. Or call cancel_action. |
terminal_reader_timeout | api_error | 500 | The Reader did not answer in time. | Retry the request. |
intent_invalid_state | invalid_request_error | 400 | The PaymentIntent is not in requires_payment_method. | Create a new PaymentIntent. |
resource_missing | invalid_request_error | 400 | The Reader has no action in progress. | Check the Reader before you cancel. |
Bahn sets the HTTP status from the error type: card_error and invalid_request_error return 400, authentication_error returns 401, idempotency_error returns 409, rate_limit_error returns 429, and api_error returns 500.
Webhook events
PaymentIntent events
| Event | Description |
|---|---|
payment_intent.status.succeeded | The payment is complete. |
payment_intent.status.requires_payment_method | The payment was declined. Send the PaymentIntent to the Reader again. |
payment_intent.status.canceled | The PaymentIntent was canceled. |
Reader action events
| Event | Description |
|---|---|
reader_action.status.succeeded | Bahn authorized the payment. |
reader_action.status.failed | The payment was declined, timed out, or the Reader lost its connection. Read failure_code, failure_message, and failure_decline_code. |
reader_action.status.canceled | You or the customer canceled the action. |
See Events for the full payloads.