Accept in-person terminal payments

Terminal payments collect a card-present payment on a specific Terminal using the same PaymentIntent as online payments. The PaymentIntent carries the amount and currency; the terminal request selects the device and the tender. Use a simulated Terminal for repeatable automated testing, then run the same payment flow on a physical Terminal.

Terminal payments require an Ionic tmr_… ID owned by the same Merchant and mode as the PaymentIntent. Every test account receives built-in simulated tmr_… IDs automatically; Ionic assigns physical Terminal IDs through the hardware provisioning flow. Send only the Ionic ID; never send a hardware serial number or device credential. See the Terminal object for its lifecycle, connection, and capability states.

Before you begin

You need:

a server-side Ionic secret key with payments:read and payments:write;
a built-in simulated test Terminal or an assigned physical Terminal that is ready for the requested tender;
the terminal’s Ionic ID, which starts with tmr_;
a unique Idempotency-Key for each mutating POST request; reuse a value only to retry the same request. The read-only batch refresh does not use one.

Keep keys on your backend. Your browser or POS client should call your server, and your server should call Ionic. If you are a Platform, send Ionic-Account: $CONNECTED_ACCOUNT_ID on every request in this guide. It selects the connected account that owns the PaymentIntent, Terminal, and resulting payment resources. A Merchant using its own Account key omits that header.

Request physical hardware

Create a provisioning request when a Merchant needs a physical Terminal. The request tracks hardware fulfillment and eventually points to the Ionic Terminal resource used by the payment API. The Terminal object guide explains how to interpret its independent setup, connection, and capability states.

Create or reuse a Location

Create the business Location where the Terminal will operate, or reuse an existing loc_… in the same Merchant and mode.

Request a Terminal

Use a secret key with terminals:write. Ionic selects and prepares the appropriate hardware; the request body contains only the Location, a merchant-facing label, and optional metadata.

curl https://api.ionicfi.com/v1/terminal_provisioning_requests \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: request-front-counter-terminal-1" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "'$LOCATION_ID'",
    "label": "Front counter",
    "metadata": {"lane": "1"}
  }'

Store the returned tprov_… as PROVISIONING_REQUEST_ID.

Track fulfillment

Retrieve the provisioning request until it becomes ready. If it becomes requires_action, show the additive required_actions values to the Merchant and continue retrieving the same request after they are complete.

curl https://api.ionicfi.com/v1/terminal_provisioning_requests/$PROVISIONING_REQUEST_ID \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID"

The request can move through requested, processing, requires_action, ready, failed, or canceled. A ready request has a non-null terminal_id.

Check Terminal readiness

Retrieve the assigned tmr_… and begin payments only when its lifecycle status and the requested payment capability are both ready.

curl https://api.ionicfi.com/v1/terminals/$TERMINAL_ID \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID"

List provisioning requests with GET /terminal_provisioning_requests and Terminal inventory with GET /terminals. Both collections are cursor-paginated and scoped to the authenticated Merchant and test or live mode.

Test without physical hardware

Every test account automatically owns two Ionic test Locations and three ready simulated Terminals. The fixture catalog is universal, but each Account gets its own loc_… and tmr_… IDs. This gives a Platform realistic Account and multi-location isolation without a separate provisioning integration.

`test_profile`	Default result
`approved`	Succeeds immediately.
`declined`	Declines immediately with `insufficient_funds`.
`delayed`	Returns `unknown`, then resolves to `succeeded` after five seconds.

The profile configures what the Terminal observes; it does not return a canned API response. Processing still creates and transitions normal Ionic PaymentIntent, Terminal Payment, Charge, PaymentMethod, Refund, batch, profile, item, idempotency, and webhook records. This makes status handling and resource relationships representative while keeping the card interaction deterministic.

List the Account's test Terminals

Use the Platform test key and connected account header. Select a Terminal by test_profile, not by a hard-coded universal ID—the IDs are unique to each Account.

curl https://api.ionicfi.com/v1/terminals \
  -H "Authorization: Bearer $IONIC_TEST_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID"

Store the selected tmr_… as TERMINAL_ID. List again for each connected Account; never reuse one Account’s Terminal ID for another Account.

Create a PaymentIntent

Create a fresh method-neutral PaymentIntent for the logical payment attempt, exactly as shown in the normal payment flow below.

Run the normal Terminal payment call

Call POST /terminals/{id}/process_payment_intent. No simulator-only request fields or helper call are needed, so this is the same integration you use with physical hardware.

Optionally override one PaymentIntent

