SDK for Android

SDK for Android is a software development kit for fast integration of the ECommPay payment solutions right in your mobile application for Android. With SDK for Android, you can quickly build and offer you customers a fast checkout experience from inside of your Android app. In this section you will find information about using SDK for Android (SDK version 1.8) as well as Java and Kotlin code samples.

Requirements for using SDK for Android

SDK for Android may be embedded in mobile applications developed for Android version 4.2 (API Level: 17) or later. The screen resolution of the mobile device must be at least 480x800 pixels.

Download link

Starting with the version 1.7.0, the SDK for Android libraries can be imported via JCenter. For more information, see the Importing libraries via JCenter section.

You can also download SDK for Android from GitHub. Use the following links to download SDK for Android:

General information about SDK for Android

What can I do with SDK for Android?

The SDK for Android allows you to perform purchases by using payment cards and alternative payment methods. You may perform one-step and two-step purchases and COF purchases using payment cards, as well as card verification (more). The SDK for Android supports the following alternative payment methods:
In terms of SDK for Android, the ECommPay payment form is used and the following features are available:
  • Support for English and Russian. Default language is English; the payment form uses Russian only when Russian is selected as the user interface language in the mobile device settings. For the merchant it is also possible to select the language of the payment form.
  • Customisation of payment form (more).
  • Support for different ways to enter card data (more):
    • manually
    • card scanning
    • choosing saved card
    • using preselected card
  • Gathering or passing additional customer data for further analysis (more).
  • Clarification of additional parameters required for payment (more).
  • Support for 3‑D Secure 2 authentication. 3‑D Secure 2 is a new version of 3‑D Secure (Three-Domain Secure) protocol, which is intended to secure e-commerce card payments (more).
  • Support for additional attempts to perform payments (more).
  • Getting information about the payment. On all pages of the payment form there is an information button; when tapped, this button shows information about the ID, the amount, the date of the payment and payment description.
  • Sending receipts to the customer (more).

What's inside?

SDK for Android contains the following:
  • ecommpaySDK.aar—the Android library file with the payment form implementation
  • Java and Kotlin code samples

Payment workflow

After you integrate the SDK for Android library into your Android app, checkout payment is processed as follows:
  1. Your client app creates an instance of payment object with all the necessary checkout details.
  2. On the basis of the payment object parameters, the back end part of you app generates the signature for checkout request.
  3. You call a special method of the payment object to have the client app initiate a checkout request and send it to the ECommPay payment platform.
  4. The ECommPay payment platform processes the checkout request and performs the payment.
  5. The payment platform sends the payment processing results to the client app.
  6. The payment platform sends a callback with the payment processing results to the callback URL you specified.

Figure: Interaction diagram



Using SDK for Android

To start using SDK for Android you need to complete the following tasks:
  1. Make sure you have you have ready your merchant ID and secret key obtained from ECommPay.
    1. If your company has never obtained any ID or secret key from ECommPay, you need to submit an application for connecting to the ECommPay payment platform.
    2. If your company already has an ID and a secret key to sign messages obtained from ECommPay, you need to notify ECommPay customer support that you want to use SDK for Android and consult with the customer support on how to arrange a test run.
  2. Integrate the ECommPay payment solution in your app:
    1. Download SDK for Android.
    2. Import the SDK for Android library into your client app and implement the following functionality: collection of payment details, preparation of data for signing checkout request, opening payment form, and submitting request to the payment platform for payment results.
    3. Implement the checkout request signing functionality on the back end side of your mobile app.
  3. Test and put in production mode.
    1. Request test card numbers and test merchant ID from ECommPay and debug and test your app.
    2. Once testing is complete, request your production merchant ID from ECommPay and put your app in production mode.

With any questions regarding usage of SDK for Android contact ECommPay technical support service.

Payment form interface

Figure: Payment form with all supported payment methods



Figure: Payment by using the DOKU payment method



Figure: Card verification



Figure: Selecting saved card



Figure: Token generation



Figure: Using preselected card



Figure: Clarification of additional parameters required for payment



Figure: Support for additional attempts to perform payments



