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.

API Key vs Publishable Key

Session endpoints accept either key type. The difference is the headers you send, where the key is safe to live, and whether the FX-rate override parameters are honored:

	Publishable Key	API Key
Intended use	Frontend / browser code	Server-to-server only
Headers	`X-Publishable-Key: pk_...`	`X-API-Key: ak_...` and `X-MID: {MERCHANT_UUID_OR_EXTERNAL_MID}`
Merchant selection	Encoded in the key — append `:{EXTERNAL_MID}` to target a sub-merchant	Taken from the required `X-MID` header
FX-rate overrides — `fiatFXRate`, `fiatFXRateExpirationSeconds`, `cryptoFXRates`	Not permitted	Permitted for merchants with the Can set FX rate permission

All other parameters behave identically for both key types.

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}",
    "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}"
    }
}'

The FX-rate overrides (fiatFXRate, fiatFXRateExpirationSeconds, cryptoFXRates) require the API Key — see API Key vs Publishable Key — and are only honored for merchants with the Can set FX rate permission.

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.
Name
successURL
Type
string
Description
Redirect URL used on a successful payment.
Name
cancelURL
Type
string
Description
Redirect URL used when the session is cancelled.
Name
failureURL
Type
string
Description
Redirect URL used on a failed payment.
Name
fiatFXRate
Type
number
Description
The fiat FX rate locked in for the session, when provided.
Name
recommendedNetwork
Type
string
Description
Network recommended to the customer at checkout, when provided.
Name
quoteID
Type
string
Description
Quote identifier associated with the session, when provided.

example response

{
    "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 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.
Name
successURL
Type
string
Description
Redirect URL used on a successful payment.
Name
cancelURL
Type
string
Description
Redirect URL used when the session is cancelled.
Name
failureURL
Type
string
Description
Redirect URL used on a failed payment.
Name
fxRate
Type
number
Description
Fiat FX rate locked in for the session, when provided.
Name
fxRateExpiration
Type
string
Description
Expiration date/time of the fiat FX rate.
Name
cryptoFXRateExpiration
Type
string
Description
Expiration date/time of the crypto FX rate.
Name
recommendedNetwork
Type
string
Description
Network recommended to the customer at checkout, when provided.
Name
quoteID
Type
string
Description
Quote identifier associated with the session, when provided.
Name
optionalFields
Type
object
Description
Prefilled customer details supplied when the session was created.

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": "",
    "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.

POST /session/{sessionID}/transaction

POST

/session/{sessionID}/transaction

curl --location '{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.

Cancel Session

PATCH /session/{sessionID}/cancel

PATCH

/session/{sessionID}/cancel

curl --location --request PATCH '{BASE_URL}/session/{SESSION_ID}/cancel' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}'

Returns 200 OK on success.