> This page is for Afterpay Online Developer, version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# iOS SDK

The [Afterpay iOS SDK](https://github.com/afterpay/sdk-ios) presents Afterpay checkout in your iOS app and provides prebuilt UI components, such as the payment button and price breakdown. It also lets you accept Cash App Pay through your Afterpay merchant account.

This guide covers installation, configuration, the available checkout integrations, and how to test with the example app. For the complete SDK reference, see the [iOS SDK documentation](https://afterpay.github.io/sdk-ios/).

## Requirements

* iOS 12.0 or later
* Swift 5.7 or later
* Xcode 14.0 or later

> **WebView support**
>
> Afterpay checkout runs in a `WKWebView` that requires iOS Safari 13.4 or later. The SDK runs on iOS 12, but your app must hide Afterpay from customers on earlier versions. For example, wrap your Afterpay views in an `if #available(iOS 13.4, *)` check.

## Install the SDK

#### Swift Package Manager

Swift Package Manager is the recommended installation method. In Xcode, choose **File > Add Package Dependencies**, enter `https://github.com/afterpay/sdk-ios.git`, and add the `Afterpay` library to your app target. In a Swift package, add the dependency to `Package.swift`:

```swift
dependencies: [
  .package(
    url: "https://github.com/afterpay/sdk-ios.git",
    .upToNextMajor(from: "5.9.0")
  )
]
```

#### CocoaPods

```ruby
pod 'Afterpay', '~> 5.9'
```

#### Carthage

```text
github "afterpay/sdk-ios" ~> 5.9
```

To integrate the SDK manually, see [Integration](https://afterpay.github.io/sdk-ios/integration/) in the SDK documentation.

## Configure the SDK

The SDK uses your merchant configuration to render UI components with the correct branding, terms, and currency formatting. Web Redirect, Built-in UI, and Cash App Pay require it. The Afterpay Button uses its own configuration, described in [Afterpay Button](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout/afterpay-button).

Your server fetches the configuration from the [Get Configuration](/afterpay-online-developer/api-reference/reference/configuration/get-configuration) endpoint and passes it to your app:

```swift
let configuration = try Configuration(
  minimumAmount: response.minimumAmount?.amount,
  maximumAmount: response.maximumAmount.amount,
  currencyCode: response.maximumAmount.currency,
  locale: Locale(identifier: "en_US"),
  environment: .sandbox,
  // Optional. Overrides the device locale.
  consumerLocale: Locale(identifier: "en_US")
)

Afterpay.setConfiguration(configuration)
```

* Set the configuration before you present a checkout or display any UI component.
* Use `.sandbox` for development and `.production` for release builds. The environment must match the environment your server uses to create checkouts.
* Cache the configuration and refresh it about once a day. Bundle a default configuration in case the first request fails.
* If you haven't set a configuration, or the customer's language (the device language, or `consumerLocale`) isn't supported in the configured region, `Afterpay.enabled` is `false`. The lockup, price breakdown, and widget then hide themselves, but `PaymentButton` only blanks its artwork. Use this property to hide the payment button and your own Afterpay views.

## Present checkout

After you configure the SDK, present checkout in one of four ways:

* [Web Redirect](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout/web-redirect): your server creates a checkout, and the SDK loads its redirect URL. The SDK calls this Checkout V1.
* [Built-in UI](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout/built-in-ui): the SDK opens Afterpay's checkout right away and asks your app for a token. Supports express checkout. The SDK calls this Checkout V2.
* [Afterpay Button](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout/afterpay-button): the SDK creates the checkout from your app and returns a one-time virtual card. No server integration. The SDK calls this Checkout V3.
* [Cash App Pay](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout/cash-app-pay): the customer approves the payment in Cash App.

To compare the options, see [Present checkout](/afterpay-online-developer/guides/sdk/ios-sdk/present-checkout).

## UI components

The SDK includes prebuilt components that follow Afterpay brand guidelines. Outside the US, they show Afterpay branding, or Clearpay branding for UK merchants. US merchants see Cash App Afterpay branding.

* [Payment button](/afterpay-online-developer/guides/sdk/ios-sdk/ui-components/payment-button): `PaymentButton` starts an Afterpay checkout.
* [Lockup](/afterpay-online-developer/guides/sdk/ios-sdk/ui-components/lockup): `LockupView` shows the Afterpay logo.
* [Price breakdown](/afterpay-online-developer/guides/sdk/ios-sdk/ui-components/price-breakdown): `PriceBreakdownView` shows the installment amounts for a price.
* [Checkout widget](/afterpay-online-developer/guides/sdk/ios-sdk/ui-components/checkout-widget): `WidgetView` shows the payment schedule and updates when you send it a new total.

For branding, color schemes, and accessibility, see [iOS UI components](/afterpay-online-developer/guides/sdk/ios-sdk/ui-components).

## Security

To add certificate pinning to the checkout and widget web views, register an authentication challenge handler. Return `true` if you handled the challenge, or `false` to use the default handling. This example uses [TrustKit](https://github.com/datatheorem/TrustKit):

```swift
Afterpay.setAuthenticationChallengeHandler { challenge, completionHandler in
  let validator = TrustKit.sharedInstance().pinningValidator
  return validator.handle(challenge, completionHandler: completionHandler)
}
```

## Test with the example app

The [example app](https://github.com/afterpay/sdk-ios/tree/master/Example) uses the [example server](https://github.com/afterpay/sdk-example-server), which creates sandbox checkouts with your merchant credentials.

1. Start the example server. It requires Node.js and listens on `http://localhost:3000`. In `.env`, set `AFTERPAY_MERCHANT_ID` and `AFTERPAY_SECRET_KEY` to your sandbox credentials, and set `AFTERPAY_REGION`, for example `en-US`.

   ```bash
   git clone https://github.com/afterpay/sdk-example-server.git
   cd sdk-example-server
   cp .env.example .env
   npm install
   npm run build
   npm run start
   ```

2. Clone the SDK and open `Afterpay.xcworkspace` in Xcode. Open the workspace rather than the example project so that Xcode resolves the SDK's dependencies.

3. Select the **Example** scheme and run it on a simulator.

4. To use a different server host or port, change the values on the app's **Settings** tab.

5. Add items to the cart and check out. Log in with a sandbox customer account. For details, see [Test environments](/afterpay-online-developer/guides/api-development/test-environments).