Upgrade (4.X.X to 5.0.2)
If you are using an older version of the SDK, you can refer to this upgrade document. We recommend that you install the lastest version of this SDK to access the most up-to-date features and experience.
New features include:
- Refactored code
- HTTP Networking
- Debug logging
- Event tracker
- SDK configuration and init
- Prequalify Flow
- Checkout Flow (direct + vcn)
- Exceptional Flows
- Activity indicator
- Track order confirmed
- Page Types
- Session cookie
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:
- Install the iOS SDK
- Add Affirm promotional messaging
- Configure Affirm as a payment method
- Authorize a test charge
- Test your integration
- 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.
Before you begin
Before beginning integration work, you should review:
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
- Add the following to your store application’s Podfile:
- Run pod install
- Add the following to your Cartfile:
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 sharedInstance] configureWithPublicKey:@"PUBLIC_API_KEY" environment:AffirmEnvironmentSandbox];
Checkout creation is the process in which a customer uses Affirm to pay for a purchase in your app. This process is governed by the AffirmCheckoutViewController object, which requires three parameters:
The AffirmCheckout object which contains details about the order
The useVCN object which determines whether the checkout flow should use virtual card network to handle the checkout.
if set YES, it will return the debit card information from this delegate
- (void)vcnCheckout:(AffirmCheckoutViewController *)checkoutViewController completedWithCreditCard:(AffirmCreditCard *)creditCard
if set NO, it will return checkout token from this delegate
- (void)checkout:(AffirmCheckoutViewController *)checkoutViewController completedWithToken:(NSString *)checkoutToken
The AffirmCheckoutDelegate object which receives messages at various stages in the checkout process
Once the AffirmCheckoutViewController has been constructed from the parameters above, you may present it with any other view controller. This initiates the flow which guides the user through the Affirm checkout process. An example of how this is implemented is provided as follows:
// 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, shipping amount, and tax amount AffirmCheckout *checkout = [AffirmCheckout checkoutWithItems:@[item] shipping:shipping taxAmount:[NSDecimalNumber zero] shippingAmount:[NSDecimalNumber zero]]; // alternatively, initialize the AffirmCheckout object with the item(s), shipping details, and payout Amount AffirmCheckout *checkout = [AffirmCheckout checkoutWithItems:@[item] shipping:shipping payoutAmount:price]; // initialize an AffirmCheckoutViewController with the checkout object and present it AffirmCheckoutViewController *controller = [AffirmCheckoutViewController startCheckout:checkout delegate:self]; [self presentViewController:controller animated:YES 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:
- Initiate checkout to access the account creation screen
- If you have an existing account, click Sign In
- 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
- Enter 1234 for the verification code
- 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. Promos consist of promotional messaging, which appears directly in your app, and a modal, which which offers users an ability to prequalify.
To display promotional messaging, the SDK provides the AffirmPromotionalButton class, only requires the developer to add to their view and configure to implement. The AffirmPromotionalButton is implemented as follows:
AffirmPromotionalButton *button = [[AffirmPromotionalButton alloc] initWithPromoID:@"promo_set_ios" showCTA:YES pageType:AffirmPageTypeProduct presentingViewController:viewController frame:frame]; [self.view addSubview:button]; [self.button configureWithAmount:number affirmLogoType:AffirmLogoTypeName affirmColor:AffirmColorTypeBlue maxFontSize:15];
- ConfigureButton - AffirmPromotionalButton
- initWithPromoId - Affirm provides this Promo ID
- showCTA - To display link to 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
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:
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.
[Note: this integration is deprecated as of SDK version 4.0.13.] To display the AffirmPromoModal outside of tapping on the AffirmPromotionalButton, you may initialize and display an instance of the promo modal viewController as follows
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
Track Order Confirmed
The trackOrderConfirmed event triggers when a customer completes their purchase. The SDK provides the AffirmOrderTrackerViewController class to track it, it requires AffirmOrder and an array with AffirmProduct.
[AffirmOrderTrackerViewController trackOrder:order products:@[product0, product1]];
[Note: this feature will be improved after the endpoint is ready for app and it will be disappeared after 5 seconds]
A demo app that integrates Affirm is included in the repo. To run it, run
install and then open Examples.xcworkspace in Xcode.
6. 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.
7. 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 Integration Consultant or firstname.lastname@example.org to coordinate this test.
Connect to the live Affirm environment
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.