---
updatedAt: 2026-02-20T19:24:52.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/payments/llms.txt
---

# Set Up iOS SDK

With the iOS SDK, you can offer Affirm as a payment option in iOS applications. This guide walks you through setting up the iOS client on your checkout page.

<HTMLBlock>{`
<style>
  .dropdown-menu {
    font-family: Arial, sans-serif;
    max-width: 250px;
    margin-left: auto; /* Align to the right */
  	margin-right: 0; /* Ensure it's flush to the right */
    border: 1px solid #ddd;
    border-radius: 8px;
    padding: 10px;
    background: #4A4AF4;
    overflow: hidden; /* Ensure the container grows with content */
  }

  .dropdown-item {
    margin-bottom: 10px;
  }

  .dropdown-toggle {
    display: block;
    width: 100%;
    text-align: left;
    padding: 10px;
    background: #fff;
    border: 1px solid #ddd;
    border-radius: 4px;
    cursor: pointer;
  }

  .dropdown-toggle:hover {
    background: #f0f0f0;
  }

  .dropdown-content {
    display: none;
    margin-top: 5px;
    padding: 10px;
    background: #fff;
    border: 1px solid #ddd;
    border-radius: 4px;
  }

  .dropdown-item.open .dropdown-content {
    display: block;
  }

  .flag-icon {
    width: 20px;
    height: 20px;
    margin-right: 10px;
  }

  .product-item {
    margin-bottom: 5px;
    color: black;
  }

  .product-icon {
    width: 20px;
    height: 20px;
    margin-right: 10px;
  }
  
  .country-title {
    font-family: Arial, sans-serif;
    font-size:20px;
    text-align: center;
    font-weight: bold;
    color: #ffffff;
  } 

</style>
  <div class="dropdown-menu">
    <p class="country-title" alt="Countries where this product is available">Country Availability</p>

    <div class="dropdown-item">
      <button class="dropdown-toggle" onclick="toggleDropdown(event)" alt="Drop down menu displaying the available countries for this product">
        <b>Country List</b> ⬇️
      </button>
      <div class="dropdown-content">
        <div class="product-item">
          <img src="https://files.readme.io/a4c8b3d6596d943e2b93c82cb1d432a2edaf6998667835c2e97ef4a31d460c7e-us-circle-01.png" alt="USA" class="flag-icon">
          USA
        </div>
        <div class="product-item">
          <img src="https://files.readme.io/3ca294a1b4b8b8506c3ff32876abc6e3e33d0e65a509dab81398915094bdbc5c-61TcZ33ZrJL._AC_UY1000_.jpg" alt="Canada" class="flag-icon">
          Canada
        </div>
        <div class="product-item">
          <img src="https://files.readme.io/db98461fef617df7c9970e98f01150f067fcee1fc823a450f09056138b9f70be-united-kingdom-flag-rounded-icon-uk-flag-union-jack-vector.jpg" alt="UK" class="flag-icon">
          UK
        </div>
      </div>
    </div>

  </div>
`}</HTMLBlock>

## Overview

Starting a payment with Affirm on an iOS client consists of creating a checkout form, tokenizing customer information to transmit it securely to your server, and using that token to initiate a charge.