Use the test helper only when a focused test needs a result other than the selected Terminal’s profile. This override wins for the exact Terminal and PaymentIntent once.

curl https://api.ionicfi.com/v1/test_helpers/terminals/$TERMINAL_ID/payment_scenarios \
  -H "Authorization: Bearer $IONIC_TEST_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: scenario-order-1042-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_01JEXAMPLEF9W6B3C2D7K4M8N",
    "outcome": "declined",
    "failure_code": "insufficient_funds"
  }'

Supported override outcomes are succeeded, voided, declined, failed, canceled, unknown, and dispatch_not_started. Declined and failed outcomes require a compatible failure_code.

An override persists until the next new command matching both IDs consumes it. Retrying that consumed command with the same idempotency key is safe; a different payment attempt cannot reuse the override. Only one unconsumed override can be armed for an exact Terminal and PaymentIntent. With no matching override, the Terminal uses its built-in test_profile. To test reconciliation, set outcome to unknown and include a final resolution_outcome plus resolution_delay_seconds from 1 through 86400. Ionic first returns the attempt with an unknown result; retrieve that same terminal_payment until the configured delay passes. Ionic reconciles the result automatically, usually within about one second of the configured time. Never submit a second Sale to resolve an unknown result. Cancellation uses the normal POST /terminal_payments/{id}/cancel endpoint. An unresolved unknown scenario without a configured final result becomes canceled. If the scenario already has a later resolution_outcome, that result remains authoritative, which lets you test a late-approval race after cancellation was requested.

Simulate current batches

Configure a durable current-batch situation, then call the same batch refresh endpoint used with a physical Terminal. Keep a profile’s reference stable and submit that profile again to replace its items for the next observation. Profiles omitted from an update remain unchanged, so an open batch cannot disappear. Up to 10 profiles with 1,000 items per profile can be retained.

curl https://api.ionicfi.com/v1/test_helpers/terminals/$TERMINAL_ID/batch_scenarios \
  -H "Authorization: Bearer $IONIC_TEST_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: batch-scenario-closeout-1" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [{
      "reference": "default",
      "items": [
        {
          "operation": "sale",
          "amount": 1250,
          "transaction_id": "sim_sale_1",
          "external_reference": "order_123",
          "sequence": "1"
        },
        {
          "operation": "refund",
          "amount": 250,
          "transaction_id": "sim_refund_1",
          "external_reference": "refund_123",
          "sequence": "2"
        }
      ]
    }]
  }'

curl https://api.ionicfi.com/v1/terminal_batches/refresh \
  -H "Authorization: Bearer $IONIC_TEST_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"terminal_id":"'$TERMINAL_ID'"}'

The refresh creates or updates normal terminal_batch, settlement-profile, and batch-item resources. With no configured batch scenario, a simulated Terminal reports an empty default profile instead of returning an unsupported operation. The simulator also supports the normal POST /refunds flow for a succeeded Terminal payment; refund resources and state transitions are handled by the same Ionic payment lifecycle. When refunds on the Terminal are on for your account, include terminal_id on a full refund before the batch settles to void the sale on the Terminal and print its receipt there; see Refunds on the Terminal. With automatic refund receipts on, a card-present refund that includes terminal_id prints its receipt on that Terminal; see Refund receipts.

Payment flow

Create a PaymentIntent

Create the same PaymentIntent used by other Ionic payment flows. Do not attach a payment_method, send a payment_token, or confirm it first. The intent must remain in requires_payment_method, use USD, and use automatic capture.

curl https://api.ionicfi.com/v1/payment_intents \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: pos-order-1042-intent" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 123,
    "currency": "usd",
    "capture_method": "automatic"
  }'

Process it on a terminal

Select the Ionic terminal ID in the route and pass the PaymentIntent ID in the request. The request has no Credit/Debit selector: the buyer presents an ordinary card and the eligible route is chosen automatically.

curl https://api.ionicfi.com/v1/terminals/$TERMINAL_ID/process_payment_intent \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: pos-order-1042-terminal-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_01JEXAMPLEF9W6B3C2D7K4M8N"
  }'

If PIN debit applies, the terminal prompts for PIN. The returned Terminal Payment reports payment_type as credit or debit once the tender type is confirmed.

Inspect the Terminal Payment

HTTP 202 means Ionic recorded the attempt and returned a terminal_payment; it does not by itself mean the payment was approved. Complete the order only when status is succeeded.

