SDK UI & Core for Android

Overview

Introduction

Mobile SDK UI & Core for Android is a software development kit that can be used to integrate Android applications with the ecommpay payment platform.

SDK UI & Core for Android provides the functionality for interaction of customers with the user interface and for interaction of a mobile application with the payment platform which allows sending and receiving necessary information during payment processing.

SDK UI & Core for Android can be embedded in mobile applications developed for Android version 5.0 or later. The SDK UI & Core for Android libraries and code examples are available on GitHub. To access, use the following URLs:

Capabilities

The following functional capabilities are supported by SDK UI & Core for Android:

  • Processing purchases with immediate debiting of funds, made with payment cards and alternative payment methods available for the merchant's project.
  • Registering COF purchases.
  • Saving payment data for subsequent payment processing.
  • Submitting additional payment information.
  • Cascade payment processing.
  • Collecting customer data.
  • Checking current payment information.
  • Sending email notifications with the list of purchased items to customers after the payment has been processed.
  • Customising the colour of the payment interface.
  • Adding the logo of the merchant.

In case of card and Google Pay payments, the payment interface described in this article is used. With other payment methods, Payment Page is used during payment processing.

Workflow

Generally, the following workflow is relevant when purchases are processed with the use of SDK UI & Core for Android.

  1. In the user interface of a mobile application, the customer initiates a purchase by clicking the payment button or in a different fashion set up on the merchant side.
  2. In the mobile application, a set of parameters for creating a payment session is generated. Then, with the help of SDK UI & Core for Android, this set is converted into a string for signing, and the string is sent to the server side of the merchant web service.
  3. On the server side of the merchant web service, the parameters can be checked and supplemented if necessary, and the signature to the final parameter set is generated, following which the prepared data is sent back to SDK UI & Core for Android.
  4. With the help of SDK UI & Core for Android, a payment session is initiated in the payment platform.
  5. On the payment platform side, the payment interface is prepared in accordance with the invocation parameters, and the data for opening the interface is passed to the customer's device.
  6. In the mobile application, the payment form is displayed to the customer.
  7. The customer selects a payment method (if no method was selected when the payment session was initiated), specifies the necessary information, and confirms the purchase.
  8. SDK UI & Core for Android sends a purchase request to the payment platform.
  9. On the payment platform side, the payment is registered and all necessary technical actions are performed; these actions include sending the required data to the payment environment—to the providers and payment systems.
  10. The payment is processed in the payment environment. Then the payment result information is received in the payment platform.
  11. In the payment platform, the information about the payment result is processed and a callback is sent to the server side of the web service.
  12. The information about the purchase result is sent from the payment platform to SDK UI & Core for Android.
  13. The notification with the result information is displayed to the customer in the user interface.

Interface

When card and Google Pay payments are processed, the customer interacts with the user interface designed by the ecommpay specialists. This user interface can be customised: you can change its colour and add your company's logo.

Setup

Integration steps

To integrate the web service with the ecommpay payment platform by using SDK UI & Core for Android:

  1. Address the following organisational issues of interaction with ecommpay:
    1. If your company has not obtained a project identifier and a secret key for interacting with ecommpay, submit the application for connecting to the ecommpay payment platform.
    2. If your company has obtained a project identifier and a secret key for interacting with ecommpay, inform the technical support specialists about the company's intention to integrate by using SDK UI & Core for Android and coordinate the procedure of testing and launching the functionality.
  2. Complete the following preliminary technical steps:
    1. Download and link the SDK UI & Core for Android libraries.
    2. Ensure the collection of data necessary for opening the payment form. The minimum data set needed in order to open the payment form consists of the project, payment, and customer identifiers as well as of the payment amount and currency.
    3. Ensure signature generation for the data on the server side of the mobile application.
    4. Ensure the receipt of and the response to the notifications from SDK UI & Core for Android as well as the receipt of and the response to the callbacks from the payment platform on the web service side.
  3. With the technical support specialists, coordinate the timeline and the main steps of integrating, testing (including testing available payment methods), and launching the solution.
    1. For testing, use the test project identifier and the details of test cards.
    2. For switching to the production mode, change the value of the test project identifier to the value of the production project identifier received from ecommpay.

