> 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.

# Afterpay Button on iOS

The Afterpay Button runs entirely in your app. You pass the order details to the SDK, the customer completes checkout, and the SDK returns a one-time virtual card for the order. You process the card through your existing card payments flow, so your server doesn't need an Afterpay API integration.

The SDK supports the Afterpay Button in the US and Canada. The SDK calls it Checkout V3.

```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 Gateway as Your card processor
    App->>SDK: Present checkout with order details
    Note over SDK: Customer logs in and confirms
    SDK-->>App: Virtual card and tokens
    App->>Gateway: Authorize the virtual card
    App->>SDK: Update merchant reference (optional)
```

## Step 1: Configure the SDK

Set the Afterpay Button configuration when your app starts. Your Afterpay account manager provides your `shopDirectoryMerchantId`.

```swift
Afterpay.setV3Configuration(
  CheckoutV3Configuration(
    shopDirectoryMerchantId: "your_merchant_id",
    region: .US,
    environment: .sandbox
  )
)
```

The Afterpay Button doesn't need your server to fetch the merchant configuration. To show [UI components](/cash-app-afterpay/guides/sdk/ios-sdk/ui-components), such as the payment button and price breakdown, fetch the configuration with the SDK and set it:

```swift
Afterpay.fetchMerchantConfiguration { result in
  switch result {
  case .success(let configuration):
    Afterpay.setConfiguration(configuration)
  case .failure(let error):
    // Handle the error.
    break
  }
}
```

## Step 2: Present the checkout

When the customer taps your [payment button](/cash-app-afterpay/guides/sdk/ios-sdk/ui-components/payment-button), present the checkout with the customer and order details:

```swift
Afterpay.presentCheckoutV3Modally(
  over: self,
  consumer: Consumer(email: "customer@example.com"),
  orderTotal: OrderTotal(total: 100, shipping: .zero, tax: .zero),
  items: cartItems, // Your cart items, conforming to CheckoutV3Item.
  buyNow: false
) { result in
  switch result {
  case .success(let data):
    // Process the virtual card in data.cardDetails.
    break
  case .cancelled(let reason):
    // Handle the cancellation.
    break
  }
}
```

* `consumer` conforms to `CheckoutV3Consumer`. The SDK's `Consumer` type takes the email address, and optionally the name, phone number, and shipping and billing addresses.
* `orderTotal.total` is the amount to charge, including shipping and tax. The SDK sends `shipping` and `tax` for fraud detection.
* `items` is optional. The SDK doesn't use it to calculate the total.
* Set `buyNow` to `true` to show a **Buy Now** button at the end of checkout.

If you haven't set the Afterpay Button configuration with `setV3Configuration`, debug builds trigger an assertion failure, and release builds return without presenting checkout or calling the completion handler.

## Step 3: Process the virtual card

A successful result contains `CheckoutV3Data`:

| Property         | Description                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardDetails`    | The virtual card. It's either `.card(Card)`, with the card number, CVC, card type, and expiry, or `.tokenized(TokenizedCard)`, with a card token for your payment gateway and the expiry. |
| `cardValidUntil` | The time before which you must authorize the card.                                                                                                                                        |
| `tokens`         | The tokens that identify the checkout. Keep them to update the merchant reference.                                                                                                        |

Authorize the card through your card processor before `cardValidUntil`, as you would any other card payment.

## Step 4: Update the merchant reference

If you don't have an order number when the checkout starts, associate the order with the virtual card after you create the order:

```swift
Afterpay.updateMerchantReferenceV3(
  with: "merchant-order-123",
  tokens: data.tokens
) { result in
  // Handle the result.
}
```

## Accept Cash App Pay

You can also offer Cash App Pay with the Afterpay Button. The SDK creates the checkout and signs it for Cash App Pay Kit. For the full flow, see [Cash App Pay on iOS](/cash-app-afterpay/guides/sdk/ios-sdk/implementation-guide/cash-app-pay).