Virtual Card on iOS

📘
Check out the virtual card on android here.

Starting a payment with Affirm with a virtual card on an iOS client consists of creating a checkout form, tokenizing customer information, and generating a card. The card can then be used via your existing payment rails.

This guide shows you how to include iOS client on your checkout page.

The iOS SDK is open-source and fully documented.

Step 1: Set up Affirm on iOS

With CocoaPods

1. Install the latest version of CocoaPods.

2. If you don't have an exisiting Podfile, run the following command to create one:

pod init

3. Add this line to your Podfile:

pod 'AffirmSDK'

4. Run the following command:

pod install

Use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.
In the future, to update to the latest version of the SDK, just run:

pod update AffirmSDK

With Carthage

1. If you haven't already, install the latest version of Carthage.

2. Add this line to your Cartfile:

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

3. Follow the Carthage installation instructions.

4. In the future, to update to the latest version of the SDK, run the following command:

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

🚧
For details on the latest SDK release and past versions, see the Releases page on GitHub. Watch releases for the repository to receive notifications when a new release is published.

Step 2: Initialize Affirm

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

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

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

Step 3: Render Affirm checkout

Checkout creation is when a customer uses Affirm to pay for an in-app purchase. Use the following code snippet to create a checkout object and launch the Affirm checkout for a virtual card:

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.

Step 4: Handle callbacks

The AffirmCheckoutDelegate object which receives messages at various stages in the checkout process. It will return creditCard object containing the Affirm card details. You can also decide only to retrieve card details from your server-side if you have PCI concerns.

func vcnCheckout(_ checkoutViewController: AffirmCheckoutViewController, completedWith creditCard: AffirmCreditCard) {
        resultLabel.text = "Received credit card:\ncredit card id: \(creditCard.creditCardId)\ncheckout token: \(creditCard.checkoutToken)\ncard holder name: \(creditCard.cardholderName)\nnumber:\(creditCard.number)\ncvv: \(creditCard.cvv)\nexpiration: \(creditCard.expiration)\ncallback id: \(creditCard.callbackId)"
        checkoutViewController.dismiss(animated: true, completion: nil)
    }

- (void)vcnCheckout:(AffirmCheckoutViewController *)checkoutViewController completedWithCreditCard:(AffirmCreditCard *)creditCard

For more callbacks, please see the code reference.

👍
Once the checkout has been successfully confirmed by the user, the AffirmCheckoutDelegate object will receive a creditCard object. The card details should be forwarded to your server to be used with your existing card payment rails.