Skip to main content

Merchant Help

 

Affirm Merchant Help

iOS SDK

Overview

You can use the Affirm iOS SDK to add the Affirm payment option to your iOS application. The SDK allows you to:

  • Offer Affirm as a payment option at checkout
  • Display Affirm promotional messaging

The process to add Affirm to your iOS app is:

  1. Install the iOS SDK
  2. Add Affirm promotional messaging
  3. Configure Affirm as a payment method
  4. Authorize a test charge
  5. Test your integration
  6. Deploy to production

Please contact us using this form or through your Affirm contacts if you have any questions or problems implementing the iOS SDK.

Sandbox development

You should have received an email inviting you to create an Affirm account. Click here for information about accessing your account.

Develop and test the Affirm integration in your development environment connected to our sandbox. To use our sandbox, retrieve your sandbox API keys at https://sandbox.affirm.com/dashboard/#/apikeys for use during integration.

After development and testing, you'll need to update your integration to use your live API keys, which you can find at https://affirm.com/dashboard/#/apikeys.

1. Install the iOS SDK

We recommend using CocoaPods or Carthage to install the SDK.

CocoaPods

  1. Add the following to your store application’s Podfile:
pod 'AffirmSDK'
  1. Run pod install

Carthage

  1. Add the following to your Cartfile:
github "Affirm/affirm-ios-sdk"
  1. Follow these instructions

If you’re not using CocoPods or Carthage, you can install the SDK by cloning our GitHub repository and adding the AffirmSDK.framework folder into your XCode project.

2. Configure Affirm as a payment method

Add your Public API key and set the environment to our sandbox in the shared AffirmConfiguration instance (preferably in your AppDelegate).

AffirmConfiguration *config = [AffirmConfiguration configurationWithPublicAPIKey:@"PUBLIC_API_KEY" environment:AffirmEnvironmentSandbox];
[AffirmConfiguration setSharedConfiguration:config];

Create the AffirmCheckoutViewController object, which manages checkout, with these 3 required parameters:

  • The AffirmCheckoutDelegate object receives messages when the checkout creation succeeds or fails
  • The AffirmConfiguration object contains your public key and Affirm domain set to sandbox.affirm.com
  • The AffirmCheckout checkout object describes the purchase (includes price, item, address, contact information).
    • Note: Unlike the ecommerce integration, the Affirm SDK expects prices to be formatted as an NSDecimalNumber in dollars, not integer cents USD.

Once you create AffirmCheckoutViewController from these parameters, you’d present it as you would any other view controller. Here is an example:

AffirmItem *item = [AffirmItem itemWithName:@"Affirm Test Item" SKU:@"test_item" unitPrice:price quantity:1 URL:[NSURL URLWithString:@"http://www.example.com/item"]];
AffirmShippingDetail *shipping = [AffirmShippingDetail shippingDetailWithName:@"Chester Cheetah" addressWithLine1:@"633 Folsom Street" line2:@"" city:@"San Francisco" state:@"CA" zipCode:@"94107" countryCode:@"USA"];
AffirmCheckout *checkout = [AffirmCheckout checkoutWithItems:@[item] shipping:shipping taxAmount:[NSDecimalNumber zero] shippingAmount:[NSDecimalNumber zero]];
AffirmCheckoutViewController *checkoutVC = [AffirmCheckoutViewController startCheckout:checkout checkoutType:AffirmCheckoutTypeAutomatic delegate:self];
[self presentViewController:checkoutVC animated:true completion:nil];

This creates the flow that guides the customer through the Affirm checkout process. The flow ends when the customer either successfully confirms the checkout, cancels the checkout, or encounters an error. In each of these cases, Affirm will send a message to AffirmCheckoutDelegate with additional information about the outcome.

3. Authorize a test charge

Follow these steps to get the checkout token during development:

  1. Initiate checkout to access the account creation screen
  2. If you have an existing account, click Sign In
  3. If you don’t have an existing account, create one with the following:
  • Any first and last name
  • An email address with a valid format
  • A valid US cell phone number (you do not need access to this number) that you will use in all subsequent checkout attempts
  • A birth date older than 18 years old
  • Any four digits
  1. Enter 1234 for the verification code
  2. Click Confirm

The checkout token will be sent to the AffirmCheckoutDelegate object. Forward this token to your server to authorize the charge. Click here for more information on authorizing a charge.

4. Add Affirm promotional messaging

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

Note: Unlike the ecommerce integration, the Affirm SDK expects prices to be formatted as an NSDecimalNumber in dollars, not integer cents USD.

Add monthly payment messaging

Display monthly payment messaging by using a custom AffirmAsLowAsButton provided in the SDK. AffirmAsLowAsButton includes all the functionality in a button, which handles all its states. You only need to add to your view and configure it. Add AffirmALAButton with the following code:

AffirmAsLowAsButton *alaButton = [AffirmAsLowAsButton createButtonWithPromoID:@"promo_id" presentingViewController:self frame:frame];
[self.view addSubview:alaButton];
[alaButton configureWithAmount:amount affirmLogoType:AffirmLogoTypeName affirmColor:AffirmColorTypeBlue maxFontSize:18 callback:^(BOOL alaEnabled, NSError *error) {
    //alaEnabled specifies whether ALA text or a default message is being displayed
}];
  • amount: The price of the product or cart in NSDecimalNumber format
  • promoId: Affirm provides this Promo ID
  • affirmLogoType: Set as either AffirmDisplayTypeLogo, AffirmDisplayTypeText, AffirmDisplayTypeSymbol, or AffirmDisplayTypeSymbolHollow
  • affirmColor: Set as either AffirmColorTypeBlue, AffirmColorTypeBlack, or AffirmColorTypeWhite

Add an educational modal

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

  • When alaEnabled is true and amount is greater than or equal to 50, the customer sees a product modal with pricing information
  • When alaEnabled is true and amount is less than 50, the customer sees a site modal without pricing information
  • When alaEnabled is 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:

AffirmPromoModalViewController *promoVC = [AffirmPromoModalViewController promoModalControllerWithModalId:@"promo_id" amount:amount];
[self presentViewController:promoVC 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

5. Test your integration

After completing your integration, do a thorough testing of both your front-end and order management functions in our sandbox to ensure that everything works as expected. Click here for our recommended test plan. However, you’ll need to tailor your testing plan to your specific systems, processes, and integration.

6. Deploy to production

Coordinate testing with Affirm

Before deploying the Affirm integration to your production site, Affirm will need to test it in your development or staging environment connected to our live environment. Contact your Client Success Manager to coordinate this test.

Launch to production

After you have connected your integration to our live environment and we have tested it, you are ready to release your application in your production environment and offer Affirm as a payment option to your customers.