Pay.Cards iOS with acquiring API documentation

Introduction

PAY.CARDS is a framework, which permits the reading of data on bank cards by means of a camera integrated into iOS devices and the conducting of withdrawal operations using these cards. The algorithms of recognition of these cards are based on a neural network.

Supported cards

The current version of PAY.CARDS permits the scanning and recognition of only embossed bank cards used by the Visa and MasterCard systems. It can scan and recognize card numbers, the cardholder's name and card's month and year of expiration.

The CVC/CVV must be entered manually by a user.

Before use

The following organizational and technical steps must be carried out in order to begin using the framework:

  • The merchant must first register with Wallet One Checkout and receive a merchant ID

  • The merchant must coordinate one of the payment methods with the Wallet One Checkout commercial manager and sign an agreement;

  • After signing the agreement, the Wallet One Checkout commercial manager will configure and activate that payment method for the merchant’s account.

API Classes

  • PCD Configuration

    This class contains the configuration data. The data must be entered in the class field before creating a payment and receiving a payment status.

    Mandatory fields: Merchant ID

  • PCD Payment View Controller

    The View Controller permits making payment for an order. The View Controller is inside the UINavigationController. It reports payment completion through PCDPaymentViewControllerDelegete.

    Mandatory fields: Payment

  • PCD Customer

    This class contains the customer's information. It is used when creating a PCD Payment.

    Mandatory fields: ID, telephone number or e-mail address

  • PCD Payment

    This class contains information on the payment being made. All the fields are mandatory.

  • PCD Transaction History

    This class displays the transaction status using the transaction ID. Transaction ID returns PCDPaymentViewController through PCDPaymentViewControllerDelegete in the event of successful completion of the transaction.

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 PayCardsAcquiring.framework to Embedded Binaries

Add the PayCardsAcquiring.framework to Linked Frameworks and Libraries

Add the CRNResources.bundle to Copy Bundle Resources

Use

1.

Configuration:

Import the following header file into the View Controller's file, from which the scanning form will be retrieved:

                  #import <PayCardsAcquiring/PayCardsAcquiring.h>
                
2.

Before using this framework, set the global data by means of the PCDConfiguration

                  [PCDConfiguration sharedInstance].merchantId = @"112233445566";
                  // Merchant’s ID resultant after registration in Wallet One Checkout
                  [PCDConfiguration sharedInstance].culture = PCDCultureEN;
                  //PCDCulture specifies the language of the framework UI. The following cultures are available:
                  //PCDCultureEN
                  //PCDCultureRU
                  //PCDCultureES
                  //PCDCultureFR
                  //PCDCultureIT
                  //PCDCulturePT
                  //PCDCultureUA
                  //PCDCultureZH
                  [PCDConfiguration sharedInstance].soundEnabled = YES;
                  [PCDConfiguration sharedInstance].saveCard = YES;
                  // This manages the saving of the user's bank card for further payments. YES by default.
                  [PCDConfiguration sharedInstance].storeCVV = YES;
                  // This manages the saving of the bank card's CVV in the iOS Keychain. In the future, the user will be offered to use the TouchID instead of entering the CVV manually when making a payment (available only on iOS version 8 and later).
                
3.

To make a payment, icreate the class instance PCDPayment

                  PCDPayment *payment = [PCDPayment new];
                  // all the fields are mandatory

                  payment.orderDescription = “Air ticket payment”;
                  // order description
                  payment.amount = @(3)
                  // the sum, without the merchant’s commission
                  payment.currencyCode = PCDCurrencyCodeUSD;
                  // payment currency

                  //Supported currencies:
                  //PCDCurrencyCodeUSD
                  //PCDCurrencyCodeEUR
                  //PCDCurrencyCodeKZT
                  //PCDCurrencyCodeZAR
                  //PCDCurrencyCodeTJS
                  //PCDCurrencyCodeBYR
                  //PCDCurrencyCodeUAH
                  //PCDCurrencyCodeRUB

                  payment.orderNumber = @"123321";
                  // The order identifier in the merchant’s e-shop record-keeping system. The value of this parameter must be unique for each order. The order identifier must be unique for all the application instances.

                  PCDCustomer *customer = [PCDCustomer new];

                  customer.ID = @"12345"
                  // A mandatory field, which identifies the end user in the merchant’s record-keeping system. The framework uses this parameter to determine which bank cards must be loaded from the server and shown on the interface.
                  // The end user phone number or email should be indicated

                  customer.email = @"customer@email.com";
                  customer.phoneNumber = @"9998880000";
                  customer.firstname = @"John";
                  customer.lastname = @"Smith";
                  payment.customer = customer;

                
