> Lydian Developer Documentation > Page: https://developer.lydian.com/api/session > Documentation index: https://developer.lydian.com/llms.txt # 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. Session endpoints accept either a **Publishable Key** (`X-Publishable-Key`) or an **API Key** (`X-Api-Key` with `X-MID`). The FX-rate override fields (`fiatFXRate`, `fiatFXRateExpirationSeconds`, `cryptoFXRates`) are honored only with an API Key, for merchants with the *Can set FX rate* permission. For how sessions and transactions relate, see [Sessions & Transactions](https://developer.lydian.com/concepts/sessions-and-transactions.md). For the end-to-end flow, see [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md). For status values, see [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md). ## Create Session **Endpoint:** `POST /session` ```bash curl --location '{API_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}", "successURL": "{SUCCESS_URL}", // OPTIONAL — redirect on success "cancelURL": "{CANCEL_URL}", // OPTIONAL — redirect on cancel "failureURL": "{FAILURE_URL}", // OPTIONAL — redirect on failure "fiatFXRate": {FX_RATE_IN_FLOAT}, // OPTIONAL (API Key only) "fiatFXRateExpirationSeconds": {SECONDS}, // OPTIONAL (API Key only, required with fiatFXRate) "cryptoFXRates": { "{ASSET}": {RATE_IN_FLOAT} }, // OPTIONAL (API Key only) "customFlatFeePerNetwork": { "{NETWORK}": {FEE} }, // OPTIONAL — mutually exclusive with customFeePercentagePerNetwork "customFeePercentagePerNetwork": { "{NETWORK}": {PCT} }, // OPTIONAL — mutually exclusive with customFlatFeePerNetwork "recommendedNetwork": "{CRYPTO_NETWORK}", // OPTIONAL — network preselected at checkout "quoteID": "{QUOTE_ID}", // OPTIONAL "optional": { // OPTIONAL — prefill customer details when KYC is required "firstName": "{FIRST_NAME}", "lastName": "{LAST_NAME}", "email": "{EMAIL}", "street1": "{STREET_1}", "street2": "{STREET_2}", "city": "{CITY}", "region": "{REGION}", "postalCode": "{POSTAL_CODE}", "country": "{COUNTRY_CODE}" } }' ``` > **Note:** The FX-rate overrides (`fiatFXRate`, `fiatFXRateExpirationSeconds`, `cryptoFXRates`) require the > API Key — see [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md) — and are only honored for > merchants with the *Can set FX rate* permission. ### Create Session Response - `sessionID` (string): Unique identifier for the session. - `qrData` (string): The data to generate QR code that can be scanned using mobile devices. - `successURL` (string): Redirect URL used on a successful payment. - `cancelURL` (string): Redirect URL used when the session is cancelled. - `failureURL` (string): Redirect URL used on a failed payment. - `fiatFXRate` (number): The fiat FX rate locked in for the session, when provided. - `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided. - `quoteID` (string): Quote identifier associated with the session, when provided. **example response** ```json { "sessionID": "009a3809-7328-4b6c-873b-089eff019f98", "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98", "successURL": "https://brimspire.com/checkout/success", "cancelURL": "https://brimspire.com/checkout/cancel", "failureURL": "https://brimspire.com/checkout/failure", "fiatFXRate": 1, "recommendedNetwork": "ethereum", "quoteID": "" } ``` ## 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](https://developer.lydian.com/api/transaction.md#get-transaction) api call. **Endpoint:** `GET /session/{sessionID}` ```bash curl --location --request GET '{API_BASE_URL}/session/{sessionID}' \ --header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \ --header 'Content-Type: application/json' ``` ### Get Session Response - `createdAt` (string): Created at date time of the session. - `updatedAt` (string): Updated at date time of the session. - `sessionID` (string): Unique identifier for the session. - `merchantID` (string): Unique identifier for the merchant. - `accountID` (string): Unique identifier for the account. - `descriptor` (string): Human‑readable descriptor for the session. - `externalMID` (string): External merchant ID (e.g., from a partner or POS). - `referenceNumber` (string): Merchant reference or order number for reconciliation. - `amount` (number): Payment amount. - `amountCurrency` (string): Currency code for the amount (ISO 4217, e.g., USD). - `qrData` (string): QR payload/URL the customer scans to choose asset/network and authorize the amount. - `status` (string): Current session status: `0` pending, `1` success. - `expiration` (string): Expiration date/time for the session. - `transactionID` (string): Associated transaction ID, set after the customer selects an asset and network. - `successURL` (string): Redirect URL used on a successful payment. - `cancelURL` (string): Redirect URL used when the session is cancelled. - `failureURL` (string): Redirect URL used on a failed payment. - `fxRate` (number): Fiat FX rate locked in for the session, when provided. - `fxRateExpiration` (string): Expiration date/time of the fiat FX rate. - `cryptoFXRateExpiration` (string): Expiration date/time of the crypto FX rate. - `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided. - `quoteID` (string): Quote identifier associated with the session, when provided. - `optionalFields` (object): Prefilled customer details supplied when the session was created. **example response** ```json { "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": "", "successURL": "https://brimspire.com/checkout/success", "cancelURL": "https://brimspire.com/checkout/cancel", "failureURL": "https://brimspire.com/checkout/failure", "fxRate": 1, "fxRateExpiration": "2025-11-18T17:15:24.26Z", "cryptoFXRateExpiration": "", "recommendedNetwork": "ethereum", "quoteID": "", "optionalFields": {} } ``` ## Create Session Transaction Once the customer selects an asset and network, create a Transaction linked to the Session. **Endpoint:** `POST /session/{sessionID}/transaction` ```bash curl --location '{API_BASE_URL}/session/{SESSION_ID}/transaction' \ --header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "asset": "{ASSET}", "network": "{CRYPTO_NETWORK}", "wallet": "{CUSTOMER_WALLET_ADDRESS}", "cryptoFXRateExpirationSeconds": {SECONDS}, // OPTIONAL "transactionExpirationSeconds": {SECONDS}, // OPTIONAL "quoteID": "{QUOTE_ID}" // OPTIONAL }' ``` The response is the same structure as the [Create Transaction Response](https://developer.lydian.com/api/transaction.md#create-transaction-response). ## Cancel Session **Endpoint:** `PATCH /session/{sessionID}/cancel` ```bash curl --location --request PATCH '{API_BASE_URL}/session/{SESSION_ID}/cancel' \ --header 'X-Publishable-Key: {PUBLISHABLE_KEY}' ``` Returns `200 OK` on success.