Bookings & payments

Last updated  Nov 17, 2026

When the assistant offers a booking, the user taps Confirm on its card. From SDK 2.2.0 you choose who completes it: Voqal, through your backend, or your own app, with its own booking API. Both modes are opt-in. Leave the settings alone and 2.2.0 behaves exactly like 2.1.0.

Available on iOS, Android and Flutter 2.2.0. React Native stays on 2.1.0 and books through Voqal only.

Who books it

ModebookingModeWhat happens
Voqal books itserverThe default. Voqal calls your backend's booking tool once the user confirms. You write nothing, or optionally an Add-funds callback for a short wallet.
Your app books ithostVoqal hands the confirmed booking to your app, which books it with its own API and returns the outcome. A booking handler is required.

The mode is a setup-time setting, bookingMode. Only confirm cards that carry booking details are handed to your app. Every other confirm card, such as a payment link, still runs through Voqal in both modes.

What your app receives

A booking confirm card carries a details object next to the rows the user reads. The SDK decodes it into VoqalBookingDetails: the venue, the court or resource, the date and times, the duration, the price, deposit and currency, and confirmId. Every field is optional, and the full object is also kept as-is (dictionary on iOS, fields on Android and Flutter), including any ids your backend needs.

confirm widget
{  "type": "confirm",  "title": "Create booking",  "rows": [    [      "Venue",      "Riverside Club"    ]  ],  "details": {    "action": "create_booking",    "venue": "Riverside Club",    "court": "Court B",    "date": "2026-11-17",    "start": "21:00",    "end": "22:00",    "duration_minutes": 60,    "price": null,    "deposit": 30,    "currency": "USD",    "confirm_id": "3f0c9a52-6d1e-4b7a-9c35-8e2f1a7d4b60"  }}
  • Times are venue-local wall-clock. date is yyyy-MM-dd; start and end are HH:mm. Don’t convert them from the phone’s time zone.
  • Price, deposit and currency can be nullwhen your backend didn’t return them.

Voqal books it

This is the default and needs no code. When the user confirms, Voqal calls your backend’s booking tool and shows the result. If your backend turns the booking down because the user’s wallet is short, the assistant shows an Add-funds card instead of an error. It states the amount due and has one button that hands the user back to your app.

The Add-funds card

  • addFundsButtonTitlesets the button’s label, in English and Arabic. The SDK shows the one that matches the conversation. The default is “Add funds”.
  • Tapping the button calls your Add-funds callback with the shortfall’s amount and currency. Either can be null when it isn’t known. Open your wallet or top-up screen there.
  • With dismissOnAddFunds (the default), the assistant closes first and the callback fires after, so the screen you open stays in front.
  • Set the callback whenever a booking can go through Voqal. Without it, the button closes the assistant and nothing else happens.
