Pay.Cards iOS without acquiring API documentation

Overview

Pay.Cards is a framework that is responsible for automatic recognition of bank card data using built–in camera on iOS devices. Card data recognition algorithm is based on artificial neural networks.

Supported cards

Pay.Cards framework currently support recognition of an embossed bank cards only.

Current version of framework recognize card number, expiration date & card holder name on devices iPhone 5 and higher. Cardholder name recognition is not supported on iPhone 4S.

Prerequisites

Merchants should complete Pay.Cards Registration Form and obtain their MERCHANT_ID and MERCHANT_PASSWORD values.

API Classes

  • PCDConfigurationManager

    Allows user to configure framework. Includes the following settings:

    1.

    PCDLocalization localization – framework localization

    2.

    BOOL soundEnabled. YES by default.

    3.

    BOOL collectCVV – indicate if user will be asked to enter the CVV code after scan. YES by default.

    4.

    BOOL saveCard – indicate if a recognized card will be saved. Cards's data is stored in iOS Keychain and can be used by the client with the same ClientId for future payments. YES by default.

    5.

    BOOL storeCVV – indicate if a card’s CVV will be stored in iOS Keychain. For future payments, saved CVV can be obtained after entering passcode or Touch ID. YES by default.

    6.

    PCDRequiredCardFields requeriedCardFields – combination of the elements of the following enum:

                            typedef NS_OPTIONS(NSInteger, PCDRequiredCardFields) {
                              PCDRequiredCardFieldHolderName = 1 << 0,
                              PCDRequiredCardFieldExpireDate = 1 << 1,
                              PCDRequiredCardFieldCardName = 1 << 2,
                              PCDRequiredCardFieldAll = PCDRequiredCardFieldHolderName |
                              PCDRequiredCardFieldExpireDate | PCDRequiredCardFieldCardName
                            };
                          

    Indicate which fields (holder name, expiration date, card name) of the recognized card should be shown after the recognition. Default value is PCDRequiredCardFieldAll.

  • PCDCardScanViewController

    View controller that allows user to perform two steps:

    1.

    Scan card's number and expiration date (Scanner View):

    2.

    Scan card's number and expiration date (Scanner View):

  • PCDMerchant

    Entity class to represent an info about a merchant.

  • PCDScanResultsManager

    Allows user to leave feedback if scanned data was correct or not.

Installation

1.

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

                  $ gem install cocoapods
                

To integrate PayCardsAcquiring into your Xcode project using CocoaPods, specify it in your Podfile:

                  source 'https://github.com/CocoaPods/Specs.git'
                  platform :ios, '7.0'
                  use_frameworks!
                  target "Your Target Name" do
                  pod 'PayCardsAcquiring', :git => 'https://github.com/paycardssdk/PayCardsAcquiring.git', :branch => 'master'
                  end
                

Then, run the following command:

                  $ pod install
                
2.

Manually

Add the PayCardsNoAcquiring.framework to Embedded Binaries

Add the PayCardsNoAcquiring.framework to Linked Frameworks and Libraries

Add the CRNResources.bundle to Copy Bundle Resources

Usage

1.

Before the first lib usage configure PCDConfigurationManager (example):

                  [PCDConfigurationManager sharedInstance].localization = PCDLocalizationEN;
                  [PCDConfigurationManager sharedInstance].soundEnabled = NO;
                  [PCDConfigurationManager sharedInstance].collectCVV = YES;
                  [PCDConfigurationManager sharedInstance].requeriedCardFields = PCDRequiredCardFieldHolderName | PCDRequiredCardFieldExpireDate; //show Holder Name and Expiration Date fields
                

In your presenting view controller class import the following:

                  #import <PayCardsNoAcquiring/PayCardsNoAcquiring.h>
                
2.

Create PCDMerchant object:

                  PCDMerchant *merchant = [PCDMerchant new];
                  merchant.ID = MERCHANT_ID; //Merchant's ID. Should be obtained after a registration (see Prerequisites). Mandatory field.
                  merchant.password = MERCHANT_PASSWORD; //Merchant's password. Should be obtained after a registration (see Prerequisites). Mandatory field.
                  merchant.clientId = CLIENT_ID; //Client's ID in Merchant's system. Mandatory field.
                  merchant.email = CLIENT_EMAIL; // Client's email. Can be empty.
                  merchant.phone = CLIENT_PHONE; //Client phone. Can be empty.
                
3.

The following method is used to display the controller:

                  [PCDCardScanViewController presentOnViewController:(UIViewController *)viewController
                  merchant:merchant delegate:self verificationComplete:^(NSError *error) {}];
                  //viewController is the controller on which the payment screen will be displayed
                  //merchant property is necessary, otherwise error will occur
                  //delegate enables the tracking of the payment status
                
4.

Realize PCDCardScanViewControllerDelegete methods:

                  /*
                  fires when card recognition finishes successfully

                  Card Info example:
                  {
                    cardParams = {
                      cardName = My Card;
                      expireDate = "2015-09-01T00:00:00";
                      holderName = John Doe;
                      number = 4111111111111111;
                    };
                    scanId = 113;
                  }

                  scanId parameter is used to report if recognized data is correct or not.
                  */

                  - (void)cardScanViewController:(PCDCardScanViewController *)cardScanViewController didFinishScanWithInfo:(NSDictionary *)cardInfo;

                  /*
                    fires when error occurs
                  */
                  - (void)cardScanViewController:(PCDCardScanViewController *)cardScanViewController didCloseWithError:(NSError *)error;

                  /*
                    fires when user interrupts recognition tapping Back button
                  */
                  - (void)userDidCloseCardScanViewController:(PCDCardScanViewController *)cardScanViewController;
                
5.

When scan is completed, client’s application should send a feedback if the data recognized was correct or not. To identify scanned card, scanId parameter (received in card info in step 4) is used:

                  /*
                    Report if card data was recognized correctly or not.
                  */
                  [
                    PCDScanResultsManager reportStatusForScanId:scanId
                    succesfull:YES
                    completion:^(NSDictionary *responseData, NSError *error) {
                      //completion code
                    }
                  ];
                

App Transport Security

For iOS 9 add to your Info.plist

            <dict>
              <key>NSAppTransportSecurity</key>
              <dict>
                <key>NSAllowsArbitraryLoads</key>
                <true/>
              </dict>
            </dict>
          

Security

  • pay.cards framework doesn't send client's card data anywhere besides app using it

  • payment transaction's security should be guaranteed by the developer of the final mobile app

  • processing center where merchant will send a card's data for the authorization has to satisfy PCI DSS standard

  • recognized card’s data is encrypted using AES-128 algorithm and stored in iOS Keychain.

  • card’s CVV is stored in iOS Keychain and protected by device’s passcode (Touch ID)

Limitations

Device should be connected to the Internet to authenticate Merchant credentials. Internet connection is used to send a special files on pay.cards server intended to future improvement of recognition quality (about 20K of traffic for one scan operation).

Pay.Cards framework may be used only on iOS version 7 and higher and designed to use on iPad 2+ and iPhone 4S+ devices.