The payment intent object

A payment to be taken on one of your terminals, and its lifecycle.

EndpointsCopy Anchor Link

• GET /v1/payment_intents: List payment intents
• POST /v1/payment_intents: Create a payment intent
• GET /v1/payment_intents/{id}: Retrieve a payment intent
• POST /v1/payment_intents/{id}/cancel: Cancel a payment intent

AttributesCopy Anchor Link

idstring

Unique identifier (pi_…).

objectstring

livemodeboolean

amountinteger

Amount to charge (USDC atoms).

currencystring

statusstring

One of: requires_payment_method, requires_action, processing, succeeded, canceled

requires_payment_method: waiting for a tap (again, after a failed attempt). requires_action: held for payer confirmation (next_action). processing: settlement sent, outcome pending — never retry. succeeded: settled (payment once indexed). canceled: nothing was or will be charged.

terminalstring

Terminal that takes the payment (tml_…).

order_idstring

descriptionstring | null

metadataobject

sourcestring

One of: api, terminal

Created by your server (api) or by the POS (terminal).

paymentstring | null

The settled payment (pay_…), once indexed.

tx_hashstring | null

Settlement transaction hash, once sent.

next_actionobject | null

Attributes of next_action

typestring

The payer must confirm the payment in the ZyloPay app.

reason_codestring | null

One of: AMOUNT_ABOVE_THRESHOLD, RISK_FLAGGED, FIRST_MERCHANT_PAYMENT, CUMULATIVE_LIMIT

Why confirmation is needed.

expires_atstring (date-time) | null

The confirmation request expires at this time.

last_payment_errorobject | null

Why the last attempt failed. Cleared on success.

Attributes of last_payment_error

codestring

Machine-readable reason (see the payment error codes in the API reference).

messagestring

cancellation_reasonstring | null

One of: requested_by_merchant, canceled_at_terminal, expired, step_up_denied, step_up_expired

canceled_atstring (date-time) | null

When the intent was canceled.

networkstring

One of: mainnet, testnet

expires_atstring (date-time)

The intent can no longer be paid after this time.

createdstring (date-time)

Creation time.

ExampleCopy Anchor Link

{
  "id": "pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60",
  "object": "payment_intent",
  "livemode": false,
  "amount": 2500000,
  "currency": "usdc",
  "status": "requires_payment_method",
  "terminal": "tml_ZP-4821-K",
  "order_id": "A7K2Q9XZ",
  "description": "Table 12",
  "metadata": {
    "pos_order": "48213"
  },
  "source": "api",
  "payment": null,
  "tx_hash": null,
  "next_action": null,
  "last_payment_error": null,
  "cancellation_reason": null,
  "canceled_at": null,
  "network": "testnet",
  "expires_at": "2026-09-28T14:04:11.000Z",
  "created": "2026-09-28T14:02:11.000Z"
}