Skip to main content

Merchant Help

 

Affirm Merchant Help

iOS SDK

Overview

The Affirm iOS SDK allows you accept Affirm payments in your own app. The SDK currently supports:

Please contact merchanthelp@affirm.com, or your Affirm contacts, if you have any questions or problems implementing the iOS SDK.


Installation

CocoaPods and Carthage are the recommended methods for installing the Affirm SDK. 

CocoaPods

Add the following to your Podfile and run pod install

pod 'AffirmSDK'

Carthage

Add the following to your Cartfile and follow the setup instructions here

github "Affirm/affirm-ios-sdk"

Manual

Alternatively, if you do not want to use CocoaPods or Carthage, you may clone our GitHub repository and simply drag and drop the AffirmSDK folder into your XCode project.


Retrieve keys

  1. Sign in to https://sandbox.affirm.com/dashboard
  2. Retrieve API keys
    1. Hover over the profile icon area at the lower-left of the page.
      Screen Shot 2016-03-22 at 7.56.58 AM-2.png
    2. Click the API Keys link that appears.
      Screen Shot 2016-03-22 at 7.56.20 AM.png
    3. Copy the public, private, and financial product keys.

Affirm Checkout

You must set the API key to the shared AffirmConfiguration once (preferably in your AppDelegate) as follows:

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

Checkout creation is the process in which a customer uses Affirm to pay for a purchase in your store. This process is governed by the AffirmCheckoutViewController object, which requires three parameters:

  • An AffirmCheckout object which contains details about the purchase itself
  • An AffirmCheckoutType which determines whether the checkout flow should use the SDK's built-in loading indicator and error modal to handle loading and error states in the checkout process or if the developer will handle these states manually.
  • An 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 as 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:

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

The flow ends once the user has successfully confirmed the checkout, canceled the checkout, or encountered an error in the process. In each of these cases, Affirm will send a message to the AffirmCheckoutDelegate along with additional information about the result.

Charge authorization

Once the checkout has been successfully confirmed by the user, the AffirmCheckoutDelegate object will receive a checkout token. This token should be forwarded to your server, which should then use the token to authorize a charge on the user's account. For more details about the server integration, see our API documentation.


Promotional Messaging

Affirm Promotional Messaging allows you to display the monthly payment price to inform customers about the availability of installment financing.

To display Affirm As Low As (ALA) promotional messaging, the SDK provides a custom AffirmAsLowAsButton that encapsulates the AffirmAsLowAs functionality in a button that handles all states and only requires the developer to add to their view and configure to implement. The AffirmALAButton is implemented as follows:

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: NSDecimal representation of the price of the product (or cart).
  • PromoId: Required value and provided to you by Affirm
  • affirmLogoType: Can be one of (AffirmLogoTypeName | AffirmLogoTypeText | AffirmLogoTypeSymbol | AffirmLogoTypeSymbolHollow)
  • affirmColor : Can be one of (AffirmColorTypeBlue | AffirmColorTypeBlack | AffirmColorTypeWhite)

Tapping on the ALA button automatically opens a product/site modal depending on whether ALA is enabled on the button.

To display the AffirmPromoModal outside of tapping on the AffirmALAButton you may initialize and display an instance of the promo modal VC as follows:

AffirmPromoModalViewController *promoVC = [AffirmPromoModalViewController promoModalControllerWithModalId:@"promo_id" amount:amount];
[self presentViewController:promoVC animated:YES completion:nil];
  • amount: NSDecimal representation of the price of the product (or cart).
  • PromoId: Required value and provided to you by Affirm

Sample Application

A demo app that integrates Affirm is included in the repository. To run it, run pod install and then open AffirmSDKDemo.xcworkspace in Xcode.


Test your Affirm configuration

Test your configuration to ensure that everything is working before you go live. Email  merchanthelp@affirm.com with a link to your test site so that we can verify your configuration and provide you with production keys.

  1. Add an item to the cart on your test site.
  2. Proceed to checkout.
  3. During checkout, enter valid U.S. addresses and mobile-phone information. Affirm cannot test your configuration if the address or phone information is fake.
  4. Select Affirm as the payment option.
  5. Proceed to Affirm's testing environment checkout.

Note: The URL https://sandbox.affirm.com indicates that you are in the testing environment.

6. When prompted for your security PIN, enter 1234.

7. Select terms.

8. Confirm your loan.

 

9. Wait to ensure that you have been redirected to your confirmation page.

10. Verify that the transaction appears in your platform's admin panel and on  sandbox.affirm.com/dashboard

Note: When a customer completes checkout with Affirm as the payment method, Affirm authorizes a charge for the amount of the order. The charge appears in a pending state on the customer’s Affirm account. Authorized transactions expire if they are not captured before the capture deadline. The default capture deadline is specified in your partnership agreement with Affirm. If you did not specify your authorization-period requirements because of inventory, pre-orders, or shipping time in your onboarding form, please email merchanthelp@affirm.com for help with completing this process.


Go live with Affirm financing

After you verify that your configuration is working properly in the Affirm Sandbox environment, your Affirm Client Success Manager will activate your Affirm Live environment access. This will allow you to sign into the Live version of the Merchant Dashboard, as well as access your Live API keys.

Retrieve Live API keys

  1. Go to the API keys page in the Affirm dashboard.
  2. Retrieve your live API keys.
  3. Enter the live API keys into your integration.
  4. Update the configurationWithPublicAPIKey and environment config to point to the production environment.