Payment Intents

A Payment Intent records the amount, asset, verified merchant destination, environment, and expiry that the observer uses to evaluate blockchain evidence.

Create contract

POST /api/v1/merchants/{merchant}/payment-intents requires JSON, payment_intents:write, and Idempotency-Key. Required fields are asset_public_id, destination_account_public_id, and amount. The implementation also accepts the legacy combined asset_destination form as an alternative pair. expires_in_seconds defaults to 900 and must be between 60 and 86400. merchant_reference and description are optional bounded text fields.

text

curl -X POST https://YOUR_API_HOST/api/v1/merchants/YOUR_MERCHANT_ID/payment-intents \
  -H 'Authorization: Bearer YOUR_LIVE_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-001' \
  --data '{"asset_public_id":"asset_YOUR_ASSET","destination_account_public_id":"wa_YOUR_ACCOUNT","amount":"12.50","merchant_reference":"order-001"}'

Returned object

The merchant serializer returns public_id, environment, status, amount {display, atomic}, asset {public_id, type, identifier, symbol, decimals}, network {key, chain_id}, destination {address}, created_at, expires_at, merchant_reference, description, cancelled_at, and payment_url. Detail responses additionally return observations.

State model

The implemented Payment Intent statuses are pending, processing, confirmed, expired, and cancelled. Creation starts pending. Verified observer progress can move it to processing; sufficient confirmations move it to confirmed. A pending intent is expired when its deadline is reached and expiry is evaluated. A pending unexpired intent can be cancelled. Reorganization handling can return processing or confirmed authority to pending when no non-reorg matched observation remains.

Observation and authority

The observer matches exact network, asset, destination, and atomic amount evidence. It records classifications including matched, underpaid, overpaid, late, ambiguous, additional_payment, and cancelled/expired outcomes where applicable. Confirmation is based on server-observed confirmations and required confirmations. Client input cannot set status, paid, confirmed, transaction_hash, or other authoritative payment fields.

Expiration and late payment

Expiration prevents a pending intent from remaining pending; the observer evaluates blockchain evidence against the intent deadline and can record a late/expired observation. The implementation does not document a merchant-side refund or automatic acceptance policy for late, underpaid, or overpaid evidence. Reconcile those event classifications using exact amounts and server state.

Cancel

POST /api/v1/merchants/{merchant}/payment-intents/{payment_intent}/cancel requires JSON and payment_intents:write. A pending unexpired intent becomes cancelled; an already expired pending intent becomes expired. The operation does not mark a payment successful.