> This page is for Afterpay. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.cash.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server. # 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](#step-5-present-checkout). ## 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](/cash-app-afterpay/guides/api-development/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. > **WebView support** > > Afterpay checkout runs in a web view. On iOS, it requires iOS 13.4 or later. On Android, it depends on the WebView version installed on the device. For details, see the [iOS SDK](/cash-app-afterpay/guides/sdk/ios-sdk) and [Android SDK](/cash-app-afterpay/guides/sdk/android-sdk) overviews. ## 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. ```mermaid %%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#FFF', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000', 'secondaryColor': '#fff', 'tertiaryColor': '#fff', 'noteBkgColor': '#fff', 'noteBorderColor': '#000', 'background': '#fff' } } }%% sequenceDiagram participant App participant SDK as Afterpay SDK participant Server as Merchant server participant API as Afterpay API Server->>API: GET /v2/configuration API-->>Server: Minimum and maximum amounts App->>Server: Request configuration Server-->>App: Configuration App->>SDK: Set configuration App->>Server: Request checkout Server->>API: POST /v2/checkouts API-->>Server: Checkout token and URL Server-->>App: Checkout URL App->>SDK: Present checkout URL Note over SDK: Customer logs in and confirms SDK-->>App: Checkout result (order token) App->>Server: Complete order Server->>API: POST /v2/payments/capture API-->>Server: Payment Server-->>App: Order result ``` ## 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](/cash-app-afterpay/api-reference/reference/configuration/get-configuration) endpoint. ```bash 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. ```json { "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](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) endpoint and returns the checkout URL. ```bash 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" }' ``` > **Warning** > > Set both `merchant.redirectConfirmUrl` and `merchant.redirectCancelUrl`. The SDK watches for checkout to redirect to one of them to detect the result. They can be any URLs; by default, the SDK doesn't load them. * 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: ```json { "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 #### Swift (iOS) Add the SDK with Swift Package Manager. 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") ) ] ``` To install with CocoaPods or Carthage, see the [iOS SDK](/cash-app-afterpay/guides/sdk/ios-sdk) overview. #### Kotlin (Android) Add the SDK to your module's `build.gradle.kts`: ```kotlin dependencies { implementation("com.afterpay:afterpay-android:4.9.0") } ``` The SDK's manifest declares the checkout activity and the `INTERNET` permission, so you don't need to change your app's manifest. ## 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. #### Swift (iOS) ```swift 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) } ``` The `Configuration` initializer throws a `ConfigurationError` if an amount, the currency code, or the locale isn't valid. #### Kotlin (Android) ```kotlin data class AmountResponse(val amount: String, val currency: String) data class ConfigurationResponse( val minimumAmount: AmountResponse?, val maximumAmount: AmountResponse, ) // Call this on the main thread. fun applyConfiguration(response: ConfigurationResponse) { Afterpay.setConfiguration( minimumAmount = response.minimumAmount?.amount, maximumAmount = response.maximumAmount.amount, currencyCode = response.maximumAmount.currency, locale = Locale.US, environment = AfterpayEnvironment.SANDBOX, ) } ``` `setConfiguration` throws an `IllegalArgumentException` if the amounts, the currency code, or the locale isn't valid, and a `NumberFormatException` if an amount isn't a number. * 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: | Option | How it works | Guides | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web Redirect | Your server creates a checkout and returns its URL. The SDK loads the URL and detects the result from your redirect URLs. This quickstart uses Web Redirect. | [iOS](/cash-app-afterpay/guides/sdk/ios-sdk/present-checkout/web-redirect) · [Android](/cash-app-afterpay/guides/sdk/android-sdk/present-checkout/web-redirect) | | Built-in UI | The SDK opens checkout right away and asks your app for a checkout token while it loads. Supports express checkout callbacks for shipping. | [iOS](/cash-app-afterpay/guides/sdk/ios-sdk/present-checkout/built-in-ui) · [Android](/cash-app-afterpay/guides/sdk/android-sdk/present-checkout/built-in-ui) | | Afterpay Button | The SDK creates the checkout from your app and returns a one-time virtual card that you process like any other card. No Afterpay server integration. | [iOS](/cash-app-afterpay/guides/sdk/ios-sdk/present-checkout/afterpay-button) · [Android](/cash-app-afterpay/guides/sdk/android-sdk/present-checkout/afterpay-button) | | Cash App Pay | Your server, or the SDK with the Afterpay Button, creates the checkout, and the customer approves the payment in Cash App. | [iOS](/cash-app-afterpay/guides/sdk/ios-sdk/present-checkout/cash-app-pay) · [Android](/cash-app-afterpay/guides/sdk/android-sdk/present-checkout/cash-app-pay) | 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. #### Swift (iOS) Call `presentCheckoutModally` from the view controller that shows your cart: ```swift 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)") } } } } } ``` If you haven't set the configuration, or the customer's language isn't supported in your region, `Afterpay.enabled` is `false`, and `presentCheckoutModally` returns without presenting checkout or calling the completion handler. For SwiftUI and Objective-C, see [Web Redirect on iOS](/cash-app-afterpay/guides/sdk/ios-sdk/present-checkout/web-redirect). #### Kotlin (Android) Register an activity result launcher in the activity that shows your cart, then launch the checkout intent with the URL: ```kotlin class CartActivity : AppCompatActivity() { private val checkoutLauncher = registerForActivityResult(StartActivityForResult()) { result -> val data = result.data ?: return@registerForActivityResult when (result.resultCode) { RESULT_OK -> { val token = Afterpay.parseCheckoutSuccessResponse(data) // Send the token to your server to complete the order. } RESULT_CANCELED -> { val status = Afterpay.parseCheckoutCancellationResponse(data) // Handle the cancellation. } } } private fun onAfterpayButtonClicked() { lifecycleScope.launch { // Call your server's checkout endpoint. val checkoutUrl = checkoutService.createCheckout() checkoutLauncher.launch( Afterpay.createCheckoutIntent(this@CartActivity, checkoutUrl), ) } } } ``` If you haven't set the configuration, or the customer's language isn't supported in your region, checkout closes with the cancellation status `LANGUAGE_NOT_SUPPORTED`. If the URL isn't an Afterpay checkout URL, it closes with `INVALID_CHECKOUT_URL`. ## 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](/cash-app-afterpay/api-reference/reference/payments/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. ```bash 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](/cash-app-afterpay/api-reference/reference/payments/auth) with the token. Then call [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/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](/cash-app-afterpay/guides/api-development/test-environments). To see a complete working integration, run the [iOS example app](/cash-app-afterpay/guides/sdk/ios-sdk#test-with-the-example-app) or the [Android sample app](/cash-app-afterpay/guides/sdk/android-sdk#test-with-the-sample-app) with the Afterpay example server. ## Go live Before you release your app, complete this checklist: * Complete [certification](/cash-app-afterpay/guides/api-development/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.