Pay.Cards Android without acquiring API documentation

Overview

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

Supported cards

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

Current version of library recognizes card number, expiration date and cardholder name.

Supported devices

Card recognition is not available on devices that show poor performance. In this case a user will be prompted to enter card data manually

Prerequisites

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

Adding the library to a project

The library consists of two modules:

  • camera_card_recognition_library - has no public API but is necessary for recognition.

  • card_recognition_library_no_acquiring - a library with a public API. Contains GUI and API for card data recognition.

There are two options to add the library to a project:

1.

Using dependency management system Maven, or a compatible build system such as Gradle.

If you use Maven, add following lines to your pom.xml file:

To the repository section:

                    <repository>
                     <id>pay.cards</id>
                     <name>Pay.Cards Android Repo</name>
                     <url>http://pay.cards/maven/</url>
                    </repository>
                  

To the dependency section:

                    <dependency>
                     <groupId>cards.pay</groupId>
                     <artifactId>card_recognition_library_no_acquiring</artifactId>
                     <version>2.0.1</version>
                    </dependency>
                  

Put the latest available library version number inside the version element.

If you use Gradle, add the following repository:

                    allprojects {
                     repositories {
                      maven { url "http://pay.cards/maven"}
                     }
                    }
                  

and dependencies:

                    dependencies {
                     compile 'cards.pay:card_recognition_library_no_acquiring:+'
                     compile 'cards.pay: camera_card_recognition_library:+'
                    }
                  

All other necessary dependencies will be added automatically

2.

You can download and include the libraries and dependencies manually.

The libraries are available in the maven repository: http://pay.cards/maven/

You need to include camera_card_recognition_library.aar and card_recognition_library_no_acquiring.aar files in a project.

The libraries require the following dependencies:

                    compile 'com.android.support:support-annotations:23.3.0'
                    compile 'com.google.code.gson:gson:2.6.2'
                    compile 'com.squareup.retrofit:retrofit:1.9.0'
                    compile 'com.squareup.okhttp:okhttp:3.2.0'
                    compile 'com.android.support:appcompat-v7:23.3.0'
                    compile 'de.greenrobot:eventbus:2.4.1'
                  

Do not use older versions of the libraries and be aware of using newer versions due to possible API changes.

API classes

ScanHelper class (import cards.pay.card_recognition_library.api.noacquiring)

Contains ConfigBuilder class, which is used to configure the library.

The constructor of the class takes initialized ScanAuthParams object.

ConfigBuilder class methods:

  • ConfigBuilder setRequestCVV(boolean requestCVV) - if set to true, a user will be asked for a CVV. Default value is true.

  • ConfigBuilder setSoundEnabled(boolean enableSound) - is used to turn the sound on and off. Default value is true.

  • ConfigBuilder setSaveCardEnabled(boolean enable) - if set to true, the card will be saved on the device for future use. Default value is true.

  • ConfigBuilder setSoundEnabled(boolean enableSound) - is used to turn the sound on and off. Default value is true.

After configuration, object of the ConfigBuilder class should be passed to one of the startScan methods:

  • void startScan(Fragment fragment, ConfigBuilder configBuilder);

  • void startScan(android.support.v4.app.Fragment fragment, ConfigBuilder configBuilder);

  • void startScan(Activity activity, ConfigBuilder configBuilder);

void sendPaymentResult(Context context, long scanId, boolean success) – this method is used to send the result of a payment made using data returned by the Pay.Cards library.

ScanAuthParams class (import cards.pay.card_recognition_library.api.noacquiring)

Contains the data necessary for card recognition: merchantId, scanMerchantId, scanMerchantPass – information about the merchant. clientId, clientEmail, clientPhone – information about the customer.

CardField enum (import cards.pay.card_recognition_library.api.noacquiring)

Enumeration that describes card fields. May be used in the setRequiredFields method to request only selected fields

  • CARD_TITLE - card title;

  • CARD_HOLDER - card holder name;

  • EXPIRATION_DATE - card expiration date;

  • ALL - all fields.

ScanCallbacks interface (import cards.pay.card_recognition_library.api.noacquiring)

Interface that is used to retrieve card recognition results.

  • void onCardSelected(CardInfo cardInfo, long scanId) - is called when a card is successfully selected or recognized. cardInfo contains card values. scanId is an identifier of what should be passed to sendPaymentResult method after payment if it is greater than 0.

  • void onCardSelectionError() - is called when an authorization error occurred.

  • void onCardSelectionCancelled() - is called when a user cancels card recognition.

CardInfo class (import cards.pay.card_recognition_library.api.noacquiring)

Contains getters:

  • Card getCard() - contains card data.

  • String getCvv() - contains CVV entered by a user.

Card class (import cards.pay.card_recognition_library.data)

Contains fields that describe a card.

  • String getCardId() - card id;

  • String getCardName() - card title, entered by a user;

  • String getColor() - card color in "#FFFFFF" format;

  • String getColorHEX() - card color in "FFFFFF" format;

  • String getCardNumber() - card number (only digits);

  • String getNumberCardFormatNoHide() - returns card number formatted with spaces;

  • String getCardNumberFormatted() - returns wildcarded card number;

  • String getCardHolderName() - card holder name;

  • String getExpirationDate() - card expiration date in "MM/yy" format.

Usage

1.

Include libraries camera_card_recognition_library and card_recognition_library_no_acquiring into a project.

2.

Create a ScanAuthParams object and fills necessary fields.

3.

Create a ScanHelper.ConfigBuilder object and configure it.

4.

Implement the ScanCallbacks interface to be able to retrieve the PayCards library results.

5.

Call one of ScanHelper.startScan()methods to start card recognition.

6.

In the onActivityResult method of you Fragment or Activity call the ScanHelper.onActivityResult() method.

                @Override
                protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
                   super.onActivityResult(requestCode, resultCode, data);
                   if (!ScanHelper.onActivityResult(requestCode, resultCode, data, this)) {
                       // process your request codes here
                   }
                }
              
7.

If the scanId passed to the onCardSelected method is greater than 0, after processing a payment using card data retrieved from the library, send payment result to the Pay.Cards server to improve recognition technology. Use the ScanHelper.sendPaymentResult() method.