Readers
A reader is payment hardware at one of your locations. There are two types:
smart_reader: a Stripe Reader S710 or S700 countertop reader. The S710 is the S700 with optional 4G/LTE cellular, and Flint recommends it. Your server sends it payments through Flint, so nothing runs on your point-of-sale device.tap_to_pay: a phone that takes Tap to Pay in your app with the Stripe Terminal SDK. Your server gives the app connection sessions from Flint.
A reader is separate from a device, which records the register, kiosk or phone that runs your app. A reader can name the device it takes payments for in device_id. Each environment keeps its own readers, so a test key sees only sandbox readers.
Take card-present payments on smart readers through the payment intent confirm route or order pay route. You can register Tap to Pay readers and open connection sessions, but taking payments on them is not supported.
Scopes#
Listing and retrieving readers requires payments.readers.read or payments.readers.write. Registering, updating, archiving, connection sessions and simulation require payments.readers.write. Naming a device in device_id also requires accounts.devices.read, so a credential can't probe for devices it can't see.
Partner apps can request both scopes. An install token holding them works with the installed merchant's readers within its grant. Readers belong to the merchant and stay when the app is uninstalled.
Register a smart reader#
Plug in the reader and open Settings on its screen to show its pairing code. Then register it at the location where it sits:
curl -X POST https://api.withflintpay.com/v1/readers \
-H "Authorization: Bearer flint_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: register-front-counter" \
-d '{
"type": "smart_reader",
"registration_code": "puppy-hamster-banana",
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"name": "Front counter"
}'
A pairing code works once, so send an Idempotency-Key. A retry with the same key returns the same reader, even after a timeout. Flint registers the reader with Stripe, reads its model and serial_number, and returns 201 with the reader. Registering needs no live payment readiness.
registration_codeis never returned. A code that is unknown, expired or already used, a live code in a sandbox, or a reader of a model Flint doesn't support returns400 INVALID_REQUESTwithparam: "registration_code". Flint unregisters a reader of an unsupported model before answering, so you can pair it elsewhere.- In a sandbox,
registration_code: simulated-s700registers a simulated Stripe Reader S700 withis_simulated: true. See Simulate a card.
Register a Tap to Pay reader#
Register one Tap to Pay reader for each phone that takes payments:
curl -X POST https://api.withflintpay.com/v1/readers \
-H "Authorization: Bearer flint_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "tap_to_pay",
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"device_id": "dev_01KF4Q6R8T0Y2U4I6O8P0A2S4D",
"name": "Ana'\''s iPhone"
}'
A Tap to Pay reader has no registration_code, model, serial_number or connectivity.
Locations and devices#
location_idmust be an active location with a complete US address:line1,city,state,postal_codeandcountry: US. Stripe requires every reader to have one. Otherwise Flint returns409 ACTION_NOT_ALLOWEDwith reasonconfiguration_required,resource_type: locationandparam: "location_id".- A reader's location never changes. To move a reader, archive it and register it again at the new location.
device_idis optional on both types and must be an active device in the same environment. When the device has a location, it must be the reader's, or Flint returns400 INVALID_REQUESTwithparam: "location_id".- A device holds at most one active Tap to Pay reader. A second returns
409 ALREADY_EXISTSwith reasondevice_reader_already_existsand the existing reader indetails[0].current_resource. - An environment holds at most 500 active readers. Another returns
409 LIMIT_REACHEDwith reasonactive_readers. - While a location has active readers, archiving it or changing its address to one readers can't use returns
409 RESOURCE_IN_USEwith the readers inblocking_resources. Archiving a device that an active reader names does the same.
Flint keeps the reader's Stripe location in step with its Flint location: a change to the location's name or address reaches Stripe shortly after.
List and retrieve readers#
curl "https://api.withflintpay.com/v1/readers?location_id=loc_01KEZF7C00CMHRRYA3MV996JB2&type=smart_reader" \
-H "Authorization: Bearer flint_live_YOUR_KEY"
GET /v1/readers returns readers newest first, then by reader_id. Filter by location_id, device_id and type, each an exact match. Archived readers are left out unless the status filter names archived. Set page_size from 1 to 100, with 20 by default, and pass next_page_token as the next request's page_token.
GET /v1/readers/{reader_id} returns one reader, including an archived one. A reader in another environment returns 404 RESOURCE_NOT_FOUND, the same as an unknown ID.
active_payment_intent_id names the payment presented on the reader now, and is omitted while the reader is idle. It follows the payment, so it doesn't advance the reader's version or send a reader event.
Connectivity#
An active smart reader's connectivity is what Flint last observed, and an archived reader omits it: status (online or offline, and other values may be added), last_seen_at (when the reader last reached Stripe) and observed_at. Flint refreshes it when it sends, cancels or simulates a payment on the reader, and every five minutes for active live smart readers. It changes without a write, doesn't advance version, and sends no event. Don't gate a sale on it: Flint checks the reader itself before it sends a payment.
Update a reader#
curl -X PATCH https://api.withflintpay.com/v1/readers/rdr_01KF4Q2W8E6R0T2Y4U6I8O0P2A \
-H "Authorization: Bearer flint_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Back counter", "expected_version": 1}'
PATCH /v1/readers/{reader_id} changes name, device_id and metadata, with the device rules above. device_id: null clears the device. metadata merges by key, and metadata: null clears it. type and location_id can't change. expected_version is optional; a stale value returns 409 VERSION_CONFLICT with the current version. An update that changes nothing keeps the version and sends no event. An archived reader can't change: 409 ACTION_NOT_ALLOWED with reason archived.
Archive a reader#
DELETE /v1/readers/{reader_id} archives the reader and returns it with status: archived. A smart reader is unregistered from Stripe shortly after, so its hardware can be paired again. A Tap to Pay reader stops getting connection sessions at once. An archived reader takes no payments or sessions.
While a payment is presented on the reader, DELETE returns 409 RESOURCE_IN_USE with the payment intent in blocking_resources. Archiving an archived reader returns it unchanged. The optional expected_version query parameter works as for updates.
Connection sessions#
The Stripe Terminal SDK asks your app for a connection token whenever it connects. Your app asks your server, and your server asks Flint:
curl -X POST https://api.withflintpay.com/v1/readers/rdr_01KF4Q7Y9U1I3O5P7A9S1D3F5G/connection-sessions \
-H "Authorization: Bearer flint_live_YOUR_KEY"
{
"data": {
"reader_id": "rdr_01KF4Q7Y9U1I3O5P7A9S1D3F5G",
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"client_session": {
"stripe": {
"connection_token": "pst_live_YWNjdF8x...",
"location_id": "tml_FjRwD2kYxJ8gQb"
}
}
},
"request_id": "req_01KF4Q8A0S2D4F6G8H0J2K4L6Z"
}
- Return
client_session.stripe.connection_tokenfrom the SDK'sfetchConnectionTokencallback, and passclient_session.stripe.location_id, a Stripe location ID, toTapToPayConnectionConfiguration. - Each call creates a new single-use token, including a retry with the same
Idempotency-Key.client_sessionappears only in this response, never on the reader, in lists or in webhooks. - The token works only with readers at the reader's location. It is scoped to the location, not to one phone, so your server decides which phone gets which session. Keep your credential on your server.
- Connection sessions are for Tap to Pay readers: a smart reader returns
409 ACTION_NOT_ALLOWEDwith reasonreader_type_not_supported, and an archived reader returns reasonarchived. - A merchant whose card payments aren't ready returns
409 MERCHANT_NOT_READYwith the readiness reason. A Stripe failure returns502 EXTERNAL_SERVICE_ERROR; try again. - Archiving the reader, or uninstalling the app that holds the session's credential, stops new tokens at once. A connected SDK keeps its Stripe connection until it next asks for a token.
Simulate a card#
In a sandbox, POST /v1/readers/{reader_id}/simulate presents a Stripe test card on a simulated reader for the payment presented on it, so the result arrives the way a real tap's does. It returns the reader.
curl -X POST https://api.withflintpay.com/v1/readers/rdr_01KF4Q2W8E6R0T2Y4U6I8O0P2A/simulate \
-H "Authorization: Bearer flint_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"outcome": "approved", "card_brand": "visa", "tip_money": {"amount": 300, "currency": "USD"}}'
outcomeis required:approved,declinedorinsufficient_funds.card_brandis optional,visaby default:visa,mastercard,amexordiscover. Declines present Visa test cards whatever brand you send.tip_moneyis the tip the buyer picks, in USD, for a payment sent with the tip screen on. Otherwise it returns400 INVALID_REQUESTwithparam: "tip_money".- A live credential returns
403 FORBIDDENwith reasontest_mode_required. A physical or Tap to Pay reader returns409 ACTION_NOT_ALLOWEDwith reasonsimulated_reader_required, and a reader with no payment presented returns reasonstatus_not_reached.
Resetting or archiving a sandbox archives its readers, unregisters them from Stripe and deletes their Stripe test locations, so a physical reader paired in the sandbox can be paired again at once.
Events#
| Event | When |
|---|---|
reader.created | A reader is registered. |
reader.updated | A reader's name, device_id or metadata changes. |
reader.archived | A reader is archived. |
Each event carries the reader. Connectivity and active_payment_intent_id change without an event. Partner apps holding payments.readers.read receive these events for their installed merchants.
Errors#
| Code | Reason | When |
|---|---|---|
400 INVALID_REQUEST | An unusable registration_code, a device at another location, a tip_money without the tip screen, or another invalid field. param names it. | |
403 INSUFFICIENT_SCOPE | device_id without accounts.devices.read. | |
403 FORBIDDEN | test_mode_required | simulate with a live credential. |
404 RESOURCE_NOT_FOUND | An unknown reader, location or device. | |
409 ACTION_NOT_ALLOWED | configuration_required | The location isn't active with a complete US address. |
409 ACTION_NOT_ALLOWED | archived | A write, session or simulation on an archived reader, or an archived device. |
409 ACTION_NOT_ALLOWED | reader_type_not_supported | A connection session for a smart reader. |
409 ACTION_NOT_ALLOWED | simulated_reader_required | simulate on a physical or Tap to Pay reader. |
409 ACTION_NOT_ALLOWED | status_not_reached | simulate with no payment presented on the reader. |
409 ALREADY_EXISTS | device_reader_already_exists | A second active Tap to Pay reader on one device. |
409 LIMIT_REACHED | active_readers | 500 active readers in the environment. |
409 RESOURCE_IN_USE | Archiving a reader with a payment presented on it. | |
409 VERSION_CONFLICT | A stale expected_version. | |
409 MERCHANT_NOT_READY | Card payments aren't ready, when registering a smart reader, creating a connection session or simulating. | |
502 EXTERNAL_SERVICE_ERROR | Stripe didn't complete the request. Try again. | |
503 PAYMENT_PROCESSING_UNAVAILABLE | Payment processing is temporarily unavailable for the merchant environment. Try again. |
Related#
LocationsCreate the locations readers sit at, with a complete US address.DevicesRecord the registers, kiosks and phones that run your app.IdempotencyRetry a registration safely with an Idempotency-Key.The Reader object#
A card reader or Tap to Pay phone that takes in-person payments at a location.
Returned by GET /v1/readers/{reader_id} and carried by the endpoints below.
Attributes
active_payment_intent_idstringThe payment intent presented on the reader now. Omitted while the reader is idle. It follows the payment, so it doesn't advance the reader's `version` or send a reader event.
connectivityobjectSmart readers only, and omitted once the reader is archived. Observed reader state: it changes without a write, doesn't advance `version`, and sends no event. Don't gate a sale on it: Flint checks the reader itself before it sends a payment.
last_seen_atstring or nullWhen the reader last reached Stripe. Omitted when it never has.
observed_atstringRequiredWhen Flint observed this.
statusenumRequiredWhether the reader was reaching Stripe when Flint last observed it.
onlineoffline
created_atstringRequiredWhen the reader was registered.
device_idstringThe register, kiosk or phone the reader takes payments for; on a Tap to Pay reader, the phone it runs on. Omitted when none is set.
is_simulatedbooleanRequired`true` for a sandbox simulated reader, registered with `registration_code: simulated-s700`.
location_idstringRequiredThe location the reader is at. Set at registration and never changed: to move a reader, archive it and register it again.
metadatamap of stringRequiredYour key-value pairs for the reader.
modelenumThe smart reader's model, read from the reader at registration. Smart readers only.
stripe_reader_s700stripe_reader_s710other
namestringRequiredYour label for the reader.
reader_idstringRequiredUnique identifier for the reader.
serial_numberstringThe smart reader's serial number, read from the reader at registration. Smart readers only.
statusenumRequiredWhether the reader can take payments.
activearchived
typeenumRequiredWhat kind of reader it is. A smart reader is driven from your server; a Tap to Pay reader is a phone driven by the Stripe Terminal SDK in your app.
smart_readertap_to_pay
updated_atstringRequiredWhen the reader last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"active_payment_intent_id": "pi_01KEZF7C00G26W9S1Y3D318MZK",
"connectivity": {
"last_seen_at": "2026-11-12T16:40:02Z",
"observed_at": "2026-11-12T16:40:21Z",
"status": "online"
},
"created_at": "2026-11-09T18:02:11Z",
"device_id": "dev_01KEZF7C0096ZG1YZWTWT30ZXN",
"is_simulated": false,
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"metadata": {
"lane": "1"
},
"model": "stripe_reader_s700",
"name": "Front counter",
"reader_id": "rdr_01KEZF7C00HK9FNY9ADZF01C6Z",
"serial_number": "STRM26138003393",
"status": "active",
"type": "smart_reader",
"updated_at": "2026-11-09T18:02:11Z",
"version": 1
}List readers#
/v1/readersRequires scope payments.readers.read or payments.readers.write
Rate limit: read
Lists readers newest first, then by `reader_id`. Archived readers are listed only when the `status` filter names `archived`. Default order: created_at descending, then reader_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
statusarray of enumFilter by status. Omitted, the list leaves out archived rows; name archived to include them. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
activearchived
location_idstringExact match on the reader's Flint location ID.
device_idstringExact match on the reader's Flint device ID.
typearray of enumExact match on the reader's type. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
smart_readertap_to_pay
Response · 200
A page of readers.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
active_payment_intent_idstringThe payment intent presented on the reader now. Omitted while the reader is idle. It follows the payment, so it doesn't advance the reader's `version` or send a reader event.
connectivityobjectSmart readers only, and omitted once the reader is archived. Observed reader state: it changes without a write, doesn't advance `version`, and sends no event. Don't gate a sale on it: Flint checks the reader itself before it sends a payment.
created_atstringRequiredWhen the reader was registered.
device_idstringThe register, kiosk or phone the reader takes payments for; on a Tap to Pay reader, the phone it runs on. Omitted when none is set.
is_simulatedbooleanRequired`true` for a sandbox simulated reader, registered with `registration_code: simulated-s700`.
location_idstringRequiredThe location the reader is at. Set at registration and never changed: to move a reader, archive it and register it again.
metadatamap of stringRequiredYour key-value pairs for the reader.
modelenumThe smart reader's model, read from the reader at registration. Smart readers only.
stripe_reader_s700stripe_reader_s710other
namestringRequiredYour label for the reader.
reader_idstringRequiredUnique identifier for the reader.
serial_numberstringThe smart reader's serial number, read from the reader at registration. Smart readers only.
statusenumRequiredWhether the reader can take payments.
activearchived
typeenumRequiredWhat kind of reader it is. A smart reader is driven from your server; a Tap to Pay reader is a phone driven by the Stripe Terminal SDK in your app.
smart_readertap_to_pay
updated_atstringRequiredWhen the reader last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/readers \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of readers.
{
"data": [
{
"active_payment_intent_id": "pi_01KEZF7C00G26W9S1Y3D318MZK",
"connectivity": {
"last_seen_at": "2026-11-12T16:40:02Z",
"observed_at": "2026-11-12T16:40:21Z",
"status": "online"
},
"created_at": "2026-11-09T18:02:11Z",
"device_id": "dev_01KEZF7C0096ZG1YZWTWT30ZXN",
"is_simulated": false,
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"metadata": {
"lane": "1"
},
"model": "stripe_reader_s700",
"name": "Front counter",
"reader_id": "rdr_01KEZF7C00HK9FNY9ADZF01C6Z",
"serial_number": "STRM26138003393",
"status": "active",
"type": "smart_reader",
"updated_at": "2026-11-09T18:02:11Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Register a reader#
/v1/readersIdempotentRequires scope payments.readers.write
Rate limit: external_provider_action
Readers are payment hardware at a location: a Stripe Reader S710 or S700 your server sends payments to through Flint (`smart_reader`), or a phone that takes Tap to Pay in your app with the Stripe Terminal SDK (`tap_to_pay`). A reader is separate from a device, which records the register or phone that runs your app. Registers a smart reader with its pairing code, or a Tap to Pay reader for a phone, at a location with a complete US address. A pairing code works once, so send an `Idempotency-Key`: a retry with the same key returns the same reader. Registering needs no live payment readiness; payments on the reader do. Sends `reader.created`.
Request body
Send exactly one of these
Registers a countertop reader with the pairing code it shows under Settings.
device_idstringThe register, kiosk or phone the reader takes payments for. Needs `accounts.devices.read` as well. When the device has a location, it must be the reader's. A device holds at most one active Tap to Pay reader.
location_idstringRequiredAn active location with a complete US address (`line1`, `city`, `state`, `postal_code`, `country: US`). Stripe requires every reader to have one.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
namestringRequiredYour label for the reader. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
registration_codestringRequiredThe pairing code the reader shows under Settings. In a sandbox, `simulated-s700` registers a simulated Stripe Reader S700. Never returned. A code works once, so send an `Idempotency-Key` and retry with it.
typeenumRequired`smart_reader`.
smart_reader
Registers a phone that takes payments with Tap to Pay in your app.
device_idstringThe register, kiosk or phone the reader takes payments for. Needs `accounts.devices.read` as well. When the device has a location, it must be the reader's. A device holds at most one active Tap to Pay reader.
location_idstringRequiredAn active location with a complete US address (`line1`, `city`, `state`, `postal_code`, `country: US`). Stripe requires every reader to have one.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
namestringRequiredYour label for the reader. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
typeenumRequired`tap_to_pay`.
tap_to_pay
Response · 201
The registered reader.
dataobjectRequiredResource, collection, or operation result returned by this request.
active_payment_intent_idstringThe payment intent presented on the reader now. Omitted while the reader is idle. It follows the payment, so it doesn't advance the reader's `version` or send a reader event.
connectivityobjectSmart readers only, and omitted once the reader is archived. Observed reader state: it changes without a write, doesn't advance `version`, and sends no event. Don't gate a sale on it: Flint checks the reader itself before it sends a payment.
created_atstringRequiredWhen the reader was registered.
device_idstringThe register, kiosk or phone the reader takes payments for; on a Tap to Pay reader, the phone it runs on. Omitted when none is set.
is_simulatedbooleanRequired`true` for a sandbox simulated reader, registered with `registration_code: simulated-s700`.
location_idstringRequiredThe location the reader is at. Set at registration and never changed: to move a reader, archive it and register it again.
metadatamap of stringRequiredYour key-value pairs for the reader.
modelenumThe smart reader's model, read from the reader at registration. Smart readers only.
stripe_reader_s700stripe_reader_s710other
namestringRequiredYour label for the reader.
reader_idstringRequiredUnique identifier for the reader.
serial_numberstringThe smart reader's serial number, read from the reader at registration. Smart readers only.
statusenumRequiredWhether the reader can take payments.
activearchived
typeenumRequiredWhat kind of reader it is. A smart reader is driven from your server; a Tap to Pay reader is a phone driven by the Stripe Terminal SDK in your app.
smart_readertap_to_pay
updated_atstringRequiredWhen the reader last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/readers \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"device_id": "dev_01KEZF7C0096ZG1YZWTWT30ZXN",
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"name": "Front counter",
"registration_code": "puppy-hamster-banana",
"type": "smart_reader"
}'Get a reader#
/v1/readers/{reader_id}Requires scope payments.readers.read or payments.readers.write
Rate limit: read
Returns a reader, including an archived one, with the payment presented on it now in `active_payment_intent_id`.
Path parameters
reader_idstringRequiredFlint reader ID. Must be a valid ID with prefix rdr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
curl https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The reader.
{
"data": {
"active_payment_intent_id": "pi_01KEZF7C00G26W9S1Y3D318MZK",
"connectivity": {
"last_seen_at": "2026-11-12T16:40:02Z",
"observed_at": "2026-11-12T16:40:21Z",
"status": "online"
},
"created_at": "2026-11-09T18:02:11Z",
"device_id": "dev_01KEZF7C0096ZG1YZWTWT30ZXN",
"is_simulated": false,
"location_id": "loc_01KEZF7C00CMHRRYA3MV996JB2",
"metadata": {
"lane": "1"
},
"model": "stripe_reader_s700",
"name": "Front counter",
"reader_id": "rdr_01KEZF7C00HK9FNY9ADZF01C6Z",
"serial_number": "STRM26138003393",
"status": "active",
"type": "smart_reader",
"updated_at": "2026-11-09T18:02:11Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update a reader#
/v1/readers/{reader_id}IdempotentRequires scope payments.readers.write
Rate limit: write
Changes a reader's `name`, `device_id` (`null` clears it) and `metadata` (merged by key). A reader's `type` and `location_id` never change: to move a reader, archive it and register it again at the new location. An archived reader can't change. Sends `reader.updated`.
Path parameters
reader_idstringRequiredFlint reader ID. Must be a valid ID with prefix rdr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
device_idstring or nullThe device the reader takes payments for. `null` clears it. Naming a device needs `accounts.devices.read` as well.
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
metadatamap of string or nullKeys to set, merged into the reader's metadata. A key with an empty value is removed; `null` clears all metadata.
namestringYour label for the reader. Can't be null. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
curl -X PATCH https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"name": "Back counter"
}'Archive a reader#
/v1/readers/{reader_id}IdempotentRequires scope payments.readers.write
Rate limit: write
Archives a reader and returns it with `status: archived`. A smart reader is unregistered from Stripe shortly after, so its hardware can be paired again; a Tap to Pay reader stops getting connection sessions at once. Refused with `RESOURCE_IN_USE` while a payment is presented on the reader. Archiving an archived reader returns it unchanged. Sends `reader.archived`.
Path parameters
reader_idstringRequiredFlint reader ID. Must be a valid ID with prefix rdr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
expected_versionintegerOptional version most recently read. A stale value fails with `VERSION_CONFLICT` and the current version.
curl -X DELETE https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Create a reader connection session#
/v1/readers/{reader_id}/connection-sessionsIdempotentRequires scope payments.readers.write
Rate limit: external_provider_action
Tap to Pay readers only. Creates a fresh single-use Stripe Terminal connection token for the reader's location: return `client_session.stripe.connection_token` from the SDK's `fetchConnectionToken` callback, and pass `client_session.stripe.location_id` to `TapToPayConnectionConfiguration`. Each call creates a new token, including a retry with the same `Idempotency-Key`. The token works with readers at the reader's location, not only this phone, so your server decides which phone gets which session. Keep your credential on your server.
Path parameters
reader_idstringRequiredFlint reader ID. Must be a valid ID with prefix rdr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 201
The connection session.
dataobjectRequiredResource, collection, or operation result returned by this request.
client_sessionobjectRequiredWhat the Stripe Terminal SDK takes. Appears only in this response, never on the reader, in lists or in webhooks.
location_idstringRequiredThe reader's Flint location.
reader_idstringRequiredThe Tap to Pay reader the session is for.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C/connection-sessions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Simulate a card on a reader#
/v1/readers/{reader_id}/simulateIdempotentRequires scope payments.readers.write
Rate limit: external_provider_action
Sandbox only. Presents a Stripe test card on a simulated reader (registered with `registration_code: simulated-s700`) for the payment presented on it, so the result arrives the way a real tap's does. Returns the reader. A live credential gets `403 FORBIDDEN` with reason `test_mode_required`.
Path parameters
reader_idstringRequiredFlint reader ID. Must be a valid ID with prefix rdr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
card_brandenumThe brand of the test card to present. Defaults to `visa`. Declines present Visa test cards whatever brand you send.
visamastercardamexdiscover
outcomeenumRequiredThe buyer's and issuer's decision.
approveddeclinedinsufficient_funds
tip_moneyobjectThe tip the buyer picks, when the payment was sent with the tip screen on. USD only.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
curl -X POST https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C/simulate \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"card_brand": "visa",
"outcome": "approved",
"tip_money": {
"amount": 300,
"currency": "USD"
}
}'Was this helpful?