Pay.Cards Android with 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.

Embedding the library into the program

The library consists of two modules:

  • camera_card_recognition_library has no open API, but is required for the operation.

  • card_recognition_library_with_acquiring is a library with an open API with a graphical interface and an API designed to work with a gateway.

The library may be embedded into the program in two ways:

1.

By using Maven dependency manager or a build system compatible with it (Gradle).

For Maven, add the following strings to your pom.xml:

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_with_acquiring</artifactId>
                        <version>2.0.1</version>
                      </dependency>

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

Add the latest available library version to the ’version’ field.

For Gradle, add the following repository:

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

and dependencies:

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

All the required dependencies of the library will be added automatically.

2.

The libraries and their dependencies can be downloaded and added manually.

The libraries can be downloaded from the maven repository: http://pay.cards/maven/

Camera_card_recognition_library.aar and card_recognition_library_with_acquiring.aar shall be added to the project.

The libraries require specific 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'
                      

When adding the specified dependencies do not use the library versions lower than the specified ones and try to be careful with the higher versions due to possible changes in the API.

API classes

PayCardsHelper (import cards.pay.card_recognition_library.api.withacquiring) class

It contains ConfigBuilder class to configure the library.

A filled instance of OrderInfo is passed to a constructor of ConfigBuilder class.

Methods of ConfigBuilder class:

  • setProcessing(Processing processing) sets the server used for order processing. Default value - Processing.WALLET_ONE.

  • setReportLongPendingTransactions(boolean enable)set whether the library returns PENDING status for the orders processed over 30 seconds. If the value is false, the library will wait till the order is completed. The default value is false.

  • ConfigBuilder setSoundEnabled(boolean enableSound) enables or disables the sounds. The sounds are enabled by default.

  • ConfigBuilder setSaveCardEnabled(final boolean enable)sets whether cards are saved or not. Cards are saved by default.

The configured object of ConfigBuilder class shall be passed to one of the startScan methods:

  • void startPayment(final Fragment fragment, final ConfigBuilder configBuilder);

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

  • void startPayment(final Activity activity, final ConfigBuilder configBuilder);

Methods of PayCardsHelper class:

  • onActivityResult(final int requestCode, final int resultCode, final Intent data, final PayCardsCallbacks payCardsCallbacks) is a method to process payment results and call callbacks;

  • StatusOrder checkOrderStatus(Context context, long transactionId, String merchantId)

  • StatusOrder checkOrderStatus(Context context, long transactionId, String merchantId, Processing processing)

    Synchronous methods of order status validation.

  • void checkOrderStatusAsync(Context context, long transactionId, String merchantId, PayCardsCallbacks payCardsCallbacks)

  • void checkOrderStatusAsync(final Context context, final long transactionId, final String merchantId, final PayCardsCallbacks payCardsCallbacks, final Processing processing)

    Asynchronous methods of order status validation. These methods shall be called from the main thread. When order status validation is completed, one of the callbacks payCardsCallbacks will be called in the main thread.

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

It contains getters and setters for the fields required to complete an order. The underlined fields shall be filled out.

  • setWmiCurrencyId(int currencyId) – an identifier of payment currency in accordance with ISO 4217. The following currencies are supported: 643, 840, 978, 980, 974, 710, 398, 972;

  • setWmiPaymentAmount(BigDecimal amount) – order amount;

  • setCustomerId(String customerId) – user identifier in the application;

  • setWmiOrderId(String orderId) – order identifier in the accounting system of an online store/merchant. The value of this parameter shall be unique for each order. Order identifier shall be unique for every instance of the application;

  • setCustomerMail(String email) – user’s e-mail . It is mandatory if mCustomerPhone is not specified;

  • setCustomerPhone(String phone) – user’s phone number. It is mandatory if mCustomerMail is not specified;

  • setWmiMerchantId(String merchantId) – merchant identifier (wallet number) received during registration in processing;

  • setWmiDescription(String description) – order description;

  • setCustomerFirstName(String firstName) – user’s first name;

  • setCustomerLastName(String lastName) – user’s last name;

PayCardsCallbacks (import cards.pay.card_recognition_library.api.withacquiring) interface

It contains callbacks to transfer the results of payment to the calling fragment/activity.

  • void onOperationComplete(final StatusOrder statusOrder, long transactionId) is called after processing of a transaction is completed;

  • void onOperationCanceled() is called, if the user quits the library interface without completing the transaction;

  • void onOperationError(ErrorResponse error) is called if an error occurs during payment execution;

enum StatusOrder (cards.pay.card_recognition_library.data)

The list of possible transaction statuses:

  • SUCCESS – transaction is successful;

  • ERROR – transaction has been completed with an error;

  • PENDING – transaction is in process;

  • INCORRECT_INPUT_DATA – occurs if input data is incorrect (for example, not all fields are filled out or the currency is not supported);

  • CANCELED – transaction is cancelled;

  • UNKNOWN_STATUS – unknown transaction status.

ErrorResponse (cards.pay.card_recognition_library.data) class

It contains information on the reason for the transaction error.

Using library

1.

Connect ‘camera_card_recognition_library, card_recognition_library_with_acquiring’ and its dependencies to the library.

2.

Create and fill out an instance if OrderInfo class.

3.

Create an instance of PayCardsHelper.ConfigBuilder class and configure it with the help of the methods specified in the class description.

4.

Implement PayCardsCallbacks to accept the result of payment execution.

5.

Call one of the static methods PayCardsHelper.startScan().

6.

In the calling Fragment or Activity reload the onActivityResult method, pass its parameters and callbacks to PayCardsHelper.onActivityResult():

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

If PayCardsHelper.onActivityResult() returned false, you may continue processing your own requestCodes.

7.

If after the transaction processing, the order status is PENDING, you may check the order status later using the following methods: checkOrderStatus or checkOrderStatusAsync of PayCardsHelper class.

Testing

In order to test the library without making payment, the following reserved card numbers can be used:

1.

1111 1111 1111 1111 – transaction is always successful. The status StatusOrder.SUCCESS is returned.

2.

1111 1111 1111 1112 – transaction always ends with an error. The status StatusOrder.ERROR is returned.

3.

1111 1111 1111 1113 – transaction has the PENDING status. The status StatusOrder.PENDING is returned. The library reacts accordingly depending on the value passed in setReportLongPendingTransactions during initialization.