The [iOS SDK](https://github.com/Affirm/affirm-merchant-sdk-ios) is available on Github.

***

## Steps

### 1. Set up Affirm on iOS

#### **With CocoaPods**

1. Install the latest version of [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
2. If you don't have an exisiting [Podfile](https://guides.cocoapods.org/syntax/podfile.html), run this command to create one:

```text Terminal
pod init
```

3. Add this line to your Podfile:

```text Terminal
pod 'AffirmSDK'
```

4. Run this command:

```text Terminal
pod install
```

5. Use the `.xcworkspace` file to open your project in Xcode, instead of the `.xcodeproj` file, from here on out.
6. In the future, to update to the latest version of the SDK, you can run this:

```text Terminal
pod update AffirmSDK
```

<br />

#### **With Carthage**

1. Install the latest version of [Carthage](https://github.com/Carthage/Carthage/releases).
2. Add this line to your Cartfile:

```text Terminal
github "Affirm/affirm-merchant-sdk-ios"
```

3. Follow the Carthage [installation instructions](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos).
4. In the future, to update to the latest version of the SDK, run this command:

```text Terminal
carthage update affirm-merchant-sdk-ios --platform ios
```

> 🚧 SDK Releases
>
> For details on the latest SDK release and past versions, see the [Releases page](https://github.com/Affirm/affirm-merchant-sdk-ios/releases) on GitHub. Watch releases for the repository to receive notifications when a new release is published.

<br />

### 2. Initialize Affirm

Configure the SDK with your Affirm public API key so that it can make requests to the Affirm server.

```swift
ffirmConfiguration.shared.configure(publicKey: "YOUR PUBLIC KEY", environment: .sandbox, merchantName: "Affirm Example Swift")
```
```objectivec
[[AffirmConfiguration sharedInstance] configureWithPublicKey:@"YOUR PUBLIC KEY" environment:AffirmEnvironmentSandbox merchantName:@"Affirm Example"];
```

<br />

### 3. Render Affirm Checkout

Checkout creation is when a customer uses Affirm to pay for an in-app purchase. You can create a checkout object and launch the Affirm checkout using the `Checkout` function:

```swift
let dollarPrice = NSDecimalNumber(string: self.amountTextField.text)
        let item = AffirmItem(name: "Affirm Test Item", sku: "test_item", unitPrice: dollarPrice, quantity: 1, url: URL(string: "http://sandbox.affirm.com/item")!)
        let shipping = AffirmShippingDetail.shippingDetail(name: "Chester Cheetah", line1: "633 Folsom Street", line2: "", city: "San Francisco", state: "CA", zipCode: "94107", countryCode: "USA")
        let checkout = AffirmCheckout(items: [item], shipping: shipping, taxAmount: NSDecimalNumber.zero, shippingAmount: NSDecimalNumber.zero, discounts: nil, metadata: nil, financingProgram: nil, orderId: "JKLMO4321")

        let controller = AffirmCheckoutViewController.start(checkout: checkout, useVCN: true, delegate: self)
        present(controller, animated: true, completion: nil)
```
```objectivec
// initialize an AffirmItem with item details
AffirmItem *item = [AffirmItem itemWithName:@"Affirm Test Item" SKU:@"test_item" unitPrice:price quantity:1 URL:[NSURL URLWithString:@"http://sandbox.affirm.com/item"]];

// initialize an AffirmShippingDetail with the user's shipping address
AffirmShippingDetail *shipping = [AffirmShippingDetail shippingDetailWithName:@"Chester Cheetah" addressWithLine1:@"633 Folsom Street" line2:@"" city:@"San Francisco" state:@"CA" zipCode:@"94107" countryCode:@"USA"];

// initialize an AffirmCheckout object with the item(s), shipping details, tax amount, shipping amount, discounts, financing program, and order ID
AffirmCheckout *checkout = [[AffirmCheckout alloc] initWithItems:@[item] shipping:shipping taxAmount:[NSDecimalNumber zero] shippingAmount:[NSDecimalNumber zero] discounts:nil metadata:nil financingProgram:nil orderId:@"JKLMO4321"];

// The minimum requirements are to initialize the AffirmCheckout object with the item(s), shipping details, and payout Amount
AffirmCheckout *checkout = [AffirmCheckout checkoutWithItems:@[item] shipping:shipping payoutAmount:price];

// initialize an UINavigationController with the checkout object and present it
UINavigationController *nav = [AffirmCheckoutViewController startCheckoutWithNavigation:checkout useVCN:YES getReasonCodes:NO delegate:self];
[self presentViewController:nav animated:YES completion:nil];

// It is recommended that you round the total in the checkout request to two decimal places. Affirm SDK converts the float total to integer cents before initiating the checkout, so may round up or down depending on the decimal places. Ensure that the rounding in your app uses the same calculation across your other backend systems, otherwise, it may cause an error of 1 cent or more in the total validation on your end.
```

<br />

### 4. Add Affirm promotional messaging

Affirm promotional messaging components show customers how they can use Affirm to finance their purchases. Properly placed promotional messaging helps drive increased AOV and conversion.

#### A. Set up promotional messaging:

1\. To display promotional messaging, use the `AffirmPromotionalButton` class, which only requires you to configure and add to your view for implementation. To implement the `AffirmPromotionalButton`:

```swift
self.promotionalButton = [[AffirmPromotionalButton alloc] initWithPromoID:@"promo_set_ios"
                                                                  showCTA:YES
                                                                 pageType:AffirmPageTypeProduct
                                                 presentingViewController:self
                                                                    frame:CGRectMake(0, 0, 315, 34)];
[self.stackView insertArrangedSubview:self.promotionalButton atIndex:0];
```

2\. Use the following to display or refresh promotional messaging:

```objectivec
[self.promotionalButton configureByHtmlStylingWithAmount:[NSDecimalNumber decimalNumberWithString:amountText]
                                          affirmLogoType:AffirmLogoTypeName
                                             affirmColor:AffirmColorTypeBlue
                                           remoteFontURL:[NSURL URLWithString:@"https://fonts.googleapis.com/css?family=Saira+Stencil+One&display=swap"]
                                            remoteCssURL:url];
```
```swift
self.promotionalButton.configure(amount: NSDecimalNumber(string: amountText),
                         affirmLogoType: .name,
                            affirmColor: .blue,
                                   font: UIFont.italicSystemFont(ofSize: 15),
                              textColor: .gray)
```

3\. To use local fonts:

* First, add the font files to your project. Ensure that the files are targeted properly to your application.
* Then, add the font files to your `App-Info.plist`.
* Lastly, use the font in your CSS file. For example:

```css
@font-face
{
font-family: 'OpenSansCondensed-Bold';
src: local('OpenSansCondensed-Bold'),url('OpenSansCondensed-Bold.ttf') format('truetype');
}

body {
font-family: 'OpenSansCondensed-Light';
font-weight: normal;
!important;
}
```

<Callout icon="📘" theme="info">
  If no promotional message is returned, we automatically hide the button.
</Callout>

Tapping on the *Promotional* button automatically opens a modal in an `AffirmPrequalModalViewController` with more information, including (if you have it configured) a button that prompts the user to prequalify for Affirm financing.

#### B. Retrieve raw string from promotional message:

You can retrieve raw string using `AffirmDataHandler`.

```objectivec
NSDecimalNumber *dollarPrice = [NSDecimalNumber decimalNumberWithString:self.amountTextField.text];
[AffirmDataHandler getPromoMessageWithPromoID:@"promo_set_ios"
                                       amount:dollarPrice
                                      showCTA:YES
                                     pageType:AffirmPageTypeBanner
                                     logoType:AffirmLogoTypeName
                                    colorType:AffirmColorTypeBlue
                                         font:[UIFont boldSystemFontOfSize:15]
                                    textColor:[UIColor grayColor]
                     presentingViewController:self
                            completionHandler:^(NSAttributedString *attributedString, UIViewController *viewController, NSError *error) {
                                [self.promoButton setAttributedTitle:attributedString forState:UIControlStateNormal];
                                self.promoViewController = viewController;
}];
```

Then, you can present a promo modal using the following:

```objectivec
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:self.promoViewController];
[self presentViewController:nav animated:YES completion:nil];
```

* `initWithPromoId` - Affirm provides this Promo ID.
  * `showCTA` - To display a link to the modal.
  * `pageType` - Affirm provides this Page type.

* Configure Button:
  * `configureWithAmount`: The price of the product or cart in NSDecimalNumber format.
  * `affirmLogoType`: Set as either `AffirmDisplayTypeLogo`, `AffirmDisplayTypeText`, `AffirmDisplayTypeSymbol`, or `AffirmDisplayTypeSymbolHollow`.
  * `affirmColor`: Set as either `AffirmColorTypeBlue`, `AffirmColorTypeBlack`, or `AffirmColorTypeWhite`.

#### C. Add an educational modal:

Tapping on `AffirmAsLowAsButton` opens an educational modal based on the following:

* When `alaEnabled` is set to `true` and the amount is greater than or equal to 50, the customer sees a product modal with pricing information.
* When `alaEnabled` is set to `true` and the amount is less than 50, the customer sees a site modal without pricing information.
* When `alaEnabled` is set to `false`, the customer sees a site modal without pricing information.

To display a modal elsewhere in the application, initialize and display an instance of the modal VC as follows:

Tapping on the *Promotional* button automatically opens a modal in an `AffirmPrequalModalViewController` with more information, including (if you have it configured) a button that prompts the user to prequalify for Affirm financing.

```objectivec
AffirmPromoModalViewController *viewController = [[AffirmPromoModalViewController alloc] initWithPromoId:@"promo_id" amount:amount delegate:delegate];
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:viewController];
[self.presentingViewController presentViewController:nav animated:YES completion:nil];
```

* `amount`: The price of the product or cart in NSDecimal (value less than 50 opens a site modal with no pricing information)
* `promoId`: Affirm provides this Promo ID

#### D. Track order confirmed:

The `trackOrderConfirmed` event triggers when a customer completes their purchase. The SDK provides the `AffirmOrderTrackerViewController` class to track it, which requires `AffirmOrder` and an array with `AffirmProduct`.

```ruby
[AffirmOrderTrackerViewController trackOrder:order products:@[product0, product1]];
```

<Callout icon="📘" theme="info">
  This feature improves after the endpoint is ready for app and disappears after 5 seconds.
</Callout>

<br />

### 5. Handle callbacks

The `AffirmCheckoutDelegate` object which receives messages at various stages in the checkout process. It will return `checkout_token` from this delegate.

```swift
func checkout(_ checkoutViewController: AffirmCheckoutViewController, completedWithToken checkoutToken: String)
```
```objectivec
- (void)checkout:(AffirmCheckoutViewController *)checkoutViewController completedWithToken:(NSString *)checkoutToken
```

For more callbacks, see the [code reference](https://github.com/Affirm/affirm-merchant-sdk-ios/blob/master/AffirmSDK/AffirmCheckoutDelegate.h).

> 👍 Checkout Token
>
> Once the checkout has been successfully confirmed by the user, the `AffirmCheckoutDelegate` object receives a `checkout_token`. This token should be forwarded to your server, which should be used to [authorize a charge](https://docs.affirm.com/developers/reference/authorize_charge) on the user's account.

<br />

### 6. Create a charge

When a customer successfully completes a checkout, it is recorded as a new purchase attempt. This needs to be handled on your server-side to be fulfilled via our [Charges API](https://docs.affirm.com/payments/docs/create-a-charge).

***

## What's next?

* <Anchor label="iOS SDK FAQ" target="_blank" href="https://docs.affirm.com/payments/docs/ios-sdk-faqs">iOS SDK FAQ</Anchor>
* <Anchor label="Checkout button" target="_blank" href="https://docs.affirm.com/developers/docs/pre-styled-checkout-button">Checkout button</Anchor>
* <Anchor label="Set up Android SDK" target="_blank" href="https://docs.affirm.com/payments/docs/checkout-android">Set up Android SDK</Anchor>

# Sub pages

* [iOS SDK FAQ](https://docs.affirm.com/payments/docs/ios-sdk-faqs.md)

# Sibling pages

* [About Mobile SDKs](https://docs.affirm.com/payments/docs/mobile-sdks.md)
* [Set Up Android SDK](https://docs.affirm.com/payments/docs/checkout-android.md)

# Related topics

* [About Mobile SDKs](https://docs.affirm.com/payments/docs/mobile-sdks.md)
* [iOS SDK FAQ](https://docs.affirm.com/payments/docs/ios-sdk-faqs.md)
* [Set Up Android SDK](https://docs.affirm.com/payments/docs/checkout-android.md)