iOS integration guide
Scan a payment card with CardScan for iOS.
- Objective C or Swift 4.0 or higher
- Xcode 11 or higher
- iOS 11 or higher for integration
- iOS 11.2 or higher for using the scanning view controllers
- iOS 13 or higher for name and expiration extraction
We have a repo on github that includes examples of using CardScan with both Cocoapods and Swift Package Manager. Please see that repo for more details.
CardScan defaults to a
formSheet for the iPad, which handles all screen orientations and autorotation correctly. However, if you'd like to use CardScan in full screen mode instead, make sure to select the Requires full screen option in your Info.plist file via XCode, or else non-portrait orientations won't work.CardScan is available through CocoaPods and Swift Package Manager. With version 2.0 we dropped support for Carthage. If you require Carthage support we suggest moving to Swift Package Manager or reach out and we'll try to work with you.
In our deployments we use XCFrameworks to encapsulate our code and resources. XCFrameworks have the advantage of faster compilation times and simplified bundle management, but if you need source we make it available in our CardScan repo.
CocoaPods
Swift Package Manager
Add the following line to your Podfile:
pod 'CardScan'
Or if you're using Stripe:
pod 'CardScan'
pod 'CardScan/Stripe'
Next, install the new pod. From a terminal, run:
pod install
When using Cocoapods, you use the
.xcworkspace instead of the .xcodeproj. Again from the terminal, run:open YourProject.xcworkspace
To use Swift Package Manager, in Xcode add the
https://github.com/getbouncer/cardscan-ios.git repo and choose the latest version up to the next major version. For example, if CardScan is on version 2.0.2 then you'd select 2.0.2 - Next MajorCardScan uses the camera, so you'll need to add an description of camera usage to your Info.plist file:
XCode iOS camera permission
The string you add here will be what CardScan displays to your users when CardScan first prompts them for permission to use the camera.
iOS camera prompt
Alternatively, you can add this permission directly to your Info.plist file:
<key>NSCameraUsageDescriptionkey>
<string>We need access to your camera to scan your cardstring>
CardScan can be configured and run through Swift or Objective-C. CardScan requires an API key, which can be generated for your app through the Bouncer API console.
The CardScan SDK will send anonymous stats to Bouncer's servers. This code snippet shows what we send.
Swift
Objective C
Configure the library when your application launches by adding CardScan to your
AppDelegate.swift file. If you are planning to use a navigation controller or support rotation, also be sure to add supportedOrientationMaskOrDefault.import UIKit
import CardScan
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?
) -> Bool {
ScanViewController.configure(apiKey: "<your_api_key_here>")
// do any other necessary launch configuration
return true
}
func application(
_ application: UIApplication,
supportedInterfaceOrientationsFor window: UIWindow?
) -> UIInterfaceOrientationMask {
// if you are planning to embed scanViewController into a navigation
// controller, put this line to handle rotations
return ScanBaseViewController.supportedOrientationMaskOrDefault()
}
}
Configure the library when your application launches by adding CardScan to your
AppDelegate.m file.#import "AppDelegate.h"
@import CardScan;
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// if you need to get an API key you can get one from here:
// https://api.getbouncer.com/console
[ScanViewController configureWithApiKey:@"<your_api_key_here>"];
return YES;
}
@end
To use CardScan, create a
ScanViewController, display it, and implement the ScanDelegate protocol to receive results from the scan.Swift
Objective C
import UIKit
import CardScan
class ViewController: UIViewController, ScanDelegate {
override func viewWillAppear() {
super.viewWillAppear()
// It's important that this goes in viewWillAppear because the user may
// deny permission on the ScanViewController, in which case the button
// must be hidden to avoid future presses.
if !ScanViewController.isCompatible() {
// Hide your "scan card" button because this device isn't compatible
// with CardScan
}
}
@IBAction func scanCardButtonPressed() {
guard let vc = ScanViewController.createViewController(withDelegate: self) else {
print("This device is incompatible with CardScan")
return
}
self.present(vc, animated: true)
}
func userDidSkip(_ scanViewController: ScanViewController) {
self.dismiss(animated: true)
}
func userDidCancel(_ scanViewController: ScanViewController) {
self.dismiss(animated: true)
}
func userDidScanCard(
_ scanViewController: ScanViewController,
creditCard: CreditCard
) {
let number = creditCard.number
let expiryMonth = creditCard.expiryMonth
let expiryYear = creditCard.expiryYear
// If you're using Stripe and you include the CardScan/Stripe pod, you
// can get `STPCardParams` directly from CardScan `CreditCard` objects,
// which you can use with Stripe's APIs
let cardParams = creditCard.cardParams()
// At this point you have the credit card number and optionally the
// expiry. You can either tokenize the number or prompt the user for
// more information (e.g., CVV) before tokenizing.
self.dismiss(animated: true)
}
}
#import "ViewController.h"
@import Stripe;
@interface ViewController ()
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
if (![ScanViewController isCompatible]) {
// Hide the "scan card" button because this device isn't compatible
// with CardScan
}
}
- (IBAction)scanCardPress:(id)sender {
UIViewController *vc = [ScanViewController createViewControllerWithDelegate:self];
[self presentViewController:vc animated:YES completion:nil];
}
- (void)userDidSkip:(ScanViewController * _Nonnull)scanViewController {
[self dismissViewControllerAnimated:YES completion:nil];
}
- (void)userDidCancel:(ScanViewController * _Nonnull)scanViewController {
[self dismissViewControllerAnimated:YES completion:nil];
}
- (void)userDidScanCard:(ScanViewController * _Nonnull)scanViewController creditCard:(CreditCard * _Nonnull)creditCard {
NSString *number = creditCard.number;
NSString *expiryMonth = creditCard.expiryMonth;
NSString *expiryYear = creditCard.expiryYear;
// If you're using Stripe and you include the CardScan/Stripe pod, you can
// get `STPCardParams` directly from CardScan `CreditCard` objects, which
// you can use with Stripe's APIs
STPCardParams *cardParams = [creditCard cardParams];
// At this point you have the credit card number and optionally the expiry.
// You can either tokenize the number or prompt the user for more
// information (e.g., CVV) before tokenizing.
[self dismissViewControllerAnimated:YES completion:nil];
}
@end
Though CardScan supports several cards, you may need to add support for cards specific to your business, instructions can be found in the card support docs.
Sam King, Jaime Park, Zain ul Abi Din, Adam Wushensky, and Andy Li
This library is available under paid and free licenses. See the LICENSE file for the full license text.
In short, this library will remain free forever for non-commercial applications, but use by commercial applications is limited to 90 days, after which time a licensing agreement is required. We're also adding some legal liability protections.
After this period commercial applications need to convert to a licensing agreement to continue to use this library.
- Details of licensing (pricing, etc) are available at
What's allowed under the license:
- Free use for any app for 90 days (for demos, evaluations, hackathons, etc).
- Contributions (contributors must agree to the
- Any modifications as needed to work in your app
What's not allowed under the license:
- Commercial applications using the license for longer than 90 days without alicense agreement.
- Using us now in a commercial app today? No worries! Just emailup.
- Redistribution under a different license
- Removing attribution
- Modifying logos
- Indemnification: using this free software is ‘at your own risk’, so you can’tsue Bouncer Technologies, Inc. for problems caused by this library
Last modified 1yr ago