Signature generation

To verify data integrity and authenticate the messages your application exchange with the ECommPay payment platform, all the messages need to be signed. You must sign all your outgoing messages (for example, checkout request) and check signatures of all the incoming messages (for example, callbacks). Before generating signature, you need to prepare the payment data by packing all the payment parameters into a single string. The string is generated on the client side where you can use SDK for Android for this purpose. The signing process requires the secret key provided by ECommPay therefore the signing procedure must be performed on the back end side of your app.

Figure: Data signing procedure



Once you generate the string to sign on the basis of all the payment parameters, do the following:
  1. Generate the HMAC value based on the SHA-512 hashing algorithm and your secret key.
  2. Encode the result of step1 using Base64.
Use the following example to test whether your code correctly generates signatures:
  • Input data
    • Sample string to sign:
      customer_id:5;payment_amount:30;payment_currency:RUB;payment_id:payment1;project_id:115
    • Sample secret key: 12345
  • Result: generated signature:
    pVmAtGFBQJD2NgLToP1B2elR4QROiYGi3IobPD9PFDfrkjBqdSCFgrVSEtebVJUzOUUHX5tPnHQq9RMn61679A==

The signature your back end generates based on the sample string and the secret key must be exactly the same as of the sample generated signature.

We recommend choose specific implementation of the signing algorithm based on the programming environment you use. For the detailed information about signature generation, see Signature generation and verification.

Importing libraries

Importing libraries in your project

Listed below are the instructions on how to import the ecommpaySDK.aar library into your application.
  1. Download the ecommpaySDK.aar file.
  2. Add the ecommpaySDK.aar file into your project.

    To do this is in Android Studio 3.0, go to File > New > New Module, select Import .JAR/.AAR Package, browse to the ecommpaySDK.aar file, and select the file.

  3. Open your application module (build.gradle).
  4. In the android {} section, add the following compilation parameters:
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
  5. In the dependencies {} section, add the following dependencies:
    implementation project(path: ':ecommpaySDK')
     
    implementation 'io.card:android-sdk:5.5.1'
     
    implementation 'com.squareup.retrofit2:retrofit:2.3.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.10.0'
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support:support-v4:28.0.0'
    implementation 'com.android.support:recyclerview-v7:28.0.0'
     
    implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
    implementation 'com.google.code.gson:gson:2.8.4'
     
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.10"
     
    implementation "android.arch.lifecycle:viewmodel:1.1.1"
    implementation "android.arch.lifecycle:extensions:1.1.1"
    annotationProcessor "android.arch.lifecycle:compiler:1.1.1"

    If some of the dependencies are already added in the dependencies {} section, do not add them again.

  6. Add the following permissions in the AndroidManifest.xml file:
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Importing libraries via JCenter

To import the libraries via JCenter, you need to do the following:
  1. Open your application module (build.gradle) and add the following string to the dependencies {} section:
    implementation 'com.ecommpay:paymentpage-sdk-android:1.7.0'
  2. In the android {} section, add the following compilation parameters:
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
  3. In the dependencies {} section, add the following dependencies:
    implementation project(path: ':ecommpaySDK')
     
    implementation 'io.card:android-sdk:5.5.1'
     
    implementation 'com.squareup.retrofit2:retrofit:2.3.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.10.0'
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support:support-v4:28.0.0'
    implementation 'com.android.support:recyclerview-v7:28.0.0'
     
    implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
    implementation 'com.google.code.gson:gson:2.8.4'
     
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.10"
     
    implementation "android.arch.lifecycle:viewmodel:1.1.1"
    implementation "android.arch.lifecycle:extensions:1.1.1"
    annotationProcessor "android.arch.lifecycle:compiler:1.1.1"

    If some of the dependencies are already added in the dependencies {} section, do not add them again.

  4. Add the following permissions in the AndroidManifest.xml file:
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Opening payment form

This section contains samples of payment form invocation code in Java and Kotlin.

Opening payment form in Java

