Set Up iOS SDK

Country Availability

Country List ⬇️

USA

Canada

UK

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 is available on Github.

Steps

pod init

pod 'AffirmSDK'

pod install

pod update AffirmSDK

github "Affirm/affirm-merchant-sdk-ios"

carthage update affirm-merchant-sdk-ios --platform ios

ffirmConfiguration.shared.configure(publicKey: "YOUR PUBLIC KEY", environment: .sandbox, merchantName: "Affirm Example Swift")

[[AffirmConfiguration sharedInstance] configureWithPublicKey:@"YOUR PUBLIC KEY" environment:AffirmEnvironmentSandbox merchantName:@"Affirm Example"];

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)

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

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:

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:

[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];

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:

@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;
}

📘

If no promotional message is returned, we automatically hide the button.

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.

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:

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.

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.

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

📘

This feature improves after the endpoint is ready for app and disappears after 5 seconds.

5. Handle callbacks

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

func checkout(_ checkoutViewController: AffirmCheckoutViewController, completedWithToken checkoutToken: String)

- (void)checkout:(AffirmCheckoutViewController *)checkoutViewController completedWithToken:(NSString *)checkoutToken

For more callbacks, see the code reference.

What's next?

• iOS SDK FAQ
• Checkout button
• Set up Android SDK