Mobile SDK quickstart

This quickstart walks you through adding Afterpay to an iOS or Android app, from your first server request to your first captured sandbox payment. You set up two server endpoints, add the Afterpay SDK to your app, present checkout, and capture the payment.

The quickstart presents checkout with Web Redirect, the simplest option. For the other ways to present checkout, see Step 5.

Before you begin

Make sure that you have the following:

• An Afterpay sandbox merchant ID and secret key. Your Afterpay account manager provides them. For details, see Test environments.
• A backend server that you control. Your server calls the Afterpay API with your secret key. Never put your secret key in your app.
• For iOS: Xcode 14.0 or later and an app that targets iOS 12.0 or later.
• For Android: Android Studio and an app with a minimum SDK of API level 24 (Android 7.0) or later.

How it works

Your server holds your Afterpay credentials and makes every Afterpay API call. Your app gets the merchant configuration and a checkout URL from your server, and the SDK presents checkout to the customer.

Step 1: Fetch the merchant configuration

The SDK needs your merchant configuration to show checkout and its UI components with the correct currency and order limits. Your server fetches the configuration from the Get Configuration endpoint.

curl https://global-api-sandbox.afterpay.com/v2/configuration \
  --user 'MERCHANT_ID:SECRET_KEY' \
  --header 'Accept: application/json' \
  --header 'User-Agent: YOUR_USER_AGENT'

The response contains your order limits. The response omits minimumAmount if your account has no minimum order amount.

{
  "minimumAmount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "maximumAmount": {
    "amount": "2000.00",
    "currency": "USD"
  }
}

Expose an endpoint on your server that returns this response to your app, for example GET /afterpay/configuration. Your configuration doesn’t change often, so call Get Configuration on a schedule, about once a day, and serve the stored result.

Step 2: Create a checkout

When the customer starts checkout, your app asks your server for a checkout. Your server calls the Create Checkout endpoint and returns the checkout URL.

curl https://global-api-sandbox.afterpay.com/v2/checkouts \
  --request POST \
  --user 'MERCHANT_ID:SECRET_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: YOUR_USER_AGENT' \
  --data '{
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "consumer": {
      "email": "test@example.com",
      "givenNames": "Joe",
      "surname": "Consumer"
    },
    "merchant": {
      "redirectConfirmUrl": "https://example.com/checkout/confirm",
      "redirectCancelUrl": "https://example.com/checkout/cancel"
    },
    "merchantReference": "merchant-order-123"
  }'

• Set amount from the order on your server. Afterpay rejects the checkout if the amount is outside your configured limits or if the currency differs from your account currency.
• Set merchantReference to your order ID so that you can match the payment to the order.

The response contains the checkout token, its expiry time, and the checkout URL:

{
  "token": "002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk",
  "expires": "2023-08-29T00:57:25.754Z",
  "redirectCheckoutUrl": "https://portal.sandbox.afterpay.com/..."
}

Expose an endpoint on your server that creates the checkout and returns the redirectCheckoutUrl to your app, for example POST /afterpay/checkout.

Step 3: Install the SDK

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

Step 4: Configure the SDK

Request the configuration from your server and pass it to the SDK. Set the configuration before you present checkout. Do this when your app starts, and again when you refresh the configuration.

import Afterpay
struct AmountResponse: Decodable {
  let amount: String
  let currency: String
}
struct ConfigurationResponse: Decodable {
  let minimumAmount: AmountResponse?
  let maximumAmount: AmountResponse
}
func applyConfiguration(_ response: ConfigurationResponse) throws {
  let configuration = try Configuration(
    minimumAmount: response.minimumAmount?.amount,
    maximumAmount: response.maximumAmount.amount,
    currencyCode: response.maximumAmount.currency,
    locale: Locale(identifier: "en_US"),
    environment: .sandbox
  )
  Afterpay.setConfiguration(configuration)
}

• Set the locale to match your merchant account’s region, for example en_US for an account in the United States. The SDK uses it for terms and currency formatting.
• The SDK supports only the customer languages available in your region. For example, the en_US locale supports English. The SDK uses the device language unless you pass the optional consumerLocale parameter.
• Use the sandbox environment for development. The environment must match the Afterpay API host that your server uses.
• Store the configuration and pass it to the SDK each time your app starts, before the customer can start a checkout.

Step 5: Present checkout

The SDK can present checkout in four ways:

With Web Redirect, when the customer taps your payment button, call your server’s checkout endpoint from Step 2 and pass the returned URL to the SDK. The SDK loads checkout in a web view. When checkout redirects to your confirm or cancel URL, the SDK closes checkout and returns a result. A successful result contains the order token, which your server uses to complete the payment.

func didTapPayWithAfterpay() {
  // Call your server's checkout endpoint.
  checkoutService.createCheckout { result in
    guard case .success(let checkoutUrl) = result else {
      // Show an error.
      return
    }
    // Present checkout on the main queue.
    DispatchQueue.main.async {
      Afterpay.presentCheckoutModally(
        over: self,
        loading: checkoutUrl
      ) { result in
        switch result {
        case .success(let token):
          // Send the token to your server to complete the order.
          self.completeOrder(token: token)
        case .cancelled(let reason):
          print("Checkout cancelled: \(reason)")
        }
      }
    }
  }
}

Step 6: Capture the payment

Your app sends the order token to your server. To capture the full order amount immediately, your server calls the Capture Full Payment endpoint with the token. Look up the order by the checkout token that your server stored in Step 2, rather than trusting order details sent by the app.

curl https://global-api-sandbox.afterpay.com/v2/payments/capture \
  --request POST \
  --user 'MERCHANT_ID:SECRET_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: YOUR_USER_AGENT' \
  --data '{
    "token": "ORDER_TOKEN",
    "merchantReference": "merchant-order-123"
  }'

The response is a payment object. Fulfill the order only if its status is APPROVED. If the status is DECLINED, don’t fulfill the order. Then return the result to your app.

To capture later instead, for example when you ship the order, call Auth with the token. Then call Capture Payment with the id from the Auth response. An authorization expires after 13 days.

Step 7: Test in the sandbox

1. Run your server with your sandbox credentials and the sandbox host https://global-api-sandbox.afterpay.com.
2. Run your app with the sandbox environment and start a checkout.
3. In checkout, create a sandbox customer account with a unique email address and phone number. The sandbox doesn’t send SMS messages, so enter 111111 as the verification code.
4. Pay with a test card, such as Visa 4111 1111 1111 1111 with a future expiry date. Use CVV 000 for an approved payment and 051 for a declined payment.
5. Confirm that your server captures the payment and that your app shows the result.

For more test cards and sandbox accounts, see Test environments.

To see a complete working integration, run the iOS example app or the Android sample app with the Afterpay example server.

Go live

Before you release your app, complete this checklist:

• Complete certification. Afterpay issues your production credentials after you pass.
• On your server, use your production merchant ID and secret key, and the production API host https://global-api.afterpay.com.
• Update your User-Agent header with your production merchant ID.
• In your app, set the environment to production: .production on iOS or AfterpayEnvironment.PRODUCTION on Android.
• Make sure that your app and your server use the same environment. The SDK environment must match the Afterpay API host that your server uses to create checkouts.