iOS SDK

The Afterpay iOS SDK 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.

Requirements

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

Install the SDK

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

To integrate the SDK manually, see 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.

Your server fetches the configuration from the Get Configuration endpoint and passes it to your app:

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: your server creates a checkout, and the SDK loads its redirect URL. The SDK calls this Checkout V1.
• 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: 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: the customer approves the payment in Cash App.

To compare the options, see 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: PaymentButton starts an Afterpay checkout.
• Lockup: LockupView shows the Afterpay logo.
• Price breakdown: PriceBreakdownView shows the installment amounts for a price.
• 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.

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:

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

Test with the example app

The example app uses the 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.

   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.