If you have any questions about working with SDK UI & Core for Android, contact the ecommpay technical support specialists (support@ecommpay.com).

Libraries installation

For the mobile applications developed for Android version 5.0 or later, linking the SDK UI & Core for Android libraries via MavenCentral is supported. To link the libraries:

  1. Open the build.gradle.kts module in the application.
  2. Specify the mavenCentral repository in the repositories section:
    allprojects {
        repositories {
            google()
            mavenCentral()
        }
    }
  3. Add the following code in the dependencies section:
    implementation "com.ecommpay:msdk-ui:LATEST_VERSION"

Signature generation

Make sure that the data is signed on the server side of the web service with the use of the secret key received from ecommpay. To work with the signature, you can use ready-to-use components, such as language-specific SDKs for web services (details), or your own in-house solutions. The procedure of working with the signature is described in Signature generation and verification.

Testing

Before you start processing real payments via SDK UI & Core for Android, it is recommended that you test payment processing in the test project. You can obtain the identifier and the secret key of the test project when accessing the ecommpay test environment (this can be done via the company's website). Along with that, upon the coordination with the ecommpay specialists, it is possible to test the use of the Google Pay method and additional capabilities, such as cascade payment processing and collection of customer data.

To test payment processing:

  1. Open the build.gradle.kts module in the application.
  2. Specify the test project identifier (projectId) and the secret key of the given project (projectSecretKey).
  3. Run the gradle synchronisation process.

To switch to the production mode, change the test values (the identifier and the secret key of the test project) to the production ones.

Use

Opening payment form

SDK UI & Core for Android supports such actions as performing one-time purchases and registering COF purchases. To initiate these actions, you need a certain parameter set. The required minimum of parameters is passed in the EcmpPaymentInfo object while other parameters can be passed in the EcmpPaymentOptions object, requested from the customer, or received from the payment platform.

To open the payment form:

  1. Create the EcmpPaymentInfo object.
    • This object must contain the following required parameters:
      • projectId (integer)—a project identifier assigned by ecommpay
      • paymentId (string)—a payment identifier unique within the project
      • paymentCurrency (string)—the payment currency code in the ISO 4217 alpha-3 format
      • paymentAmount (integer)—the payment amount in the smallest currency units
      • customerId (string)—a customer's identifier within the project
      • signature (string)—a request signature generated after all required parameters have been specified
    • You can also add any other parameters listed in the following table.
    val ecmpPaymentInfo = EcmpPaymentInfo(
            projectId = 77655,
            paymentId = payment_322,
            paymentAmount = 100,
            paymentCurrency = "USD",
            paymentDescription = "Cosmoshop payment", 
            customerId = "customer_003",
            regionCode = "DE",           //Code of the customer's country
            token = "o8i7u65y4t3rkjhgfdw3456789oikjhgfdfghjkl...", //Token associated with certain payment data
            languageCode = "de",         //Payment interface language code
            receiptData = "eyAKICAicG9zaXRpb25zIjpbIAogICAgIIjoxLAogICAgICAgICJhbW91bnQiOjU5OTAsCiAgQ==",
            //Data to be included in the notification with the list of the purchased items
            hideSavedWallets = false,    //Parameter to enable hiding or displaying saved payment instruments
            forcePaymentMethod = card    //Identifier of the preselected payment method
       )
  2. Sign the parameters contained in the EcmpPaymentInfo object.
    ecmpPaymentInfo.signature = SignatureGenerator.generateSignature(
            paramsToSign = ecmpPaymentInfo.getParamsForSignature(),
            secret = SECRET_KEY
       )
  3. Create the EcmpPaymentOptions object that contains the required parameter actionType (string) with the value specifying the sale operation type. You can also add any other objects and parameters listed in the following table.

    In addition to the required EcmpPaymentInfo object and the actionType parameter, the following example contains several additional parameters including the EcmpAdditionalFields object with data specified in the fields that are used for collecting customer information.

    val paymentOptions = paymentOptions {
            actionType = sale
            brandColor = "#800008"
            logoImage = BitmapFactory.decodeResource(resources, R.drawable.example_logo) 
            paymentInfo = ecmpPaymentInfo
            isTestEnvironment = true
            merchantId = BuildConfig.GPAY_MERCHANT_ID
            merchantName = "Example Merchant Name"
            additionalFields = EcmpAdditionalFields(
              field {
                  EcmpAdditionalField(
                     EcmpAdditionalFieldType.CUSTOMER_EMAIL,
                     "mail@mail.com"   
                  )
              }
              field {
                  EcmpAdditionalField(
                     EcmpAdditionalFieldType.CUSTOMER_FIRST_NAME,
                     "firstName"
                  )
              }
           )
       }
  4. Create the EcmpPaymentSDK object.
    val sdk = EcmpPaymentSDK(
            context = applicationContext,
            paymentOptions = paymentOptions,
            )

    If necessary, you can open the payment form in the test mode in order to get information about errors if there were any when payment parameters were specified or to test processing payments with a certain payment result. In the EcmpPaymentSDK object, specify the PaymentSDK.MockModeType.SUCCESS value for the mockModeType parameter (if you need to receive Success payment result). You can also pass values PaymentSDK.MockModeType.DECLINE (if you need to receive Decline payment result) and PaymentSDK.MockModeType.DISABLED (if you need to switch to the production mode).

  5. Open the payment form.
    sdk.openPaymentScreen(this, 1234)

Payment status information

To receive payment result notifications, use the onActivityResult method.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
 
        when (resultCode) {
            EcmpPaymentSDK.RESULT_SUCCESS -> {
                Toast.makeText(this, "Payment was finished successfully", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was finished successfully")
            }
            EcmpPaymentSDK.RESULT_CANCELLED -> {
                Toast.makeText(this, "Payment was cancelled", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was cancelled")
            }
            EcmpPaymentSDK.RESULT_DECLINE -> {
                Toast.makeText(this, "Payment was declined", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was declined")
            }
            EcmpPaymentSDK.RESULT_ERROR -> {
                val errorCode = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_CODE)
                val message = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_MESSAGE)
                Toast.makeText(this, "Payment was interrupted. See logs", Toast.LENGTH_SHORT).show()
                Log.d(
                    "PaymentSDK",
                    "Payment was interrupted. Error code: $errorCode. Message: $message"
                )
            }
        }
    }

Possible payment result codes:

  • RESULT_SUCCESS—payment has been completed.
  • RESULT_CANCELLED—payment has been cancelled.
  • RESULT_DECLINE—payment has been denied.
  • RESULT_ERROR—error occurred when the payment was being processed.

Additional capabilities

Saving payment data

SDK UI & Core for Android allows saving payment data of the customer for subsequent processing of payments without the need for the said customer to re-enter such data. This capability is set up individually for each project. The merchant has to let the technical support know which of the two options is preferable: always save payment data or ask the customer to select the option. For more information about this capability, refer to article Saving customer payment data.

As a result of saving payment data, a separate identifier is generated for each payment instrument. This identifier is associated with the identifier of a certain customer (customerId). To display saved payment data to the customer, pass false in the hideSavedWallets parameter of the EcmpPaymentOptions object.

Cascade payment processing

In case of a payment attempt failure, the capability of cascade payment processing can be used (details). This capability implies executing a sequence of payment attempts via alternative providers without the payment method change and can be set up upon coordination with the ecommpay specialists.

If this capability is set up for the project in use, then after the first unsuccessful attempt, a notification is received from SDK UI & Core for Android. This notification contains the cascading_with_redirect = trueattribute-value pair. Along with that, the error page with the button to retry making the payment is shown to the customer. If the 3‑D Secure authentication is not required as part of the additional attempt, then the attempt is executed without any further interaction with the customer. Otherwise, a separate page opens for repeating the authentication process.

Submitting additional payment information

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for its initiation. However, in some cases, a payment system or a provider can require additional data necessary for processing a particular payment. This can be due to region-specific requirements, the need for an additional anti-fraud check, or other factors. The information about submitting additional payment data is provided in the following article.

The final set of required parameters can vary depending on a specific provider or a payment system. The list of parameters relevant for a particular payment is displayed to the customer on the payment form. The customer fills in the required data, confirms the payment, and receives the payment result information.

Collecting customer data

In some cases, alongside the mandatory parameters, it can be relevant to require the additional ones (such as phone numbers and email addresses) from the customers. To have this capability set up, the merchant should decide which data has to be mandatory to be specified by the customers and communicate data collection preferences to the technical support specialists. For more information about using the capability, see the separate article.

Payment form opening parameters

When working with SDK UI & Core for Android, you can pass the following optional parameters in the EcmpPaymentInfo object.

Parameter Description

paymentDescription
string

Description of the payment. A string that contains between 1 and 255 characters.

Example: Cosmoshop purchase

receiptData
string

Data to be included in the notification with the list of the purchased items, passed as a JSON object encoded using the Base64 scheme.

Example: eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg

token
string

Token associated with certain payment data. A string that contains between 1 and 255 characters.

Example: 6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c

hideSavedWallets
boolean

Parameter to enable hiding or displaying saved payment instruments in the payment form.

Possible values:

  • true—saved payment data is hidden
  • false—saved payment data is displayed.

forcePaymentMethod
string

The identifier of the preselected payment method according to the table.

Example: card

ecmpThreeDSecureInfo
object

Object that contains additional objects and parameters necessary for the 3‑D Secure 2 authentication (learn more).

languageCode
string

Payment interface language code in the ISO 639-1 alpha-2 format.

Example: EN

regionCode
string

Code of the customer's country in the ISO 3166-1 alpha-2 format.

Example: GB

You can pass the following optional parameters in the EcmpPaymentOptions object.

Parameter Description

merchantID
string

The Google Pay identifier of the merchant.

merchantName
string

The Google Pay name of the merchant.

logoImage
bitmap

A bitmap file that contains the logo of the merchant.

brandColor
string

Payment interface colour in hexadecimal format.

Example: #800080

isTestEnvironment
boolean

Parameter to indicate a test payment.

Possible values:

  • true
  • false

additionalFields
list

Additional fields that contain information about the customer.

Example: EcmpAdditionalField(EcmpAdditionalFieldType.CUSTOMER_EMAIL,"mail@mail.com")

recipientInfo
object—object with information about the recipient of the payment.

pan
string

Card number.

Example: 5443011828121882

card_holder
string

First and last name (as specified on the card).

Example: Arthur Eddington

wallet_id
string

Number of the wallet.

Example: WID2812188222111944

wallet_owner
string

First and last name of the recipient.

Example: Arthur Eddington

country
string

Code of the recipient's country in the ISO 3166-1 alpha-2 format.

Example: GB

address
string

Recipient's address.

Example: 42 Walliscote Road

city
string

Recipient's city of residence.

Example: Weston-super-Mare

state
string

Recipient's state.

Example: GB

To work with COF purchases, you should pass relevant parameters in the recurrentData object of the EcmpPaymentOptions object.

Parameter Description

type
string

COF purchase type:

  • COneClick
  • U—autopurchase
  • R—regular purchase

period
string

Debiting period for a regular purchase.

Possible values:

  • D—daily
  • W—weekly
  • M—monthly
  • Q—quarterly
  • Y—yearly

expiry_day
string

Expiration day of the COF purchase.

expiry_month
string

Expiration month of the COF purchase.

expiry_year
integer

Expiration year of the COF purchase.

scheduled_payment_id
string

Identifier to assign to the COF purchase (for automatic debiting).

Parameter must be passed together with the start_date parameter.

start_date
string

Date to perform the first debit in the dd-mm-yyyy format. Parameter must be passed together with the scheduled_payment_id parameter.

time
string

Time when to perform a scheduled debit (for regular purchases) in the hh:mm:ss format, passed if the period parameter is specified as well.

schedule
object—schedule of debits performed as part of the COF purchase (can be specified by the merchant). Should contain parameters amount and date.

amount
integer

The amount to debit in the smallest units of currency.

date
string

Date to perform the debit in the dd-mm-yyyy format.