AppVoqalDelegate.swift
extension AppVoqalDelegate: VoqalAddFundsHandler {    func voqalDidTapAddFunds(amount: Double?, currency: String?) {        // With dismissOnAddFunds the assistant has already closed.        router.openWallet(prefill: amount, currency: currency)    }}

Your app books it

Set bookingModeto host and implement the booking handler. When the user taps Confirm, the SDK calls your handler with the booking’s details and waits. You book it with your own API and return a VoqalBookingResult. The SDK reports that result to Voqal, and the assistant carries on with it in context (“You’re booked, reference 8812”).

Host mode requires the handler. Voqal never books on your behalf in this mode, and there is no fallback. A missing handler, or a handler that returns nothing, is reported as a failed booking. That is a bug to fix in your app.

iOS

Adopt VoqalBookingHandler and VoqalAddFundsHandler on the delegate you already pass to the SDK. VocalButtonDelegate itself is unchanged from 2.1.0. Both callbacks run on the main actor.

AppDelegate.swift
configuration.bookingMode = .host              // default .server: Voqal books itconfiguration.addFundsButtonTitle =    VoqalLocalizedText(en: "Top up wallet", ar: "اشحن المحفظة")configuration.dismissOnAddFunds = true         // close the assistant firstconfiguration.hostActionTimeoutSeconds = 300   // then report unknown
AppVoqalDelegate.swift
extension AppVoqalDelegate: VoqalBookingHandler {    @MainActor    func voqalDidConfirmBooking(_ details: VoqalBookingDetails)        async throws -> VoqalBookingResult {        let response = try await bookingsAPI.create(            idempotencyKey: details.confirmId,    // one card never books twice            date: details.date,                   // "2026-11-17", venue-local            start: details.start,                 // "21:00"            end: details.end,            fields: details.dictionary            // every field the card carried        )        guard response.isBooked else {            return VoqalBookingResult(status: .failed,                                      message: response.message, code: response.errorCode)        }        return VoqalBookingResult(status: .success,                                  message: "Booked. Ref \(response.reference)",                                  reference: response.reference)    }}

Android

onBookingConfirmed and onAddFundsTapped are new optional members of VoqalDelegate. The booking callback is a suspend function that runs on the main thread.

App.kt
VoqalConfiguration(    requestId = "prod-yourapp",    apiKey = "pk_live_…",    bookingMode = VoqalBookingMode.HOST,      // default SERVER: Voqal books it    addFundsButtonTitle = VoqalLocalizedText(        english = "Top up wallet",        arabic = "اشحن المحفظة",    ),    dismissOnAddFunds = true,    hostActionTimeoutSeconds = 300,)
VoqalCredentials.kt
class VoqalCredentials(    private val authStore: AuthStore,    private val bookings: BookingsApi,) : VoqalDelegate {    override fun getToken(): String = authStore.currentToken    // Called on the main thread; switch dispatchers for network work.    override suspend fun onBookingConfirmed(        details: VoqalBookingDetails,    ): VoqalBookingResult =        withContext(Dispatchers.IO) {            val response = bookings.create(                idempotencyKey = details.confirmId,   // one card never books twice                date = details.date,                start = details.start,                end = details.end,                fields = details.fields,            )            if (response.isBooked) {                VoqalBookingResult(                    VoqalBookingStatus.SUCCESS,                    message = "Booked. Ref ${response.reference}",                    reference = response.reference,                )            } else {                VoqalBookingResult(                    VoqalBookingStatus.FAILED,                    message = response.message,                    code = response.errorCode,                )            }        }    // The assistant has already closed. Don't capture an Activity here.    override fun onAddFundsTapped(amount: Double?, currency: String?) {        navigator.openWallet(amount, currency)    }    override fun onError(error: Throwable) {        if (error is VoqalOutcomeReportError) {            bookings.reconcile(error.confirmId, error.outcomeStatus)        }    }}

Flutter

The plugin exposes the same three callbacks on Voqal. They are process-global, so clear them in dispose() if they capture widget state.

main.dart
await voqal.setup(const VoqalConfig(  apiKey: 'pk_live_…',  bookingMode: VoqalBookingMode.host,   // default .server: Voqal books it  addFundsButtonTitle:      VoqalLocalizedText(en: 'Top up wallet', ar: 'اشحن المحفظة'),  dismissOnAddFunds: true,  hostActionTimeoutSeconds: 300,));voqal.onBookingConfirmed = (VoqalBookingDetails booking) async {  final response = await bookingsApi.create(    idempotencyKey: booking.confirmId,            // one card never books twice    date: booking.date,    start: booking.start,    end: booking.end,    fields: booking.fields,  );  if (response.isBooked) {    return VoqalBookingResult(status: VoqalBookingStatus.success,        message: 'Booked. Ref ${response.reference}', reference: response.reference);  }  return VoqalBookingResult(status: VoqalBookingStatus.failed,      message: response.message, code: response.errorCode);};// The assistant has already closed, so push from your own navigator.voqal.onAddFundsTapped = (double? amount, String? currency) {  navigatorKey.currentState?.pushNamed('/wallet', arguments: amount);};voqal.onError = (VoqalError e) {  if (e.type == VoqalErrorType.outcomeReport) {    bookingsApi.reconcile(confirmId: e.confirmId, reported: e.outcomeStatus);  }};

The confirm id

Every booking card carries its own confirmId, a unique id that can be used once. Pass it to your booking API as the idempotency key. Then a repeated call for the same card, say after a timeout or a retry, can never book twice. Voqal sends the same id back with the outcome, so a result is always tied to the card the user confirmed. A card can be settled once, and only within two hours of being shown.

Outcomes, failures & timeouts

Whatever your handler does, the user gets an answer. Here is what each case reports and what the user sees:

Your handlerReported asWhat the user sees
Returns successsuccessA confirmation, with your message and reference.
Returns failedfailed, with your codeYour message, shown as written (trimmed, up to 300 characters).
Throwsfailed, host_errorThat the booking didn't go through.
Is missing or returns nothingfailed, host_no_resultThat the booking didn't go through.
Times outunknown, host_timeoutThat the booking couldn't be confirmed, and to check their bookings.
  • A timeout is unknown, not failed. Your booking may still be going through, so the assistant never claims either way. It asks the user to check their bookings. The default wait is 300 seconds, because the user may be topping up meanwhile. Values are clamped between 1 second and 1 hour.
  • Expect to be abandoned.After the timeout the SDK stops waiting. On iOS and Android it cancels your task, so stop work when it’s cancelled. A Dart future can’t be cancelled, so a Flutter handler keeps running. Either way a late result is logged and never shown, so don’t open UI from it.
  • Write the message for the user. On failure your message is shown as it is, so write it in plain language. English or Arabic both work; send whichever your backend has.

Reconciling a lost report

Your app can make the booking and Voqal can still fail to record it, for example when the network drops. The booking stands, but the assistant doesn’t know about it. The SDK tells you through its error callback with a VoqalOutcomeReportError carrying the outcome you reported, a reason code and the confirmId. Look up your own booking by that id.

PlatformWhere it arrives
iOSvoqalButton(didFailWith:)
AndroidVoqalDelegate.onError
FlutterVoqal.onError, type VoqalErrorType.outcomeReport

Errors carry codes, ids and type names only, never user data.

Turning it on

Two pieces are set up on your assistant, not in the SDK. Tell us before you ship and we turn them on:

  • Host mode.Until it’s on for your assistant, Voqal rejects the outcome your app reports. The user would see an error even though your app made the booking.
  • The Add-funds card. Tell us which error codes your backend returns for a short wallet, so those show the card rather than a failure.

Email uswith your publishable key and we’ll set it up.

Reference

SettingDefaultDescription
bookingModeserverWho completes a confirmed booking: Voqal (server) or your app (host).
addFundsButtonTitle“Add funds”The Add-funds button's label, in English and Arabic.
dismissOnAddFundstrueClose the assistant before the Add-funds callback fires.
hostActionTimeoutSeconds300How long to wait for your handler before reporting unknown.
PlatformCallbacks
iOSvoqalDidConfirmBooking(_:) from VoqalBookingHandler, and voqalDidTapAddFunds from VoqalAddFundsHandler. Adopt both on your delegate.
AndroidonBookingConfirmed and onAddFundsTapped on VoqalDelegate
FlutterVoqal.onBookingConfirmed and Voqal.onAddFundsTapped

Setting names are the same on every platform. Android uses upper-case enum values, such as VoqalBookingMode.HOST. See Configuration for every other setting.

© 2026 VoqalVoqal SDK & engine documentation