# 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.9.0`, available on [Maven Central](https://central.sonatype.com/artifact/com.bolt/checkout).

## BoltCheckoutDelegate [#boltcheckoutdelegate]

Implement this delegate when using `getBoltCheckoutActivityResultLauncher()`.

<span id="terminal-callbacks-required" />

### Terminal callbacks [#terminal-callbacks]

| Callback                       | Parameters                   | Description                                                                                                        |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `onCheckoutSuccess(result)`    | `result: BoltCheckoutResult` | Checkout completed. Use the returned references 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.                                                                                    |

<span id="lifecycle-callbacks-optional" />

### 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.   |
| `onEmailEnter(email)`                | `email: String`                              | The shopper entered an email address.            |
| `onShippingDetailsComplete(address)` | `address: BoltShippingAddress`               | The shopper submitted shipping details.          |
| `onShippingOptionsComplete()`        | *(none)*                                     | The shopper completed shipping-option selection. |
| `onPaymentSubmit()`                  | *(none)*                                     | User tapped the pay button.                      |
| `onCartLoaded()`                     | *(none)*                                     | The cart loaded in checkout.                     |
| `onNotify(eventName, eventSeverity)` | `eventName: String`, `eventSeverity: String` | Checkout emitted a notification event.           |

<span id="bidirectional-callbacks-optional-suspend-webview-mode-only" />

### 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)` | `BoltShippingAndTaxResult?` | Called with a `BoltShippingAddress`. Return shipping options and tax, or `null`. Defaults to `null`.                         |

***

## BoltCheckoutResult [#boltcheckoutresult]

`onCheckoutSuccess` receives a `BoltCheckoutResult` with these fields:

<span id="reconciliation-fields" />

<span id="transaction-core" />

| Field                  | Type     | Description                                |
| ---------------------- | -------- | ------------------------------------------ |
| `orderReference`       | `String` | Bolt order reference.                      |
| `transactionReference` | `String` | Bolt transaction reference.                |
| `transactionStatus`    | `String` | Transaction status returned to the client. |
| `orderDisplayId`       | `String` | Merchant-facing order display ID.          |
| `totalAmount`          | `Int`    | Total in minor currency units.             |
| `taxAmount`            | `Int`    | Tax in minor currency units.               |
| `shippingAmount`       | `Int`    | Shipping amount in minor currency units.   |
| `currency`             | `String` | ISO 4217 currency code.                    |
| `currencySymbol`       | `String` | Display symbol for the currency.           |

<span id="boltamountview" />

<span id="parties-and-payment-instruments" />

<span id="authorization-capture-and-risk" />

<span id="addresses-and-shipping" />

<span id="cart-integrations-and-notes" />

***

## 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]

<span id="boltfrontendshippingoption" />

### BoltShippingOption [#boltshippingoption]

Each entry in `BoltShippingAndTaxResult.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.                                           |
| `reference`             | `String` | Identifier for this shipping option.                              |
| `carrier`               | `String` | Carrier name.                                                     |
| `estimatedDeliveryDate` | `String` | Estimated delivery date.                                          |
| `taxAmount`             | `Long`   | Tax on the shipping option in minor currency units.               |

<span id="boltfrontendshippingandtaxresult" />

### BoltShippingAndTaxResult [#boltshippingandtaxresult]

Return type for `fetchShippingOptions`:

| Field             | Type                       | Description                                        |
| ----------------- | -------------------------- | -------------------------------------------------- |
| `shippingOptions` | `List<BoltShippingOption>` | Available shipping options to display in checkout. |
| `taxAmount`       | `Long`                     | Cart-level tax in minor currency units.            |
| `taxCurrency`     | `String`                   | ISO 4217 currency code for `taxAmount`.            |