Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Merchant secret key, or a Platform secret key with delegation.

Headers

​
Ionic-Account
string

Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.

Pattern: ^mer_
​
Idempotency-Key
string
required

Unique checkout-attempt key. Reuse the same value only when retrying the same request body and route.

Required string length: 1 - 255

Path Parameters

​
id
string
required

Physical Terminal selected by the POS for this checkout.

Pattern: ^tmr_

Body

application/json
​
payment_intent_id
string
required

Existing PaymentIntent in requires_payment_method.

Pattern: ^pi_
Example:

"pi_01JEXAMPLEF9W6B3C2D7K4M8N"

​
payment_type
enum<string>
required

Tender behavior requested from the Terminal. This is not a PaymentMethod type. debit invokes the terminal's PIN-debit path and requires a terminal whose debit_pin capability is ready.

Available options:
credit,
debit

Response

The Terminal Payment. Inspect status; only succeeded means the payment was approved.

​
id
string
required
Pattern: ^tpr_
​
object
enum<string>
required
Available options:
terminal_payment
​
merchant_id
string
required
Pattern: ^mer_
​
terminal_id
string
required
Pattern: ^tmr_
​
payment_intent_id
string
required
Pattern: ^pi_
​
charge_id
string | null
required

Present only after an approved attempt creates a Charge.

Pattern: ^ch_
​
livemode
boolean
required
​
amount_requested
integer<int64>
required

PaymentIntent amount in minor currency units.

Required range: x >= 1
​
amount_approved
integer<int64>
required
Required range: x >= 0
​
amount_remaining
integer<int64>
required
Required range: x >= 0
​
currency
enum<string>
required
Available options:
usd
​
payment_type
enum<string>
required

Tender type used for this attempt.

Available options:
credit,
debit,
ebt_food,
ebt_cash
​
status
enum<string>
required

succeeded: approved; complete the sale. voided: authorized and then voided; do not complete the sale. declined: explicitly declined; request another tender. canceled: interaction canceled or timed out. When cancellation_requested is true, the PaymentIntent is also canceled; create a new PaymentIntent if payment is still needed. Otherwise, retry this PaymentIntent only after it returns to requires_payment_method, using a new Idempotency-Key. failed: known processing failure; show the failure before a new attempt. unknown: both the command response and the immediate read-only status check were inconclusive; do not process the order again. pending or in_progress: retrieve this Terminal Payment until final.

Available options:
pending,
in_progress,
unknown,
succeeded,
voided,
declined,
failed,
canceled
​
cancellation_requested
boolean
required

Whether cancellation was requested. This alone does not mean the payment was canceled.

​
cancellation_requested_at
integer<int64> | null
required
​
failure_code
string | null
required

Stable Ionic detail for a known non-approval. This is intentionally an open string: branch on status, use recognized values for richer POS guidance, and fall back to failure_message for an unfamiliar value. Raw device responses are not returned.

Currently emitted values:

  • dispatch_not_started: Ionic rejected the command before payment processing began.
  • processor_error: Ionic confirmed a final processing failure.
  • invalid_routing: the Merchant's payment setup is invalid.
  • pin_processing_error: PIN processing failed.
  • do_not_honor: the payment received a generic decline.
  • insufficient_funds: the payment was declined for insufficient funds.
  • incorrect_pin: the payment was declined for an incorrect PIN.
  • pin_attempts_exceeded: the PIN retry limit was reached.
  • transaction_not_permitted: the transaction is not permitted for the selected payment setup.
​
failure_message
string | null
required

Safe Ionic explanation suitable for a POS.

​
created_at
integer<int64>
required
​
updated_at
integer<int64>
required