iOS implementation guide

This guide walks you through integrating the iOS SDK: install and configure it, create checkouts on your server, present checkout in your app, and complete the order.

When the customer taps your payment button, the SDK shows a loading screen and asks your app for a checkout token. Your app gets the token from your server and passes it to the SDK, which opens Afterpay checkout in a web view. The customer stays in your app, and the SDK receives the result directly from checkout, so your app doesn’t handle redirect URLs. You can offer standard checkout or express checkout, where the customer chooses a shipping address and shipping option in checkout.

This guide uses the SDK’s Checkout V2 API, which is available in Swift with UIKit.

To accept Cash App Pay, see Cash App Pay. For a front-end-only integration that returns a one-time virtual card, see the Afterpay Button, available in the US and Canada.

How it works

Your server creates the checkout with your merchant credentials, the SDK presents checkout to the customer, and your server completes the payment. Your merchant credentials never leave your server.

Cash App Pay uses the same server flow, but Pay Kit sends the customer to Cash App instead of the SDK presenting checkout. For the steps, see Cash App Pay.

The Afterpay Button works differently: the SDK creates the checkout itself and returns a virtual card, which you process like any other card payment.

Step 1: 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.

Step 2: Configure the SDK

The SDK uses your merchant configuration to show UI components with the right branding, terms, and currency format. Checkout and Cash App Pay also 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 stays visible with blank artwork. Check this property to hide the payment button and your own Afterpay views.

Step 3: Create a checkout on your server

When the SDK asks for a token, your app calls your server. Your server calls Create Checkout and returns the token from the response:

{
  "amount": { "amount": "100.00", "currency": "USD" },
  "consumer": { "email": "test@example.com" },
  "merchant": {
    "redirectConfirmUrl": "https://example.com/checkout/confirm",
    "redirectCancelUrl": "https://example.com/checkout/cancel",
    "popupOriginUrl": "https://static.afterpay.com"
  },
  "merchantReference": "merchant-order-123"
}

For express checkout, also set mode to express. For the other express fields, see Express checkout.

Step 4: Present the checkout

Start checkout when the customer taps your payment button.

Call presentCheckoutV2Modally from the view controller that shows your cart. Set the SDK configuration first. Otherwise, debug builds trigger an assertion failure, and release builds return without presenting checkout or calling the completion handler.

Afterpay.presentCheckoutV2Modally(
  over: self,
  options: CheckoutV2Options(buyNow: true),
  didCommenceCheckout: { completion in
    // Call your server. Pass the token or an error to completion.
    checkoutService.createCheckout { result in
      completion(result)
    }
  },
  completion: { result in
    switch result {
    case .success(let token):
      // Send the token to your server to complete the order.
      break
    case .cancelled(let reason):
      // Handle the cancellation.
      break
    }
  }
)

If you pass an error to the didCommenceCheckout completion, the SDK shows a dialog that lets the customer retry or close checkout. If the customer’s language isn’t supported in your region, Afterpay.enabled is false and the SDK doesn’t present checkout.

Checkout options

Pass CheckoutV2Options to change the customer’s experience in checkout:

Step 5: Provide shipping options (express checkout)

For express checkout, the SDK calls your app when the customer chooses a shipping address and when they choose a shipping option. Return the shipping options for the address, or a ShippingOptionsError:

Afterpay.presentCheckoutV2Modally(
  over: self,
  options: CheckoutV2Options(shippingOptionRequired: true),
  didCommenceCheckout: { completion in
    checkoutService.createExpressCheckout { completion($0) }
  },
  shippingAddressDidChange: { address, completion in
    let standard = ShippingOption(
      id: "standard",
      name: "Standard",
      description: "3-5 days",
      shippingAmount: Money(amount: "5.00", currency: "USD"),
      orderAmount: Money(amount: "105.00", currency: "USD")
    )
    completion(.success([standard]))
  },
  shippingOptionDidChange: { shippingOption, completion in
    // Return an updated amount for the option, or nil to keep it.
    completion(nil)
  },
  completion: { result in
    // Handle the result.
  }
)

orderAmount is the order total including shipping and tax. The ShippingOptionsError cases are shippingAddressUnrecognized, shippingAddressUnsupported, serviceUnavailable, and badResponse. Checkout shows an error message to the customer for each one.

Use a checkout handler

To handle these callbacks outside the presenting view controller, implement CheckoutV2Handler and register it with Afterpay.setCheckoutV2Handler(_:). The protocol has the same three methods: didCommenceCheckout(completion:), shippingAddressDidChange(address:completion:), and shippingOptionDidChange(shippingOption:completion:). The SDK holds the handler weakly, so keep a strong reference to it.

Step 6: Complete the order

A successful result contains the order token. A canceled result contains a CancellationReason, such as userInitiated.

Send the order token to your server. To capture the full amount immediately, your server calls Capture Full Payment with the token. To capture later, call Auth and then Capture Payment.

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.