To open payment form, do the following:

  1. Create an instance of the ECMPPaymentInfo class with all the required parameters and any number of optional parameters, for example (required parameters are highlighted with bold optional parameters highlighted with italic):
    ECMPPaymentInfo paymentInfo = new ECMPPaymentInfo(
                  115,          // Project ID
                  "pid42582512", // Payment ID, must be unique within the project
                  1999,          // Payment amount in minor currency units
                  "USD"          // Payment currency
                  "T-shirt with dog print", // Payment description
                  "10",         // Customer identifier in your project
                  "US"          // Region code
    
                        );

    Here are the required parameters:

    • projectID—project (merchant) ID ECommPay assigned you
    • paymentID—payment ID, must be unique within the project
    • paymentAmount—payment amount in minor currency units
    • paymentCurrency—payment currency code according to ISO-4217 alpha-3

    Here are the optional parameters:

    • recurrentInfo—object with the details of COF payment (more)
    • paymentDescription—payment description (this parameter is available not only to the merchant, but also to the customer; if paymentDescription is specified in the request, it is visible to the customer in the payment form (in the dialog box with information about the payment); if this parameter is not specified in the request, it is not visible to the customer)
    • customerID—customer ID
    • regionCode—customer country
    • ActionType—action type (Sale (by default), Auth, Tokenize, or Verify
    • token—card token
    • forcePaymentMethod—the identifier of the payment method which is opened to the customer without an option for the customer to select another payment method. The list of codes is provided in the IDs of payment methods supported on Payment Page section
    • hideSavedWallets—hiding or displaying saved payment instruments in the payment form. Possible values:
      • true—saved payment instruments are hidden, they are not displayed in the payment form
      • false—saved payment instruments are displayed in the payment form
    • ECMPScreenDisplayMode—object to manage display of the final page of the payment form and hide the final page if necessary. The following parameters can be passed in the object:
      • hide_success_final_page—the final page with the message about the performed payment is not displayed in the payment form
      • hide_decline_final_page—the final page with the message about the declined payment is not displayed in the payment form

      The following is an example of specifying the hide_success_final_page and hide_decline_final_page parameters in the request:

      // Init ECMPPaymentInfo
       
      paymentInfo.addEcmpScreenDisplayMode("hide_success_final_page")
                 .addEcmpScreenDisplayMode("hide_decline_final_page");
  2. Once all the payment parameters are collected, pack the parameters into a string for signing:

    paymentInfo.getParamsForSignature();
  3. Send the string to your back end.
  4. Have your back end generate the signature on the basis of the string and your secret key.
  5. Send the signature to the client app and add it in the paymentInfo object:
    paymentInfo.setSignature(<signature>);
  6. Open the payment form by using the following code:
    startActivityForResult(ECMPActivity.buildIntent(this,
                        paymentInfo),
                        PAY_ACTIVITY_REQUEST);

Opening payment form in Kotlin

To open payment form, do the following:

  1. Create an instance of the ECMPPaymentInfo class with all the required parameters and any number of optional parameters, for example (required parameters are highlighted with bold optional parameters highlighted with italic):
    val paymentInfo = ECMPPaymentInfo(
                  115,              // Project ID
                  "pid42582512",    // Payment ID, must be unique within the project
                  1999,             // Payment amount in minor currency units
                  "USD"             // Payment currency
                  "T-shirt with dog print", // Payment description
                  "10",            // Customer identifier in your project
                  "US"):           // Region code

    Here are the required parameters:

    • projectID—Project (merchant) ID ECommPay assigned you
    • paymentID—Payment ID, must be unique within the project
    • paymentAmount—Payment amount in minor currency units
    • paymentCurrency—Payment currency code according to ISO-4217 alpha-3

    Here are the optional parameters:

    • recurrentInfo—object with the details of COF payment (more)
    • paymentDescription—payment description (this parameter is available not only to the merchant, but also to the customer; if paymentDescription is specified in the request, it is visible to the customer in the payment form (in the dialog box containing information about the payment); if this parameter is not specified in the request, it is not visible to the customer)
    • customerID—customer ID
    • regionCode—customer country
    • ActionType—action type (Sale (by default), Auth, Tokenize, or Verify.
    • token—card token
    • forcePaymentMethod—the identifier of the payment method which is opened to the customer without an option for the customer to select another payment method. The list of codes is provided in the IDs of payment methods supported on Payment Page section
    • hideSavedWallets—hiding or displaying saved payment instruments in the payment form. Possible values:
      • true—saved payment instruments are hidden, they are not displayed in the payment form.
      • false—saved payment instruments are displayed in the payment form.
    • ECMPScreenDisplayMode—object to manage display of the final page of the payment form and hide the final page if necessary. The following parameters can be passed in the object:
      • hide_success_final_page—the final page with the message about the performed payment is not displayed in the payment form.
      • hide_decline_final_page—the final page with the message about the declined payment is not displayed in the payment form.

      The following is an example of specifying the hide_success_final_page and hide_decline_final_page parameters in the request:

      // Init ECMPPaymentInfo
       
      paymentInfo.addEcmpScreenDisplayMode("hide_success_final_page")
                 .addEcmpScreenDisplayMode("hide_decline_final_page");
  2. Once all the payment parameters are collected, pack the parameters into a string for signing:
    paymentInfo.getParamsForSignature();
  3. Send the string to your back end.
  4. Have your back end generate the signature on the basis of the string and your secret key.
  5. Send the signature to the client app and add it in the paymentInfo object:
    paymentInfo.signature = <signature>
  6. Open the payment form by using the following code:
    startActivityForResult(
                        ECMPActivity.buildIntent(this,
                        paymentInfo),
                        PAY_ACTIVITY_REQUEST)

Response processing

To receive and process response with the payment processing results you need to override the onActivityResult method in activity from which you started ECMPActivity.

Figure: onActivityResult override in Java

@Override
 protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
     super.onActivityResult(requestCode, resultCode, data);
     if (requestCode == PAY_ACTIVITY_REQUEST) {
         switch (resultCode) {
             case ECMPActivity.RESULT_SUCCESS:
                 // Add your code to execute when checkout completes successfully
             case ECMPActivity.RESULT_CANCELLED:
                 // Add your code to execute when customer cancels checkout
             case ECMPActivity.RESULT_DECLINE:
                 // Add your code to execute when checkout is declined
             case ECMPActivity.RESULT_FAILED:
                 // Add your code to execute when checkout fails
                 break;
         }
 
         if(data != null && data.hasExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR)) {
            String error = data.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR);
         }
 
         if(data != null && data.hasExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN)) {
             String token = data.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN);
         }
     }
 }

