Skip to content

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
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_code is 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 returns 400 INVALID_REQUEST with param: "registration_code". Flint unregisters a reader of an unsupported model before answering, so you can pair it elsewhere.
  • In a sandbox, registration_code: simulated-s700 registers a simulated Stripe Reader S700 with is_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
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_id must be an active location with a complete US address: line1, city, state, postal_code and country: US. Stripe requires every reader to have one. Otherwise Flint returns 409 ACTION_NOT_ALLOWED with reason configuration_required, resource_type: location and param: "location_id".
  • A reader's location never changes. To move a reader, archive it and register it again at the new location.
  • device_id is 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 returns 400 INVALID_REQUEST with param: "location_id".
  • A device holds at most one active Tap to Pay reader. A second returns 409 ALREADY_EXISTS with reason device_reader_already_exists and the existing reader in details[0].current_resource.
  • An environment holds at most 500 active readers. Another returns 409 LIMIT_REACHED with reason active_readers.
  • While a location has active readers, archiving it or changing its address to one readers can't use returns 409 RESOURCE_IN_USE with the readers in blocking_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
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
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
curl -X POST https://api.withflintpay.com/v1/readers/rdr_01KF4Q7Y9U1I3O5P7A9S1D3F5G/connection-sessions \
  -H "Authorization: Bearer flint_live_YOUR_KEY"
JSON
{
  "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_token from the SDK's fetchConnectionToken callback, and pass client_session.stripe.location_id, a Stripe location ID, to TapToPayConnectionConfiguration.
  • Each call creates a new single-use token, including a retry with the same Idempotency-Key. client_session appears 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_ALLOWED with reason reader_type_not_supported, and an archived reader returns reason archived.
  • A merchant whose card payments aren't ready returns 409 MERCHANT_NOT_READY with the readiness reason. A Stripe failure returns 502 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
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"}}'
  • outcome is required: approved, declined or insufficient_funds.
  • card_brand is optional, visa by default: visa, mastercard, amex or discover. Declines present Visa test cards whatever brand you send.
  • tip_money is the tip the buyer picks, in USD, for a payment sent with the tip screen on. Otherwise it returns 400 INVALID_REQUEST with param: "tip_money".
  • A live credential returns 403 FORBIDDEN with reason test_mode_required. A physical or Tap to Pay reader returns 409 ACTION_NOT_ALLOWED with reason simulated_reader_required, and a reader with no payment presented returns reason status_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#

EventWhen
reader.createdA reader is registered.
reader.updatedA reader's name, device_id or metadata changes.
reader.archivedA 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#

CodeReasonWhen
400 INVALID_REQUESTAn unusable registration_code, a device at another location, a tip_money without the tip screen, or another invalid field. param names it.
403 INSUFFICIENT_SCOPEdevice_id without accounts.devices.read.
403 FORBIDDENtest_mode_requiredsimulate with a live credential.
404 RESOURCE_NOT_FOUNDAn unknown reader, location or device.
409 ACTION_NOT_ALLOWEDconfiguration_requiredThe location isn't active with a complete US address.
409 ACTION_NOT_ALLOWEDarchivedA write, session or simulation on an archived reader, or an archived device.
409 ACTION_NOT_ALLOWEDreader_type_not_supportedA connection session for a smart reader.
409 ACTION_NOT_ALLOWEDsimulated_reader_requiredsimulate on a physical or Tap to Pay reader.
409 ACTION_NOT_ALLOWEDstatus_not_reachedsimulate with no payment presented on the reader.
409 ALREADY_EXISTSdevice_reader_already_existsA second active Tap to Pay reader on one device.
409 LIMIT_REACHEDactive_readers500 active readers in the environment.
409 RESOURCE_IN_USEArchiving a reader with a payment presented on it.
409 VERSION_CONFLICTA stale expected_version.
409 MERCHANT_NOT_READYCard payments aren't ready, when registering a smart reader, creating a connection session or simulating.
502 EXTERNAL_SERVICE_ERRORStripe didn't complete the request. Try again.
503 PAYMENT_PROCESSING_UNAVAILABLEPayment processing is temporarily unavailable for the merchant environment. Try again.
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_idstring

The 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.

connectivityobject

Smart 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_atstringRequired

When the reader was registered.

device_idstring

The 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_idstringRequired

The location the reader is at. Set at registration and never changed: to move a reader, archive it and register it again.

metadatamap of stringRequired

Your key-value pairs for the reader.

modelenum

The smart reader's model, read from the reader at registration. Smart readers only.

  • stripe_reader_s700
  • stripe_reader_s710
  • other
namestringRequired

Your label for the reader.

reader_idstringRequired

Unique identifier for the reader.

serial_numberstring

The smart reader's serial number, read from the reader at registration. Smart readers only.

statusenumRequired

Whether the reader can take payments.

  • active
  • archived
typeenumRequired

What 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_reader
  • tap_to_pay
updated_atstringRequired

When the reader last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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#

GET/v1/readers

Requires 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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 enum

Filter 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.

  • active
  • archived
location_idstring

Exact match on the reader's Flint location ID.

device_idstring

Exact match on the reader's Flint device ID.

typearray of enum

Exact 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_reader
  • tap_to_pay

Response · 200

A page of readers.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/readersIdempotent

Requires 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_idstring

The 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_idstringRequired

An active location with a complete US address (`line1`, `city`, `state`, `postal_code`, `country: US`). Stripe requires every reader to have one.

metadatamap of string

Caller-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.

namestringRequired

Your label for the reader. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.

registration_codestringRequired

The 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

Response · 201

The registered reader.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint 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 · 200

The reader.

Same response as Register a reader.

curl https://api.withflintpay.com/v1/readers/rdr_01KEZF7C007JA0G24M7SD6P46C \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The reader.

JSON
{
  "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#

PATCH/v1/readers/{reader_id}Idempotent

Requires 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_idstringRequired

Flint 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 null

The device the reader takes payments for. `null` clears it. Naming a device needs `accounts.devices.read` as well.

expected_versioninteger

Optional 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 null

Keys to set, merged into the reader's metadata. A key with an empty value is removed; `null` clears all metadata.

namestring

Your 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.

Response · 200

The reader.

Same response as Register a reader.

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#

DELETE/v1/readers/{reader_id}Idempotent

Requires 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_idstringRequired

Flint 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_versioninteger

Optional version most recently read. A stale value fails with `VERSION_CONFLICT` and the current version.

Response · 200

The reader.

Same response as Register a reader.

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#

POST/v1/readers/{reader_id}/connection-sessionsIdempotent

Requires 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_idstringRequired

Flint 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.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/readers/{reader_id}/simulateIdempotent

Requires 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_idstringRequired

Flint 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_brandenum

The brand of the test card to present. Defaults to `visa`. Declines present Visa test cards whatever brand you send.

  • visa
  • mastercard
  • amex
  • discover
outcomeenumRequired

The buyer's and issuer's decision.

  • approved
  • declined
  • insufficient_funds
tip_moneyobject

The tip the buyer picks, when the payment was sent with the tip screen on. USD only.

Response · 200

The reader.

Same response as Register a reader.

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?