Query Session Data

Read session information — such as the current amount, execution ID, or payment method configuration — from the active Payrails session at any point after createSession() completes.

Prerequisites

An active Payrails session (see Quick Start)

Query session data with `Payrails.query()`

Use Payrails.query() with a typed key from PayrailsQuery to read data from the active session:

val executionId: String? = Payrails.query(PayrailsQuery.ExecutionId)
val amount: PayrailsAmount? = Payrails.query(PayrailsQuery.Amount)

All keys return null if no session is active. No exception is thrown.

Available keys

`PayrailsQuery.ExecutionId`

The unique identifier for the active payment execution.

val executionId: String? = Payrails.query(PayrailsQuery.ExecutionId)

Use this to tell your backend which execution to act on — for example, before calling the Payrails lookup action to update the checkout amount.

`PayrailsQuery.HolderReference`

The holder reference for the active session.

val holderReference: String? = Payrails.query(PayrailsQuery.HolderReference)

`PayrailsQuery.Amount`

The current checkout amount as a PayrailsAmount.

val amount: PayrailsAmount? = Payrails.query(PayrailsQuery.Amount)
// amount?.value    → "54.99"
// amount?.currency → "EUR"

`PayrailsQuery.BinLookup`

The BIN lookup action link from the session config, as a PayrailsLink.

val binLookupLink: PayrailsLink? = Payrails.query(PayrailsQuery.BinLookup)
// binLookupLink?.href   → "https://..."
// binLookupLink?.method → "POST"

`PayrailsQuery.InstrumentDelete`

The stored instrument delete action link.

val deleteLink: PayrailsLink? = Payrails.query(PayrailsQuery.InstrumentDelete)

`PayrailsQuery.InstrumentUpdate`

The stored instrument update action link.

val updateLink: PayrailsLink? = Payrails.query(PayrailsQuery.InstrumentUpdate)

`PayrailsQuery.PaymentMethodConfig`

Configuration for a specific payment method, as a PayrailsPaymentMethodConfig.

val cardConfig: PayrailsPaymentMethodConfig? =
    Payrails.query(PayrailsQuery.PaymentMethodConfig("card"))

// cardConfig?.displayName           → "Credit or Debit Card"
// cardConfig?.flow                  → "inline"
// cardConfig?.supportsSaveInstrument → true

Pass the payment method code (e.g. "card", "paypal") as the parameter. Returns null if the code is not present in the session config.

`PayrailsQuery.PaymentMethodInstruments`

Stored instruments for a specific payment method.

val instruments: List<StoredInstrument>? =
    Payrails.query(PayrailsQuery.PaymentMethodInstruments("card"))

Returns null if the payment method code is unrecognised or has no stored instruments. Never returns an empty list — use null as the "nothing available" signal.

Example: passing the execution ID to your backend

Payrails.createSession(configuration) { result ->
    result.onSuccess {
        // Session is active — query data as needed
        val executionId = Payrails.query(PayrailsQuery.ExecutionId)

        myApiClient.updateExecutionAmount(
            executionId = executionId,
            amount = newTotal,
            currency = "EUR"
        )

        Payrails.update(PayrailsUpdate(amount = AmountUpdate(newTotal, "EUR")))
    }
}

Prerequisites