Payment Lifecycle & Statuses

A payment moves through a series of states, reported as a numeric status. Your application logic should branch on these documented numeric status values — not on any display text, which can change.

Session status

A Session tracks the checkout at a high level, so its status is simple: it stays pending until the payment completes.

statusMeaning
0Pending — the session has been created; the customer has not completed payment.
1Success — the payment associated with the session completed successfully.

Transaction status

A Transaction carries the detailed outcome and has a richer set of states. 0 and -3 are in progress, and 1 is the single success state. It helps to think of them in groups rather than as a flat list.

In progress

statusMeaning
0Pending — payment initiated, awaiting completion.
-3KYC Verification Pending — awaiting customer identity verification before the payment can proceed.

Successful

statusMeaning
1Success — fully paid and confirmed on-chain.

Cancelled or timed out

statusMeaning
-2Cancelled
-8Payment Timeout
-9API Cancelled
-4Forfeit

Fraud & compliance

statusMeaning
-1Fraud
-7Fraud Declined
-6Fraud Refunded
-5Fraud Refund Held

The four fraud/compliance states and -4 Forfeit are terminal fraud- or compliance-related outcomes. The precise trigger that distinguishes each one is not fully specified in the current documentation — treat them as terminal "did not complete normally" states and confirm the exact semantics with the API or Lydian support before building logic that depends on the specific value.

Working with statuses

  • Branch on the number, not the label. Display text may be localized or reworded; the numeric value is the contract.
  • Only 1 means paid. A refund requires a transaction in the success state (1).
  • Don't assume every negative value is final. Negative values include an in-progress state (-3 KYC Verification Pending) as well as payments that did not complete — cancelled, timed out, or stopped for fraud/compliance reasons.