Figure: onActivityResult override in Kotlin

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
      super.onActivityResult(requestCode, resultCode, data)
      if(requestCode == PAY_ACTIVITY_REQUEST) {
          when (resultCode) {
              ECMPActivity.RESULT_SUCCESS -> {}
              ECMPActivity.RESULT_CANCELLED -> {}
              ECMPActivity.RESULT_DECLINE -> {}
              ECMPActivity.RESULT_FAILED -> {}
          }
 
          val error = data?.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR)
          val token = data?.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN)
      }
  }

The following table lists the possible values of response codes as well as the corresponding constant names and description along with the suggested response actions.

Response code Result constant Description
0 RESULT_SUCCESS Checkout successfully completed.
100 RESULT_DECLINE Operation was declined, for example because of insufficient funds.
301 RESULT_CANCELLED Operation was cancelled by the customer.
501 RESULT_FAILED An internal error occurred. You may need to contact technical support.

Callbacks

Overview

When using SDK for Android, the merchant can receive callbacks that are sent by the payment platform directly to merchant web service and callbacks that are first sent by the payment platform to SDK for Android and then by SDK for Android to merchant mobile application. In the former case, the parameters sent in callbacks may vary depending on the configurations (more). In the latter case, specific set of parameters is provided—the data about status, type and ID of the payment, currency and amount of the payment as well as the payment method that was used:

{
    "payment": {
        "status": "success",
        "type": "purchase",
        "id": "12345",
        "date": "2020-09-11T14:49:18+0000",
        "method": "card",
        "sum": 1000,
        "currency": "USD"
         }
}