{
  "id": "tpr_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "terminal_payment",
  "merchant_id": "mer_01JEXAMPLE7A5P9D3F8K2N4Q",
  "terminal_id": "tmr_01JEXAMPLE8H2Q91P4T6K0M3N5",
  "payment_intent_id": "pi_01JEXAMPLEF9W6B3C2D7K4M8N",
  "charge_id": "ch_01JEXAMPLEC4V8B2N6M9K3P7",
  "livemode": false,
  "amount_requested": 123,
  "amount_approved": 123,
  "amount_remaining": 0,
  "currency": "usd",
  "payment_type": "credit",
  "status": "succeeded",
  "cancellation_requested": false,
  "cancellation_requested_at": null,
  "failure_code": null,
  "failure_message": null,
  "created_at": 1786939200,
  "updated_at": 1786939212
}

Handle every status

Status	Meaning	Safe next action
`succeeded`	Approved	Complete the sale.
`voided`	Authorized, then voided; no funds settle	Offer another tender if payment is still needed.
`declined`	Explicitly declined	Show `failure_message` and offer another tender.
`failed`	Known processing failure	Show `failure_message`, then retry with a new `Idempotency-Key` or use another tender.
`canceled`	Buyer canceled or the interaction timed out	If `cancellation_requested` is `true`, the PaymentIntent is canceled: create a new PaymentIntent if payment is still needed. Otherwise, retry the same PaymentIntent only after it returns to `requires_payment_method`, using a new `Idempotency-Key`.
`pending` / `in_progress`	The attempt is still running	Retrieve the same Terminal Payment until it reaches a final status.
`unknown`	The financial outcome is not yet confirmed	Retrieve the same attempt until it resolves; do not start another sale.

Declines and failures are returned as Terminal Payment resources with HTTP 200. Branch on status; treat failure_code as display detail, because new codes can appear without a new status value.

Failure codes

failure_code is nullable and appears only when Ionic has a known nonapproval. These are stable Ionic values; raw device responses are not returned.

Status and code	Meaning	Safe next action
`failed` / `dispatch_not_started`	Ionic rejected the request before payment processing began.	Correct the configuration or input, then retry deliberately.
`failed` / `processor_error`	Ionic confirmed a final processing failure.	Show the message, then retry deliberately or request another tender.
`failed` / `invalid_routing`	The Merchant’s payment setup is invalid.	Correct the payment setup before retrying.
`failed` / `pin_processing_error`	PIN processing failed.	Correct the Terminal configuration or request another tender.
`declined` / `do_not_honor`	The payment received a generic decline.	Request another tender.
`declined` / `insufficient_funds`	The payment was declined for insufficient funds.	Request another tender.
`declined` / `incorrect_pin`	The payment was declined for an incorrect PIN.	Allow another PIN attempt only when your payment flow permits it.
`declined` / `pin_attempts_exceeded`	The PIN retry limit was reached.	Request another tender; do not encourage another PIN attempt.
`declined` / `transaction_not_permitted`	This transaction is not permitted for the selected payment setup.	Request another tender or correct Merchant enablement.

New failure_code values are additive. Use status as the workflow boundary and fall back to failure_message when a code is unfamiliar.

Handle API errors

An API error means Ionic could not return a normal Terminal Payment response. Most errors below happen before a Sale is sent, but a timeout or persistence failure can leave the financial outcome uncertain.

HTTP and `error.code`	Payment submitted?	Safe next action
`400 INVALID_REQUEST`	Not sent	Correct the JSON or request shape.
`400 INVALID_DATA`	Not sent	Correct the identifier, currency, or requested tender.
`401 AUTHENTICATION_REQUIRED`, `API_KEY_INVALID`, `API_KEY_EXPIRED`, or `API_KEY_REVOKED`	Not sent	Correct authentication. Replace an expired or revoked key with an active one.
`403 INSUFFICIENT_PERMISSIONS`	Not sent	Grant the required `payments:read` or `payments:write` permission.
`403 MERCHANT_INACTIVE`	Not sent	Restore Merchant eligibility.
`403 LIVE_PAYMENTS_NOT_ENABLED`	Not sent	Complete live enablement or use test mode.
`404 PAYMENT_INTENT_NOT_FOUND`	Not sent	Correct the PaymentIntent ID, Merchant, or mode.
`404 TERMINAL_NOT_FOUND`	Not sent	Correct the Terminal ID, Merchant, mode, or assignment.
`409 TERMINAL_BUSY`	Not sent by this request	Wait for the active Terminal command to finish, then retry with a new idempotency key. A repeated key returns this same response.
`409 PAYMENT_PROCESSING`	Not sent by this request	Retrieve the existing attempt; do not start another Sale.
`422 INVALID_PAYMENT_STATE`	Not sent	Inspect and correct the PaymentIntent state or capture method.
`422 TERMINAL_NOT_READY`	Not sent	Finish Terminal setup or enable the requested capability.
`429 RATE_LIMIT_EXCEEDED`	Not sent	Honor `Retry-After` and retry the identical logical request with the same idempotency key.
`503 TERMINAL_OFFLINE`	Not sent	Restore connectivity, then retry deliberately.
`503 TERMINAL_CONNECTION_UNAVAILABLE`	Not sent	Verify the Terminal assignment, registration, and payment setup.
`503 SERVICE_UNAVAILABLE`	Not sent	Retry after the control-plane dependency recovers.
`504 GATEWAY_UNCERTAIN`	May have been sent	Do not create another Sale. Inspect the PaymentIntent and any known `tpr_…`, retain the idempotency key, and contact support.
`500 INTERNAL_ERROR`	Do not infer from HTTP alone	Inspect the PaymentIntent and any known `tpr_…`; do not blindly create another Sale.

