Confirm a payment intent with an AI agent's token

Pay a requires_payment_method intent from your server with a single-use token from the payer's AI agent (agent_token).

POST/v1/payment_intents/{id}/confirmscope payments:write

The agent mints the token for your merchant and this amount with its ZyloPay agent key; pass it on unchanged. Only AI agent tokens are accepted: a pass's NFC ID or wallet token is refused. The answer is the intent: succeeded or processing when paid, requires_action when the payer must approve it in the ZyloPay app (the agent's settings may ask for every payment), or requires_payment_method with last_payment_error when declined (nothing was charged). Settles at most once: repeat the call with the same Idempotency-Key to get the same answer, and follow processing and requires_action with webhooks or retrieve, never by confirming again. Use a terminal that no POS device picks intents up from.

Path parameters

idstringrequired: Payment intent ID (pi_…).

Body parameters

agent_tokenstringrequired: A single-use payment token from the payer's AI agent (zpt_…). The agent mints it for your merchant and this amount with its ZyloPay agent key and hands it to you (for example in an x402 X-PAYMENT header). Only AI agent tokens are accepted: never a pass's NFC ID or wallet token.

Headers

ZyloPay-Versionstring: Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.
Idempotency-Keystringrequired: Required. A unique key per operation (a UUID v4). Retrying with the same key and body returns the first response (Idempotent-Replayed: true); a different body is refused with 409 idempotency_key_reused. Keys are kept 48 hours.

Returns

HTTP 200 with the payment intent object.

Errors

Status	Meaning
`400`	Invalid request (`invalid_request_error` / `idempotency_error`).
`401`	Missing, invalid, expired or revoked API key (`authentication_error`).
`403`	The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).
`409`	Conflict: idempotency key reused or in progress, or the object is in the wrong state.
`429`	Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.
`500`	Internal error (`api_error`). Retry with the same `Idempotency-Key`.

Branch on error.code. Every code is listed in error codes.

Example request

curl https://zylopay-api.fly.dev/api/v1/payment_intents/pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60/confirm \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_token": "zpt_7c1e4a9b2d8f3e6a0b5c9d2e7f1a4b8c3d6e9f2a5b8c1d4e7f0a3b6c9d2e5f8a"
  }'

Example response

{
  "id": "pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60",
  "object": "payment_intent",
  "livemode": false,
  "amount": 2500000,
  "currency": "usdc",
  "status": "succeeded",
  "terminal": "tml_ZP-4821-K",
  "order_id": "A7K2Q9XZ",
  "description": "Table 12",
  "metadata": {
    "pos_order": "48213"
  },
  "source": "api",
  "payment": "pay_1042",
  "tx_hash": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
  "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"
}

Confirm a payment intent with an AI agent's token

Path parametersCopy Anchor Link

Body parametersCopy Anchor Link

HeadersCopy Anchor Link

ReturnsCopy Anchor Link

ErrorsCopy Anchor Link

Example requestCopy Anchor Link

Example responseCopy Anchor Link