The following sections provide information about these callback messages.

Callbacks sent by the payment platform

The payment platform sends all the callback messages to the callback URL you specify. You need to contact the ECommPay technical support and provide the URL to send callbacks. For more information about callbacks, see Callbacks.

Callbacks sent by SDK for Android

Merchant mobile application can receive callback messages with information about purchase processing result from SDK for Android as information about payment processing result is sent to SDK for Android by the payment platform. The callback message is sent to the merchant before the page with information about the result is displayed to the customer on the payment form.

Information about purchase processing result is provided in broadcast messages sent to merchant mobile application by SDK for Android. To obtain this information, you need to do the following:

  1. Create the BroadcastReceiver object to receive broadcast messages.
  2. Upon receipt of broadcast messages from SDK for Android, obtain information about the purchase processing result from the Intent object by using the ECPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.getValue() key. The key is a constant provided by ECMPActivity.

The following are examples of implementation of BroadcastReceiver for obtaining information about the purchase processing result.

Figure: Java

class YourClass {   
    private BroadcastReceiver mReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            ECMPPaymentData paymentData = intent.getParcelableExtra(ECMPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.getValue());
        }
    };
}

Figure: Kotlin

class YourClass {  
    private val mReceiver: BroadcastReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val paymentData: ECMPPaymentData = intent.getParcelableExtra(ECMPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.value)
        }
    }
}

Managing card data

When paying with a payment card, the customer needs to enter the card data on the payment form. In addition to the traditional data entry method (manually), SDK for Android allows to scan a card, use a saved card or a card token for payment.

Checkout by using stored checkout credentials

You can offer your customers an option to save credentials of cards used for checkout. Your customers will be able to save one or more cards and reuse them for any further purchases without specifying the card details—the customer will be only asked to enter CVV for the current card.

To allow customer to save card credentials and use them later for checkout, you need to set the customerID parameter with ID of the card owner. All the saved cards will be associated with this customer ID and the list of all the saved cards will be shown to your customer during checkout procedure. If the customer decides to delete a saved card, the SDK for Android library will send the corresponding request to the payment platform to remove the card from the list of saved cards.

Checkout by using tokens

By using the SDK for Android library, you can implement token-based checkout. Before using the token-based checkout functionality, you need to implement storing payment card credentials and its token on your back end. Each time you initiate a token-based checkout, you need to set the token parameter of your payment object:
paymentInfo.setToken(token);
Do not forget to include the parameter in your signature generation procedure. You customer will see the payment form with the preselected card with all its credentials, except for CVV, entered in the corresponding fields.

Automatic token generation

Automatic generation procedure creates a token when the first successful purchase or payout is performed by using a card, as well as after holding the funds on a card. The generated token and the date when it was created are returned in the payment callback.

Figure: Callback part with token information

"account": {
            "number": "546942******3838",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Token generation by request

Another way to generate a token is to send a request to generate a token. To generate a token set Tokenize as action type:

Figure: Java

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize);

Figure: Kotlin

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize)

The generated token and the time it was created at are returned in the token generation response.

Checkout

One-step purchase

By default, SDK for Android uses one-step purchases (action type Sale). This type of checkout works right out-of-the-box and requires no additional setup.

Two-step purchase

SDK for Android supports two-step purchases in which payment is performed in two steps.

  1. Before opening the payment form, set the action type parameter in the payment object to Auth:

    Figure: Java

    paymentInfo.setAction(ECMPPaymentInfo.ActionType.Auth);

    Figure: Kotlin

    paymentInfo.setAction(ECMPPaymentInfo.ActionType.Auth)
  2. Capture payment by using Dashboard or sending payment capture request to the /v2/payment/card/capture endpoint.

COF purchases

ECommPay allows you to perform COF purchases. There are three types of COF purchases: OneClick, auto payments and regular payments. For more information about COF purchases, see Overview.

To implement COF purchases, instantiate the ECMPRecurrentInfo class:

Figure: Java

