How to Gate Payment Authorization

Use onRequestStart when your backend must approve a payment before Payrails authorizes it—revalidating a voucher, confirming a wallet balance, or checking loyalty points the moment the customer commits. For why the gate sits where it does, see SDK Concepts.

Steps

Step 1: Register the handler

Supply it on Options, beside redirectSessionLifecycle:

val configuration = Configuration(
    initData = initData,
    option = Options(
        onRequestStart = { context ->
            if (myBackend.validatePrePayment(context.executionId)) {
                RequestStartDecision.Proceed
            } else {
                RequestStartDecision.Refuse("Your basket is no longer valid.")
            }
        }
    )
)

The handler is a suspend function, so call your backend directly—no callback plumbing.

Step 2: Gate only the methods you care about

The handler fires for every payment method on the session. Return Proceed on the branches you are not gating—otherwise the handler blocks those payments too:

onRequestStart = { context ->
    if (context.paymentMethodCode != "payPal") {
        RequestStartDecision.Proceed          // don't gate anything else
    } else {
        val check = myBackend.validatePrePayment(context.executionId)
        if (check.ok) RequestStartDecision.Proceed else RequestStartDecision.Refuse(check.reason)
    }
}

Step 3: Handle an unreachable backend

The SDK waits 10 seconds, then blocks the payment. A handler that throws blocks it too. Both are deliberate—a gate that fails open is not a gate—but they mean your error path is a decision, so make it explicit:

onRequestStart = { context ->
    try {
        val check = myBackend.validatePrePayment(context.executionId)
        if (check.ok) RequestStartDecision.Proceed else RequestStartDecision.Refuse(check.reason)
    } catch (e: IOException) {
        // Your service is unreachable. Refuse blocks the payment; Proceed accepts the risk of an
        // unvalidated basket. Letting the exception escape also refuses it, but without a message.
        RequestStartDecision.Refuse("We couldn't confirm your basket. Please try again.")
    }
}

The handler runs on a background dispatcher, so a suspending network call needs no extra withContext. Switch context only to update the UI:

onRequestStart = { context ->
    val allowed = myBackend.validatePrePayment(context.executionId)   // already off the main thread
    if (!allowed) {
        withContext(Dispatchers.Main) { showBasketExpiredDialog() }
    }
    allowed
}

One caveat about the 10-second bound: it can only interrupt a handler that suspends. A handler that blocks its thread—a synchronous HTTP client, Thread.sleep, a blocking database read—runs to completion no matter how long it takes, because coroutine cancellation is cooperative. Use a suspending client, or wrap a blocking one so cancellation reaches it.

Step 4: Handle the block in your delegate

A blocked payment arrives as onAuthorizeFailed with failure.code == VALIDATION_FAILED. Separate it from a decline — nothing reached the backend, so there is no failed payment to explain:

override fun onAuthorizeFailed(button: PayPalButton, failure: AuthorizationFailure) {
    when (failure.code) {
        AuthorizationFailureReason.VALIDATION_FAILED ->
            // Your own check refused it. failure.message is the reason you passed to
            // Refuse(message), so you can show it directly instead of mapping a code.
            showBasketChangedMessage(failure.message)
        AuthorizationFailureReason.AUTHORIZATION_ERROR ->
            showDeclineMessage()            // the issuer refused it
        else ->
            showGenericError(failure.message)
    }
}

This is why Refuse carries a message rather than the handler returning a bare false: the reason travels with the refusal to the one place you already read failure text from, instead of stashing it somewhere and correlating it back by executionId.

Google Pay

The button opens Google Pay’s sheet, not the SDK core, so the SDK consults the gate the moment the customer taps—before the sheet appears. A refusal means they never see it. Every other method reaches the gate through Session.authorize, which also runs before any provider UI. The practical consequence: for Google Pay, the SDK calls your handler before the customer chooses a card. A basket-only check—a voucher, a wallet balance, loyalty points—works fine here. It cannot depend on which card they picked.

Reference

Context field	Type	Notes
`executionId`	`String?`	The Payrails execution, when known
`paymentMethodCode`	`String`	`"card"`, `"payPal"`, `"googlePay"`, …
`action`	`Action`	`AUTHORIZE` in this version

Handler behavior	Result
returns `Proceed`	Authorization proceeds
returns `Refuse(message)`	Stopped as `VALIDATION_FAILED`, carrying your `message`
returns `Refuse()`	Stopped as `VALIDATION_FAILED` with a generic description
no answer within 10 seconds	Stopped with a generic description, warning logged
throws	Stopped with a generic description, warning logged

Only a deliberate Refuse(message) reaches failure.message. The timeout and throw cases log their diagnostic instead of surfacing it—both describe an integration fault rather than anything phrased for a customer, and an exception string can carry internals. Blocking never sends an authorization request, never presents provider UI, and returns the element to ButtonState.ENABLED. onRequestStart is a Kotlin-only API, like onSessionExpired: suspend functions are not implementable from Java.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

How to Gate Payment Authorization

Steps

Step 1: Register the handler

Step 2: Gate only the methods you care about

Step 3: Handle an unreachable backend

Step 4: Handle the block in your delegate

Google Pay

Reference

See Also

​Steps

​Step 1: Register the handler

​Step 2: Gate only the methods you care about

​Step 3: Handle an unreachable backend

​Step 4: Handle the block in your delegate

​Google Pay

​Reference

​See Also

Steps

Step 1: Register the handler

Step 2: Gate only the methods you care about

Step 3: Handle an unreachable backend

Step 4: Handle the block in your delegate

Google Pay

Reference

See Also