Session

A Session is a short‑lived, single‑purpose container that coordinates a payment from the customer to the merchant. It holds the context needed to complete a checkout - who is paying, how much, which asset and network is used (e.g., USDT on Ethereum), and how the result is reported - so clients and servers can safely move a payment from start to finish.

Typical lifecycle

  • Create: The merchant creates a Session and receives sessionID plus qrData (a URL the customer uses to pick an asset/network and authorize).
  • Initialize: The customer scans the QR or opens the link, selects an asset and network, and a Transaction is created and linked to the Session.
  • Authorize: The customer approves the payment (e.g., signs, confirms, or broadcasts for crypto).
  • Monitor: The merchant tracks progress via Get Session and Get Transaction. After asset/network selection, the Session includes a transactionID referencing the Transaction.
  • Complete: The Transaction settles to succeeded or ends as canceled/failed/expired.

Create Session

POST /session

POST
/session
curl --location '{BASE_URL}/session' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "fxRate": {FX_RATE_IN_FLOAT} // OPTIONAL
}'

fxRate can only be passed when creating session if the session is made using the API Key instead of the Publishable Key.

Create Session Response

  • Name
    sessionID
    Type
    string
    Description

    Unique identifier for the session.

  • Name
    qrData
    Type
    string
    Description

    The data to generate QR code that can be scanned using mobile devices.

example response

{
    "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
    "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98"
}

Get Session

It is possible to poll the session to retrieve its current status and the transaction ID once the customer has selected asset and network. The status of the transaction can be received via webhook or can be polled using Get Transaction api call.

GET /session/{sessionID}

GET
/session/{sessionID}
curl --location --request GET '{BASE_URL}/session/{sessionID}' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json'

Get Session Response

  • Name
    createdAt
    Type
    string
    Description

    Created at date time of the session.

  • Name
    updatedAt
    Type
    string
    Description

    Updated at date time of the session.

  • Name
    sessionID
    Type
    string
    Description

    Unique identifier for the session.

  • Name
    merchantID
    Type
    string
    Description

    Unique identifier for the merchant.

  • Name
    accountID
    Type
    string
    Description

    Unique identifier for the account.

  • Name
    descriptor
    Type
    string
    Description

    Human‑readable descriptor for the session.

  • Name
    externalMID
    Type
    string
    Description

    External merchant ID (e.g., from a partner or POS).

  • Name
    referenceNumber
    Type
    string
    Description

    Merchant reference or order number for reconciliation.

  • Name
    amount
    Type
    string
    Description

    Payment amount.

  • Name
    amountCurrency
    Type
    string
    Description

    Currency code for the amount (ISO 4217, e.g., USD).

  • Name
    qrData
    Type
    string
    Description

    QR payload/URL the customer scans to choose asset/network and authorize the amount.

  • Name
    status
    Type
    string
    Description

    Current session status (0 = pending).

  • Name
    expiration
    Type
    string
    Description

    Expiration date/time for the session.

  • Name
    transactionID
    Type
    string
    Description

    Associated transaction ID, set after the customer selects an asset and network.

example response

{
    "createdAt": "2025-11-18T17:00:24.26Z",
    "updatedAt": "2025-11-18T17:00:24.26Z",
    "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
    "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
    "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "descriptor": "Brimspire: Test!",
    "externalMID": "",
    "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
    "amount": 0.01,
    "amountCurrency": "USD",
    "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
    "status": 0,
    "expiration": "2025-11-18T17:15:24.26Z",
    "transactionID": ""
}