iOS checkout

Before you begin

Complete steps 1 through 5 of the Custom Cart integration. Your app also needs:

• The iOS SDK installed and initialized with the publishable key, division, and environment for this integration.
• An application backend endpoint that returns a fresh order token for the current cart.

Never call POST /v1/merchant/orders or put a Bolt API key in the app. Follow Create an order token for the server implementation.

1. Get an order token

When the shopper selects checkout, send the current cart identifier to your backend. Wait for your backend to return the token from Bolt before opening checkout.

Create a new order token when the cart changes or the shopper starts another checkout attempt.

2. Open checkout

The completion handler works from UIKit and SwiftUI without requiring a presenting view controller:

import BoltCheckoutSDK

func openBoltCheckout(orderToken: String) {
    let config = BoltCheckoutConfig(orderToken: orderToken)

    BoltCheckout.shared.startCheckout(config: config) { outcome in
        switch outcome {
        case .success(let result):
            print("Bolt transaction: \(result.reference)")
        case .canceled:
            // Return the shopper to the cart.
            break
        case .failed(let errorReason):
            // Show a retry action and record the error.
            print("Bolt Checkout failed: \(errorReason)")
        }
    }
}

The app callback controls client-side state only. Use verified Merchant Callbacks and transaction webhooks as the source of truth for order and payment state.

Choose another presentation method

These are alternatives to the completion handler.

Delegate

Implement the three required BoltSimpleCheckoutDelegate methods, then pass the delegate when checkout starts:

import BoltCheckoutSDK

final class CheckoutCoordinator: BoltSimpleCheckoutDelegate {
    func open(orderToken: String) {
        let config = BoltCheckoutConfig(orderToken: orderToken)
        BoltCheckout.shared.startCheckout(config: config, delegate: self)
    }

    func onCheckoutSuccess(result: BoltCheckoutResult) {
        print("Bolt transaction: \(result.reference)")
    }

    func onCheckoutError(errorReason: String) {
        print("Bolt Checkout failed: \(errorReason)")
    }

    func onCheckoutCancel() {
        // Return the shopper to the cart.
    }
}

View controller

Present BoltCheckoutViewController with the same configuration and delegate:

let config = BoltCheckoutConfig(orderToken: orderToken)
let checkout = BoltCheckoutViewController(config: config, delegate: delegate)
present(checkout, animated: true)

Prefill shopper details

Pass optional hints when your app already has shopper information:

let hints = Bolt.HintsBuilder()
    .withFirstName("Ada")
    .withLastName("Lovelace")
    .withEmail("ada@example.com")
    .withCountry("US")
    .build()

let config = BoltCheckoutConfig(orderToken: orderToken, hints: hints)

Do not send placeholder or stale values. The shopper can review the information in checkout.

3. Verify the iOS client

In sandbox:

1. Start checkout from a cart and confirm your backend returns a new order token.
2. Confirm Bolt Checkout opens and shows the same items and total as the cart.
3. Complete a purchase with a sandbox test card.
4. Confirm the app receives a success result and your backend receives the expected callback and webhook events.
5. Cancel another attempt and confirm the app returns the shopper to the cart without treating it as a completed order.

If checkout does not open or the cart does not match, continue to Custom Cart troubleshooting.