SDK for Android (legacy)

SDK for Android is a software development kit for fast integration of the ecommpay payment solutions right in your mobile application for Android. In this section you will find information about using SDK for Android and Java and Kotlin code samples.

Note: This article describes a deprecated version of SDK for Android. You are recommended to use the new releases of mobile SDKs instead.

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

Starting with the version 1.10.0, the SDK for Android libraries are imported via MavenCentral. For more information, see the Importing libraries via MavenCentral section.

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

General information

Capabilities

SDK for Android allows you to perform purchases by using payment cards and alternative payment methods. You can perform one-step and two-step purchases and COF purchases using payment cards, as well as card verification (more). SDK for Android supports the following alternative payment methods:

SDK for Android also supports payment processing by using methods listed in the Methods section. For information about setup and configuration, contact your ecommpay account manager.

In terms of SDK for Android, the ecommpay payment form is used and the following features are available:
  • Support for English, French, German, Italian, Spanish and Russian. The language of the payment form can be the one set in the mobile device settings, or the one set by the merchant. In this case you should consider the following:
    • If the merchant sets the language supported by SDK for Android, the payment form is displayed in the language set by the merchant.
    • If the merchant sets the language which is not supported by SDK for Android, the payment form is displayed in English.
    • If the merchant does not set the language, the payment form is displayed in the language set in the mobile device settings, if this language is supported by SDK for Android, or in English, if the language of the mobile device is not supported by SDK for Android.
  • 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).

Contents

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:EUR;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 choosing 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 'androidx.appcompat:appcompat:1.0.0'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.recyclerview:recyclerview:1.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:$kotlin_version"
    
    implementation 'androidx.lifecycle:lifecycle-viewmodel:2.0.0'
    implementation 'androidx.lifecycle:lifecycle-extensions:2.0.0'
    annotationProcessor 'androidx.lifecycle:lifecycle-compiler:2.0.0'

    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 MavenCentral

Starting with the version 1.10.0, the SDK for Android libraries can be imported via MavenCentral. To import the libraries via MavenCentral, you need to do the following:

  1. Open your application module (build.gradle).
  2. In the repositories {} section, specify the mavenCentral repository:
    allprojects {
        repositories {
            google()
            jcenter()
            mavenCentral()
        }
    }

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 shown in bold, optional parameters are in italics):
    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
    Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. In such cases it will be required to specify at least one of the following parameters: the customer's phone number (customerPhone) or email (customerEmail). These parameters must be also specified in the ECMPPaymentInfo object.

    However, it is recommended that these and a number of other parameters (with the billing address information) are also specified for payments made with cards of other card schemes. According to Visa, rigorous use of these parameters can significantly increase payment acceptance rates (up to 6 %) and drastically decrease the number of operations flagged as fraudulent after they have been processed (up to 65 %). Parameters with the billing address information of the customer include the country code in ISO 3166-1 alpha-2 (billingCountry), the postal code (billingPostal), the city (billingCity), and the street address (billingAddress).

    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 Payment method codes 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
    Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. In such cases it will be required to specify at least one of the following parameters: the customer's phone number (customerPhone) or email (customerEmail). These parameters must be also specified in the ECMPPaymentInfo object.

    However, it is also recommended that these and a number of other parameters (with the billing address information) are specified for payments made with cards of other card schemes. According to Visa, rigorous use of these parameters can significantly increase payment acceptance rates (up to 6 %) and drastically decrease the number of operations flagged as fraudulent after they have been processed (up to 65 %). Parameters with the billing address information of the customer include the country code in ISO 3166-1 alpha-2 (billingCountry), the postal code (billingPostal), the city (billingCity), and the street address (billingAddress).

    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 Payment method codes 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 add the customerID parameter with ID of the card owner to the ECMPPaymentInfo object. 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": "541333******0019",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2024"
        },

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 a 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
                    "2030",          // End of payment period, year
                    "M",             // Period of COF purchase (M means 'month') 
                    "12:00:00",      // Time to initiate the first payment
                    "12-02-2020",    // 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
                    "2030",              // 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-2020",      // 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: Google Pay, Skrill Wallet, DOKU Wallet, Malaysian Online Banking, Thai Online Banking, Alipay, Neteller and purchases by using online banking in European countries. In most cases customer needs to be redirected to the payment form of the alternative payment method (APM) service. Each method is described in a separate article, and the sections below provide the description of special features of using the Google Pay.

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 capability of passing additional customer information.

Google Pay

In order to implement payment processing which involves the Google Pay payment method, it is necessary for the merchant to do the following:

  1. Register with the Google Pay Business Console and receive a Google merchant ID.
  2. Adhere to the Google Pay API's Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
  3. Contact the ecommpay technical support in order to enable the Google Pay payment method for the particular project.

Once these steps are completed, payments can be processed by using the Google Pay method. 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:

  • In the request for opening the payment form, you must specify the Google merchant ID (merchantId) and the PaymentDataRequest object which is used to configure your app's support for the Google Pay API. For the description of the PaymentDataRequest object, see the Google Pay API documentation.

    Figure: Example of the PaymentDataRequest object

    {
      "apiVersion": 2,
      "apiVersionMinor": 0,
      "merchantInfo": {
        "merchantName": "Example Merchant",
        "merchantId": "merchant_id"
      },
      "allowedPaymentMethods": [
        {
          "type": "CARD",
          "parameters": {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"]
          },
          "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
              "gateway": "ecommpay",
              "gatewayMerchantId": "gateway_merchant_id"
            }
          }
        }
      ],
      "transactionInfo": {
        "totalPriceStatus": "FINAL",
        "totalPrice": "12.34",
        "currencyCode": "USD"
      }
    }
    Note that the PaymentDataRequest.transactionInfo object must contain the following parameters:
    • totalPriceStatus—the status of the total price; the value must be FINAL which means that the total price does not change from the amount presented to the customer.
    • totalPrice—total payment amount in minor currency units. This amount must be equal to the amount specified in the PaymentDataRequest.PaymentInfo object.
    • currencyCode—payment currency in ISO-4217 alpha-3 format.

    The following are the examples of requests for opening the payment form which contain the merchant identifier (merchantId) and the PaymentDataRequest object.

    Java

    {
    PaymentInfo paymentInfo = PaymentInfo()
    ...
    PaymentDataRequest paymentDataRequest = generatePaymentRequest();
    paymentInfo.setPaymentDataRequest(paymentDataRequest);
    paymentInfo.setMerchantId("your merchant id");
    ...
    }
     
    private PaymentDataRequest generatePaymentRequest() {
        return PaymentDataRequest.fromJson(
    "your json object");
    }

    Kotlin

    {
    val paymentInfo = PaymentInfo()
    ...
    val paymentDataRequest = generatePaymentRequest();
    paymentInfo.setPaymentDataRequest(paymentDataRequest);
    paymentInfo.setMerchantId("your merchant id");
    ...
    }
     
    private fun generatePaymentRequest() -> PaymentDataRequest {
        return PaymentDataRequest.fromJson(
    "your json object");
    }
  • To set Google Pay as preselected payment method, you need to specify in the request the forcePaymentMethod parameter with the google_pay_host value. Note that you need to configure the Google Pay payment button displayed in your app in accordance with the Google brand guidelines.

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