ECMPRecurrentInfo recurrentInfo = new ECMPRecurrentInfo(
                    "R",             // Payment type
                    "10",            // End of payment period, day
                    "11",            // End of payment period, month
                    "2020",          // End of payment period, year
                    "M",             // Period of COF purchase (M means 'month') 
                    "12:00:00",      // Time to initiate the first payment
                    "12-02-2019",    // Date to initiate the first payment
                    "pid178545578"); // Payment ID, must be unique within your project

Figure: Kotlin

val recurrentInfo = ECMPRecurrentInfo(
                    "R",                 // Payment type
                    "10",                // End of payment period, day
                    "11",                // End of payment period, month
                    "2020",              // End of payment period, year
                    "M",                 // Period of COF purchase, M means 'month' 
                    "12:00:00",          // Time to initiate the first payment
                    "12-02-2-2019",      // Date to initiate the first payment
                    "your_recurrent_id") // Payment ID, must be unique within your project
Additionally you may set:
  • Amount of COF purchase. By default the amount of COF purchase is equal to payment amount. To change it, set:

    Figure: Java

    recurrentInfo.setAmount(1000);

    Figure: Kotlin

    recurrentInfo.setAmount(1000)
  • Data and amount of COF purchase. By default the debit of funds is strictly fixed in time and amount. To customize schedule for COF purchases, set:

    Figure: Java

    recurrentInfo.setSchedule(new ECMPRecurrentInfoSchedule[]{
                   new ECMPRecurrentInfoSchedule("10-10-2020",1200),
                   new ECMPRecurrentInfoSchedule("10-11-2020",1000),
                   .....
    });

    Figure: Kotlin

    recurrentInfo.setSchedule(arrayOf(ECMPRecurrentInfoSchedule("10-10-2020",1200),
                                      ECMPRecurrentInfoSchedule("10-11-2020",1000),
                                      .....
    ))

And then, add your instance of ECMPRecurrentInfo into the instance of ECMPPaymentInfo you previously created:

Figure: Java

paymentInfo.setRecurrent(recurrentInfo);

Figure: Kotlin

paymentInfo.setRecurrent(recurrentInfo)

Card verification

The card verification is used when it is necessary to check the customer's card without debiting the funds, as well as to save the card data for future use. With card verification, a zero amount is debited from the card.

To perform card verification, set Verify as action type:

Figure: Java

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify);

Figure: Kotlin

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify)

Purchases by using alternative payment methods

SDK for Android supports the following alternative payment methods: Skrill Wallet, DOKU Wallet,QIWI Wallet, Yandex.Money, Apple Pay, Banks of Malaysia, Banks of Thailand, Convenience stores in Thailand, MCash Wallet, Alipay, Neteller, WebMoney (the WebMoneyLight and WebMoneyClassic purchase scenarios). In most cases customer needs to be redirected to the payment form of the alternative payment method (APM) service.

The full sequence and particularities of the purchase process are provided below.

Figure: Purchase sequence by using the alternative payment methods (APM)



To perform purchases by using alternative payment methods, contact the ECommPay technical support in order to enable that ability for the particular project. Additionally, you may use the ability to pass additional customer information.

WebMoney

For payment processing by using SDK for Android, the WebMoneyLight and WebMoneyClassic purchase scenarios are supported. When the WebMoneyLight scenario is used, customer is redirected to the WebMoney payment form in order to transfer funds to the merchant WM e-wallet. When the WebMoneyClassic scenario is used, customer uses the WebMoney service in order to perform purchase. The main procedures, such as opening the payment form, processing response and callbacks, are performed the same way as when other alternative payment methods are used, but you also need to consider the following:

  • For payment processing by using the WebMoneyClassic purchase scenario, automatic purchase initiation with no need for the customer to specify data in the payment form is supported. To implement this option, along with the minimum set of required parameters (more) you need to specify in the request the values of both of the following parameters:
    • accountNumber—customer identifier in the WebMoney method (WMID).
    • accountPurseType—type of the WebMoney purse of the customer.

    If values of both of the accountNumber and accountPurseType parameters are specified in the request, purchase processing is started automatically with no option for the customer to change the data specified in the payment form.

    If value of only one of the parameters is specified in the request, the filed for entering the required data is displayed to the customer on the payment form. In this case purchase processing is initiated once the customer specifies the required data.

  • The currency used for the payment must be supported by the WebMoney method. For information about the supported currencies, see WebMoney.

