Sessions & Transactions
A payment involves two related objects: a Session and a Transaction. They are easy to confuse, so it's worth being precise about what each represents.
Session
A Session is the checkout context for one payment. Your backend creates it before the customer completes checkout, specifying the amount and currency to collect. Creating a session returns:
- a
sessionID— the identifier for this checkout, and - a
qrDataURL — the Lydian-hosted checkout link the customer uses to pay.
A session also records which account and merchant it belongs to (accountID, merchantID, externalMID). Its status is intentionally simple:
status | Meaning |
|---|---|
0 | Pending |
1 | Success |
See the Sessions API for the full field list.
Transaction
A Transaction is the actual payment. It is created during checkout, once the customer selects how they want to pay (their asset and network). The transaction carries the on-chain details — asset, network, address, amounts, and confirmation — and has its own richer status lifecycle (for example pending, succeeded, cancelled, or a fraud/compliance outcome). See Payment Lifecycle & Statuses for the full set of values and the Transactions API for the fields.
How they relate
The session is the context the customer enters; the transaction is the payment that results from it. When the customer selects an asset and network, Lydian creates a Transaction and links it to the session — the session then exposes a transactionID you can use to follow the payment.
So the two objects answer different questions:
- Session — "what checkout did I start, and where does the customer pay?"
- Transaction — "what actually got paid, and what state is it in?"
Track a payment to completion by polling the session (which surfaces the transactionID and overall result) or the transaction directly, or by receiving a webhook.