4.

After creating a payment, create PCDPaymentViewController instance and enter the value of PCDPayment class object (created in step 3) in the payment property.

                  PCDPaymentViewController *paymentVC = [PCDPaymentViewController new];
                  paymentVC.payment = payment;
                
5.

The following method is used to display the controller:

                  [PCDPaymentViewController presentOnViewController:(UIViewController *)viewController payment(PCDPaymentViewController *)paymentVC delegate:(id<PCDPaymentViewControllerDelegete>)delegate completion:^{ }];
                  //viewController is the controller on which the payment screen will be displayed
                  //delegate enables the tracking of the payment status
                  //completion is a block that will be fetched upon completion of animation of the payment screen display
                
6.

To process a payment, it’s necessary to realize PCDPaymentViewControllerDelegate

                  // this is retrieved upon completion of the payment by a user or if an incorrect PCDPayment copy has been submitted.

                  - (void)paymentViewController:(PCDPaymentViewController *)paymentViewController didCompletePayment:(PCDPayment *)payment transactionId:(NSString *)transactionId error:(NSError *)error {}
                  //is fetched when the user calls the payment back by clicking  back button.

                  - (void)paymentViewController:(PCDPaymentViewController *)paymentViewController didCancelPayment:(PCDPayment *)payment {}
                  //Sometimes, a payment can be under processing for a long time. In this case, the following method is fetched:

                  - (void)paymentViewController:(PCDPaymentViewController *)paymentViewController didGetProccesingStateForPayment:(PCDPayment *)payment transactionId:(NSString *)transactionId error:(NSError *)error
                

In these three situations (transaction completion, payment refusal, long transaction processing), the framework screen does not hide automatically. To complete the framework work, iretrieve the following method:

                  - (void) dismissWithCompletion:(void (^)(void))completion
                  //completion is a block that is retrieved after the framework screen is hidden
                

If a payment is processed for a long time and the method is fetched, the application can display the final status by means of PCDTransactionHistory

                  - (void) paymentViewController:(PCDPaymentViewController *)paymentViewController didGetProccesingStateForPayment:(PCDPayment *)payment transactionId:(NSString *)transactionId error:(NSError *)error;

                  [PCDTransactionHistory requestTransactionStatusByTransactionId:@"123456789" completion:^(PCDPaymentTransactionStatus status, NSError *error) {}];
                

Possible statuses:

  • PCDPaymentTransactionStatusUnknown

    This transaction status is unknown or was not received. In this case, check the error. If the error is missing, try later.

  • PCDPaymentTransactionStatusCreated

    This transaction has been created.

  • PCDPaymentTransactionStatusAuthRequired

    3DS authentication is required for this transaction.

  • PCDPaymentTransactionStatusPending

    This transaction is being processed.

  • PCDPaymentTransactionStatusSuccess

    This transaction has been successfully completed.

  • PCDPaymentTransactionStatusError

    This transaction has failed.

Only PCDPaymentTransactionStatusSuccess and PCDPaymentTransactionStatusError statuses are final. All others are temporary. In the event of receipt of a temporary status, repeat the status request.

Restrictions

To carry out payment transactions in the Pay.Cards framework, you need Internet access.


The PAY.CARDS framework can be accessed only from iOS version 7 or later. The framework interface design was adapted only for iPad 2 or later, and for iPhone 4S and later.


The framework works on devices earlier than iPad2 and iPhone 4S, but does not offer the possibility of automatic scanning bank card data, i.e. a user has to enter the card data manually.

App Transport Security

For iOS 9 add to your Info.plist

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

Security

Communication of the PAY.CARDS framework with a server is carried out only through coded connections (HTTPS). An extended Validation SSL certificate is used for server authorization. The server and the application infrastructures correspond to the PCI DSS standard.


The customer-facing application does not receive or process any user bank card data, therefore no certification requirements are required by international payment systems.


Besides retrieving the payment status provided by the PAY.CARDS framework for the merchant API, the option of server notification on payment completion by Wallet One is available (see section 5 of the API documentation of Wallet One