SDK UI & Core for Android

SDK UI & Core for Android supports such actions as performing one-time purchases and placing authorisation holds as part of executing two-step purchases, registering COF purchases and performing payment card verification. 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 unit
     • 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.
   • This object must contain the following parameters:
     • For all payments—the actionType parameter with the value specifying the required operation type: Sale, Auth, or Verify.
     • For card payments—the CUSTOMER_EMAIL or the CUSTOMER_PHONE parameter embedded in the additionalFields object (at least one of the two) to display the corresponding fields to the customer on the payment form.
   • For 3‑D Secure it is recommended that you specify the customer's billing address information:
     • BILLING_COUNTRY—the country of the customer's billing address in the ISO 3166-1 alpha-2 format (details)
     • BILLING_POSTAL—the postal code of the customer's billing address
     • BILLING_CITY—the city of the customer's billing address
     • BILLING_ADDRESS—the street of the customer's billing address

     These parameters are passed in the additionalFields object and the corresponding fields are displayed to the customer on the payment form.

     Note: 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 %).
   • 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 the CUSTOMER_EMAIL parameter required for card payments and several additional parameters including the ones listed in the additionalFields object.

   val paymentOptions = paymentOptions {
           paymentInfo = ecmpPaymentInfo
           actionType = EcmpActionType.Sale
           brandColor = "#800008"
           isDarkTheme = false
           logoImage = BitmapFactory.decodeResource(resources, R.drawable.example_logo)
           hideScanningCards = false 
           isTestEnvironment = true
           merchantId = BuildConfig.GPAY_MERCHANT_ID
           merchantName = "Example Merchant Name"
           screenDisplayModes {
             mode(EcmpScreenDisplayMode.HIDE_DECLINE_FINAL_SCREEN)
             mode(EcmpScreenDisplayMode.HIDE_SUCCESS_FINAL_SCREEN)
           }
           additionalFields {
             field {
               type = EcmpAdditionalFieldType.CUSTOMER_EMAIL
               value = "mail@mail.com"
             }
             field {
               type = EcmpAdditionalFieldType.CUSTOMER_FIRST_NAME
               value = "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 EcmpPaymentSDK.EcmpMockModeType.SUCCESS value for the mockModeType parameter (if you need to receive Success payment result). You can also pass values EcmpPaymentSDK.EcmpMockModeType.DECLINE (if you need to receive Decline payment result) and EcmpPaymentSDK.EcmpMockModeType.DISABLED (if you need to switch to the production mode).

5. Open the payment form.

   sdk.openPaymentScreen(this, 1234)

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

In addition, SDK UI and Core for Android supports processing two-step purchases (which involves placing an authorisation hold via the SDK and subsequent debiting of the authorised amount). To perform a two-step purchase:

1. Open the payment form with EcmpActionType.Auth specified as a value for the action type parameter in the paymentOptions object:

   (EcmpPaymentOptions.EcmpActionType.Auth);

2. When needed, initiate debiting of the authorised amount via Dashboard (details) or Gate (by sending the request to the /v2/payment/card/capture endpoint).

Payment instrument verification can be used when you need to validate a card without withdrawing funds instantly (for example, before performing a payout) or when you need to save card details for subsequent use. It is essentially a payment that involves debiting a dummy (zero) amount from the customer's card.

To perform verification, open the payment form with EcmpActionType.Verify specified as a value for the action type parameter in the paymentOptions object:

(EcmpPaymentOptions.EcmpActionType.Verify);

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.