Android SDK API reference
Look up checkout delegates, results, callbacks, and shipping types in the Bolt Android SDK.
This reference matches com.bolt:checkout version 0.10.2, available on Maven Central.
BoltCheckoutDelegate
Implement this delegate when using getBoltCheckoutActivityResultLauncher(). All delegate types are in the com.bolt.checkout.intl package.
Terminal callbacks
| Callback | Parameters | Description |
|---|---|---|
onCheckoutSuccess(result) | result: BoltCheckoutResult | Checkout completed. Use result.reference, result.cart?.orderReference, and result.merchantOrderNumber for client-side display, then reconcile the order on your backend. |
onCheckoutError(errorReason) | errorReason: String | Checkout failed and returned an error string. |
onCheckoutCancel() | (none) | The shopper dismissed checkout. |
Lifecycle callbacks
These default to no-op and are useful for analytics:
| Callback | Parameters | Description |
|---|---|---|
onCheckoutStart() | (none) | Checkout flow started and the UI is presented. |
onCartLoaded() | (none) | The cart loaded in checkout. |
onEmailEnter(email) | email: String | The shopper entered and validated an email address. |
onShippingDetailsComplete(address) | address: BoltShippingAddress | The shopper submitted contact and shipping details. |
onShippingOptionsComplete() | (none) | The shopper selected a shipping option and moved to payment. |
onPaymentSubmit(customFields) | customFields: Map<String, BoltCustomFieldValue> | The shopper tapped the pay button. The map holds merchant-configured custom field values keyed by field ID, and is empty when checkout sent none. |
onNotify(event) | event: BoltCallbackEvent | Checkout emitted a notification event, such as an error banner. |
onCheckoutBack(nextStep) | nextStep: String? | The shopper navigated backward. Fires only when the back button is enabled for your division. nextStep can be null. |
onCheckoutGoToStep(nextStep) | nextStep: String | The shopper moved forward to a checkout step. |
onCheckoutLogout(initialStep) | initialStep: String | The shopper logged out inside checkout. initialStep is the step checkout returns to. |
onPlatformLoginSuccess(silentLogin) | silentLogin: BoltSilentLogin | The shopper signed in to Bolt during checkout. Call silentLogin.authorize { result -> } to get an SSO authorization code without showing a login screen. Nothing runs if you do not call it. |
onUpsellPageShown(cart) | cart: BoltTransactionCart? | A post-purchase upsell offer was displayed. |
onUpsellDecision(cart, decision) | cart: BoltTransactionCart?, decision: BoltUpsellDecision | The shopper reached a final decision on the upsell offer. |
Step names in onCheckoutBack, onCheckoutGoToStep, and onCheckoutLogout are open-ended strings such as shipping_info and payment. Handle values you do not recognize.
onPaymentSubmit() and onNotify(eventName, eventSeverity) from earlier versions still exist. The SDK calls the new overloads, which forward to the old ones by default. Override only one version of each.
Callback event types
| Type | Fields | Description |
|---|---|---|
BoltCallbackEvent | eventName: String, eventSeverity: String, eventMetadata: Map<String, String> | eventSeverity is "error", "warning", or "info". Nested metadata objects arrive as JSON strings. |
BoltCustomFieldValue | Text(value: String) or Toggle(value: Boolean) | A custom field value. Fields with no value are left out of the map. |
BoltUpsellDecision | ACCEPTED, DECLINED, TIMED_OUT, ABANDONED, UNKNOWN | UNKNOWN covers decisions this SDK version does not recognize. |
BoltSilentLoginResult | Success(authCode: String, state: String) or Failure(reason: String) | Result passed to BoltSilentLogin.authorize. Send authCode and state to your backend for token exchange, as in SSO login. |
Request callbacks
These are request/response callbacks: checkout sends a request and waits for your app to respond. Both are suspend functions, so you can perform asynchronous work before returning.
| Callback | Return Type | Description |
|---|---|---|
check() | Boolean | Called before checkout opens. Return true to proceed, false to cancel (e.g. cart validation failed). Defaults to true. |
fetchShippingOptions(address) | BoltFrontendShippingAndTaxResult? | Called with a BoltShippingAddress. Return shipping options and tax, or null to fall back to backend shipping. Defaults to null. |
BoltCheckoutResult
onCheckoutSuccess receives a BoltCheckoutResult that mirrors Bolt's client transaction view. Fields marked ? can be null. Amounts are in minor currency units.
Field names and types match the published 0.10.2 artifact. Which optional fields are populated for a given checkout is not yet verified against 0.10.2.
Reconciliation fields
| Field | Role |
|---|---|
reference | Bolt transaction reference. Replaces 0.9.0's transactionReference. |
cart?.orderReference | Bolt order reference. Replaces 0.9.0's orderReference. |
merchantOrderNumber | Your merchant-facing order number when Bolt provides it. |
status | Transaction status. Replaces 0.9.0's transactionStatus. |
amount | Charged total as a BoltAmountView. Replaces 0.9.0's totalAmount, currency, and currencySymbol. |
The 0.9.0 fields orderDisplayId, taxAmount, and shippingAmount are no longer top-level fields. Tax and shipping details are in cart?.taxAmount and shippingOption.
Transaction core
| Field | Type | Description |
|---|---|---|
id | String | Transaction ID. |
type | String | Transaction type. |
processor | String | Payment processor identifier. |
date | Long | Transaction timestamp. |
reference | String | Transaction reference. |
status | String | Overall transaction status. |
amount | BoltAmountView | Primary amount: use for display and reconciliation. |
BoltAmountView
| Field | Type | Description |
|---|---|---|
amount | Long | Amount in minor currency units (e.g. cents). |
currency | String | ISO 4217 code (e.g. "USD"). |
currencySymbol | String | Display symbol (e.g. "$"). |
Parties and payment instruments
| Field | Type | Description |
|---|---|---|
fromConsumer | BoltConsumerView? | Payer (id, email, firstName, lastName, phone). |
toConsumer | BoltConsumerView? | Payee when applicable. |
fromCreditCard | BoltCreditCardView? | Card used (id, last4, bin, expiration, network, billingAddress, and more). |
toCreditCard | BoltCreditCardView? | Destination card when applicable. |
last4 | String? | Last four digits of the card at the transaction level. |
Authorization, capture, and risk
| Field | Type | Description |
|---|---|---|
authorization | BoltAuthorizationView? | status and reason for the authorization decision. |
captures | List<BoltCaptureView>? | Capture records (status, amount as BoltAmountView). |
credit | BoltCreditView? | Credit status when present. |
transactionProperties | BoltTransactionProperties? | avsResult and cvvResult from the processor. |
orderDecision | BoltOrderDecisionView? | Order decision (score, decisionFactors). |
riskScore | Double? | Risk score when provided. |
customerListStatus | BoltCustomerListStatus? | autoApproved, blockListed. |
indemnificationDecision | String? | Indemnification decision when applicable. |
indemnificationReason | String? | Indemnification reason when applicable. |
splits | List<BoltTransactionSplitView>? | Split amounts (amount, type). |
lastViewedUtc | Long? | Last viewed time. |
viewStatus | String? | View status. |
hasRefunds | Boolean? | Whether refunds exist on the transaction. |
Addresses and shipping
| Field | Type | Description |
|---|---|---|
shippingAddress | BoltAddressInput? | Shipping address (firstName, lastName, company, streetAddress1, streetAddress2, locality, region, postalCode, countryCode, country, phone, email). |
billingAddress | BoltAddressInput? | Billing address. |
shippingOption | BoltShippingOption? | Selected shipping option: valid, value, and error. When valid is true, value is a BoltCartShipmentView with service, cost, reference, carrier, estimatedDeliveryDate, taxAmount, and more. |
In 0.10.2, BoltShippingOption is this result type. The shipping option you return from fetchShippingOptions is now BoltFrontendShippingOption.
Cart, integrations, and notes
| Field | Type | Description |
|---|---|---|
cart | BoltTransactionCart? | orderReference, taxAmount, discounts (BoltCartDiscountView), and items (BoltCartItemView). |
shopify | BoltShopifyResponse? | Shopify-hosted payment fields when applicable. |
sfcc | BoltSfccOrderResponse? | Salesforce Commerce Cloud integration: sfccOrderToken when present. |
customFieldResponses | List<BoltCustomFieldResponse>? | Custom fields: publicId, response. |
userNote | String? | Shopper-supplied order note. |
BoltLoginDelegate
Implement this delegate when using getLoginActivityResultLauncher().
| Callback | Parameters | Description |
|---|---|---|
onLoginSuccess(authCode, codeVerifier, state) | authCode: String, codeVerifier: String, state: String | User authenticated successfully. Send authCode and state to your backend for token exchange. |
onLoginError(errorReason) | errorReason: String | Login failed (network error, invalid session, or user denied permissions). |
onLoginCancel() | (none) | User dismissed the login screen. No partial session is created. |
BoltPaymentFlowDelegate
Implement this delegate when using getPaymentFlowActivityResultLauncher(). The payment flow is a standalone UI for collecting and tokenizing a payment method without running the full checkout.
| Callback | Parameters | Description |
|---|---|---|
onPaymentFlowSuccess(paymentFlowMethod, creditCard) | paymentFlowMethod: BoltPaymentMethod, creditCard: BoltCreditCard? | Card successfully tokenized. creditCard contains token, last4, network, expiration, and postal code. |
onPaymentFlowError(errorReason) | errorReason: String | Tokenization or network failure. |
onPaymentFlowCancel() | (none) | User dismissed the payment collection screen. |
BoltPaymentAuthorizationDelegate
Implement this delegate when calling authorizePayment(). Used in custom checkout flows where you collected a card via the payment flow.
| Callback | Parameters | Description |
|---|---|---|
onPaymentAuthorizationSuccess(orderReference) | orderReference: String | Payment authorized. Use the reference to confirm the order with your backend. |
onPaymentAuthorizationFail(status, reason) | status: String, reason: String | Authorization declined by the processor (e.g. insufficient funds, suspected fraud). |
onPaymentAuthorizationError(errorReason) | errorReason: String | Request failed before reaching the processor (e.g. network timeout, missing tokenized card). |
Shipping types
These types were renamed after 0.9.0: BoltShippingOption is now BoltFrontendShippingOption, and BoltShippingAndTaxResult is now BoltFrontendShippingAndTaxResult.
BoltFrontendShippingOption
Each entry in BoltFrontendShippingAndTaxResult.shippingOptions:
| Field | Type | Description |
|---|---|---|
service | String | Human-readable shipping method name (e.g. "Standard Shipping"). |
cost | Long | Shipping cost in minor currency units (cents). |
currency | String | ISO 4217 currency code. Defaults to "USD". |
reference | String | Identifier for this shipping option. Defaults to "". |
carrier | String | Carrier name. Defaults to "". |
estimatedDeliveryDate | String | Estimated delivery date. Defaults to "". |
taxAmount | Long | Tax on the shipping option in minor currency units. Defaults to 0. |
BoltFrontendShippingAndTaxResult
Return type for fetchShippingOptions:
| Field | Type | Description |
|---|---|---|
shippingOptions | List<BoltFrontendShippingOption> | Available shipping options to display in checkout. |
taxAmount | Long | Cart-level tax in minor currency units. Defaults to 0. |
taxCurrency | String | ISO 4217 currency code for taxAmount. Defaults to "USD". |