A client timeout or disconnected HTTP socket is not evidence that the Terminal payment failed. Reuse an idempotency key only for the identical route and body, inspect the PaymentIntent, and retrieve any known tpr_… before considering a new attempt. Include the response X-Request-ID when contacting support.

Retrieve an unresolved attempt

If the result is pending, in_progress, or unknown, retrieve the same tpr_… resource. Do not process the PaymentIntent again to resolve a timeout.

curl https://api.ionicfi.com/v1/terminal_payments/$TERMINAL_PAYMENT_ID \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID"

Retrieval reads Ionic’s latest durable state; the GET request does not itself send a command to the Terminal. Ionic can update an unknown attempt when the original payment reaches a confirmed result, and the resulting state is available through this GET and terminal-payment webhooks. Retrieval never submits a new Sale, so poll it as often as your integration requires.

Request cancellation

Cancel only an active attempt, and treat cancellation as a request rather than a financial outcome.

curl -X POST \
  https://api.ionicfi.com/v1/terminal_payments/$TERMINAL_PAYMENT_ID/cancel \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: pos-order-1042-cancel-1"

cancellation_requested: true confirms that Ionic recorded the request. Continue inspecting status: the payment can still be approved after you request cancellation. Refund a late approval separately if you no longer want the payment.

Platforms and connected Merchants

An authorized Platform acting for a connected Merchant adds the delegation header to terminal requests whose API reference lists Ionic-Account:

Ionic-Account: mer_01JEXAMPLE7A5P9D3F8K2N4Q

The PaymentIntent, Terminal, Charge, and Terminal Payment must all belong to that account and use the same test or live mode. Identifiers that belong to another account or mode return 404. The header is route-specific, not a global account switch. Omit it for direct Merchant access and for any endpoint that does not document the header.

Test before going live

Use a test-mode key and the Account’s built-in simulated Terminals for automated coverage. Cover an approval, decline, failed dispatch, delayed unknown result, retried request with the same Idempotency-Key, cancellation, refund, a batch refresh, and retrieval of the resulting resources. Then run acceptance testing on an Ionic-assigned physical test Terminal to validate the device, store network, PIN entry, and live account setup before enabling production hardware.

The simulator proves your integration and state handling; it does not certify a physical reader, PIN entry, receipt behavior, or store network. Keep physical-terminal acceptance testing as a separate release gate.

What’s next

Refund a completed payment

Send terminal_id with a refund to run it as a card-present refund on a terminal.

Read the Terminal object

Interpret a Terminal’s setup, connection, and capability states.

Run it for connected accounts

Process terminal payments for the connected accounts a platform serves.

Payments

Manage payments

Accept in-person terminal payments

Before you begin

Request physical hardware

Test without physical hardware

Simulate current batches

Payment flow

Handle every status

Failure codes

Handle API errors

Retrieve an unresolved attempt

Request cancellation

Platforms and connected Merchants

Test before going live

What’s next

Refund a completed payment

Read the Terminal object

Run it for connected accounts

​Before you begin

​Request physical hardware

​Test without physical hardware

​Simulate current batches

​Payment flow

​Handle every status

​Failure codes

​Handle API errors

​Retrieve an unresolved attempt

​Request cancellation

​Platforms and connected Merchants

​Test before going live

​What’s next

Refund a completed payment

Read the Terminal object

Run it for connected accounts

Before you begin

Request physical hardware

Test without physical hardware

Simulate current batches

Payment flow

Handle every status

Failure codes

Handle API errors

Retrieve an unresolved attempt

Request cancellation

Platforms and connected Merchants

Test before going live

What’s next