SDK for Android

Capabilities

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

Contents

Payment workflow

Figure: Interaction diagram

Using SDK for Android

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

Importing libraries in your project

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 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

   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

   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)

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

@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);
         }
     }
 }

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.

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.

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());
        }
    };
}

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)
        }
    }
}

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

paymentInfo.setToken(token);

Automatic token generation

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

Token generation by request

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize);

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize)

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

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.

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

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

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

paymentInfo.setRecurrent(recurrentInfo);

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.

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify);

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,QIWI Wallet, , Malaysian Online Banking, Thai Online Banking, MCash Wallet, Alipay, Neteller, WebMoney (the WebMoneyLight and WebMoneyClassic purchase scenarios) 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 and the WebMoney payment methods.

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.