Gathering customer data

Usually payment form requires a minimum of data to complete a request for payment. However, in order to gather more extensive data and statistics about customers you can send and/or request additional data about your customers, such as customer phone number or email. For more information, see Collecting customer data.

To pass additional information, set them in the paymentInfo object:

Figure: Java

paymentInfo.setECMPAdditionalFields(new ECMPAdditionalField[]{
     new ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.customer_first_name, "Mark"),
     new ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.billing_country, "US"),
     ECMPAdditionalField(aps_account_number, ""),
     ECMPAdditionalField(aps_account_security_code, "")
     .....
});

Figure: Kotlin

paymentInfo.ecmpAdditionalFields = arrayOf(ECMPAdditionalField(
             ECMPAdditionalField.AdditionalFieldType.customer_first_name, "Mark"),
             ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.billing_country, "US"),
             ECMPAdditionalField(aps_account_number, ""),
             ECMPAdditionalField(aps_account_security_code, "")
             .....
)

Customisation

You may change design of the SDK for Android payment form:
  • use pre-defined themes (light and dark)

    Figure: Light theme of the payment form



    Figure: Dark theme of the payment form



  • set the custom value to any available setting

Using pre-defined themes

SDK for Android allows to choose between two pre-defined themes (light and dark) of payment form. By default SDK for Android uses light theme.

To set a dark theme:

Figure: Java

ECMPTheme theme = ECMPTheme.getDarkTheme();
startActivityForResult(ECMPActivity.buildIntent(this,
               paymentInfo,
               theme),
               PAY_ACTIVITY_REQUEST);

Figure: Kotlin

val theme = ECMPTheme.getDarkTheme()
startActivityForResult(
   ECMPActivity.buildIntent(
               this,
               paymentInfo,
               theme
    ),
    PAY_ACTIVITY_REQUEST
 )

Changing settings

Also you can set the custom value to any available setting. For example, set:

Figure: Java

theme.fullScreenBackgroundColor = Color.GREEN;
theme.showShadow = false;

Figure: Kotlin

theme.fullScreenBackgroundColor = Color.GREEN
theme.showShadow = false
The list of available settings:
  • overlayColor — the color of the overlay
  • statusBarColor — the color of the status bar
  • modalBackgroundColor— the color of the modal window
  • fullScreenBackgroundColor — the color of the payment form background in full-screen mode
  • headingTextColor— the color of the heading
  • menuTextColor — the color of the text on the buttons in the modal window header
  • fieldTextColor— the color of the text of the additional fields, payment methods names, text on the page with information about the result
  • fieldPlaceholderTextColor — the color of the placeholder texts
  • fieldImageTintColor — the color of the icons of the CVV field and payment data fields for payment with a new card
  • fieldBackgroundColor — the color of the buttons of the payment systems and CVV field
  • fieldUnderlineSelectedColor — the color of the underline when the field is selected
  • fieldUnderlineDefaultColor — the color of the underline by default
  • fieldUnderlineErrorColor — the color of the underline when validation of the completed field fails
  • navigationBarItemsColor — the color of the navigation bar items
  • navigationBarColor — the color of the navigation bar
  • primaryTintColor — the main color of the buttons and icons of the payment form
  • secondaryTintColor — the secondary color of the payment form
  • actionButtonDisableBackgroundColor — the color of the disabled action button
  • actionButtonDisableTextColor — the color of the text on the disabled action button
  • actionButtonTextColor — the color of the text on the action button
  • supportiveTextColor — the color of the secondary text
  • secureKeyboardTextColor — the color of the symbols of the onscreen keyboard
  • showShadow — enables shadow for payment methods and saved cards on the page of payment method selection
  • showLightLogo — enables light logos when using dark theme