# Android SDK API reference
> Look up checkout delegates, results, callbacks, and shipping types in the Bolt Android SDK.
Source: https://help.boltapp.com/developers/sdks/android-kotlin/api-reference
This reference matches `com.bolt:checkout` version `0.10.2`, available on [Maven Central](https://central.sonatype.com/artifact/com.bolt/checkout).
## BoltCheckoutDelegate [#boltcheckoutdelegate]
Implement this delegate when using `getBoltCheckoutActivityResultLauncher()`. All delegate types are in the `com.bolt.checkout.intl` package.
### Terminal callbacks [#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 [#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` | 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 [#callback-event-types]
| Type | Fields | Description |
| ----------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BoltCallbackEvent` | `eventName: String`, `eventSeverity: String`, `eventMetadata: Map` | `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](/developers/sdks/android-kotlin/sso-login/). |
### Request callbacks [#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 [#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 [#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 [#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 [#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 [#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 [#authorization-capture-and-risk]
| Field | Type | Description |
| ------------------------- | --------------------------------- | --------------------------------------------------------- |
| `authorization` | `BoltAuthorizationView?` | `status` and `reason` for the authorization decision. |
| `captures` | `List?` | 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?` | Split amounts (`amount`, `type`). |
| `lastViewedUtc` | `Long?` | Last viewed time. |
| `viewStatus` | `String?` | View status. |
| `hasRefunds` | `Boolean?` | Whether refunds exist on the transaction. |
### Addresses and shipping [#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 [#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?` | Custom fields: `publicId`, `response`. |
| `userNote` | `String?` | Shopper-supplied order note. |
***
## BoltLoginDelegate [#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 [#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 [#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 [#shipping-types]
These types were renamed after 0.9.0: `BoltShippingOption` is now `BoltFrontendShippingOption`, and `BoltShippingAndTaxResult` is now `BoltFrontendShippingAndTaxResult`.
### BoltFrontendShippingOption [#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 [#boltfrontendshippingandtaxresult]
Return type for `fetchShippingOptions`:
| Field | Type | Description |
| ----------------- | ---------------------------------- | ------------------------------------------------------------ |
| `shippingOptions` | `List` | 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"`. |