SDK Core for Android

Actions with payment cards

For performing targeted actions with the direct use of cards, such as purchase processing (NewCardSaleRequest), authorisation holds on funds (CardAuthRequest), and card verification (CardVerifyRequest), the following data sets are used.

Tokenisation

SDK Core for Android supports tokenisation of payment data. When the scenario of tokenisation (CardTokenizeRequest) is running, no financial operations are performed but a secure identifier associated with the data of a particular payment card is generated. The information about generating and using tokens is provided in the corresponding articles—Tokenization and Payments by using tokens.

For generating tokens via SDK Core for Android, the following data sets are required.

Usage of saved payment data

SDK Core for Android supports the capability of saving payment data on the customer's initiative and via tokenisation. It also supports using this data for payment processing. With saved payment data and tokens, it is possible to process purchases and place authorisation holds on funds via certain scenarios. In case of saved data, these scenarios are: SavedCardSaleRequest (for processing purchases) and SavedCardAuthRequest (for placing holds on funds); in case of tokens, these scenarios are CardSaleTokenizeRequest (for processing purchases) and CardAuthTokenizeRequest (for placing holds on funds).

Purchases by using alternative methods

SDK Core for Android supports processing purchases (GooglePaySaleRequest) and placing holds on funds (GooglePayAuthRequest) by using the Google Pay method.

To process purchases with the use of the Google Pay method, proceed as follows:

1. Register in the Google Pay Business Console service and receive the merchant identifier in the Google Pay service (Google merchant ID).
2. Accept and comply with the Acceptable Use Policy of Google Pay API and accept the Terms of Service of the Google Pay API.
3. Embed the Google Pay button in the user interface following the brand guidelines and implement the process of receiving token with the customer card data from the Google Pay service.
4. Add the following information to the AndroidManifest.xml file:

   <meta-data
       android:name="com.google.android.gms.wallet.api.enabled"
       android:value="true" />

Usage of additional parameters

Besides the required minimum of parameters, the additional ones can be used in requests.

• recurrentInfo—object with the COF purchase information (details).
• paymentDescription (string)—payment description.
• regionCode (string)—country code in the format of ISO 3166 alpha-2.
• token (string)—payment data token.
• forcePaymentMethod (string)—code of the preselected payment method. The codes of payment methods are provided in the corresponding reference.
• hideSavedWallets (boolean)—parameter that allows setting whether the payment instruments are displayed or not displayed to the customer. Possible values:
  • true—saved payment instruments are not displayed to the customer.
  • false—saved payment instruments are displayed to the customer.

Saving payment data

During the work with SDK Core for Android, it is possible to save customer payment data for further processing of payments, without this data being re-entered by customers. Payment data can be saved on the customer's initiative or via the tokenisation scenario (CardTokenizeRequest). While tokenisation is the default capability within the project, the capability of saving payment data on the customer's initiative needs to be set up. To set up the capability of saving payment data, contact the ecommpay technical support specialists and ensure that the toggle switch for saving data is displayed in the user interface.

As a result of saving payment data on the customer's initiative, a separate identifier (account_id) is generated for each payment instrument. This identifier is associated with the identifier of a particular customer (customer_id). These payment instrument identifiers can be received in the notification from SDK Core for Android about the payment session creation and used in the request for payment creation.

If the payment data was saved as a result of the CardTokenizeRequest scenario, a token is generated for a certain card of the customer. This token can be received in the notification stating that the token has been generated in the Payment object and further specified in payment requests. For executing the tokenisation scenario, the request for creating a session in SDK Core for Android (initiated on the merchant's side) should contain the project and customer identifiers, the rest of the details for token generation (the number and expiration date of the payment card and cardholder name) should be requested from the customer.

"SavedAccounts":
{
  "number": "541333******0019",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // payment data token
  "id": 12353661,   // saved payment data identifier (accountId)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+440202267709",
    "country": "GB",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "GB",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },

3‑D Secure authentication

When the customer 3‑D Secure authentication is required for payment processing, proceed as follows:

1. Receive the notification onThreeDSecure stating that displaying the authentication page to the customer is required. This notification contains the acsPage object with the parameters of displaying the authentication page and the link for redirecting the customer after the authentication.
2. Display the authentication page to the customer.
3. Wait for the customer to be redirected from the authentication page and call the threeDSecureHandled method.

func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // calling method
}

Cascade payment processing

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

With this capability set up for the project in use and after the first unsuccessful attempt, a notification is received from SDK Core for Android. This notification contains the isCascading object with the value true which means that an additional attempt is available as part of the cascade payment processing. If the customer authentication is required for processing the payment, the merchant should display the error information to the customer, obtain the customer's confirmation to make another attempt, and retry the payment. If the authentication is not required, no additional actions are performed on the merchant's side.

func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}

Submission of additional payment information

Generally, for processing a payment, it is enough to send a set of parameters that are mandatory for initiating this payment. Still 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 separate article.

The final set of required parameters can vary depending on a particular provider or payment system. The list of parameters relevant for a particular payment is received in the notification from SDK Core for Android after the request for payment creation (GetPayInteractor) has been sent. The merchant should ensure that the fields to be filled with the required data are displayed to the customer and then send the obtained values to SDK Core for Android.

override fun onClarificationFields(clarificationFields: List<ClarificationField>, payment: Payment) { // receiving the list of the required parameters
    interactor.sendClarificationFields(clarificationFields) // sending the data obtained from the customer
}

Collection of 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 should be requested and mandatory to be specified by the customers, then provide this information to the technical support specialists. For more information about using the capability of collecting additional data, see the separate article.

After receiving the notification with the list of the required parameters from SDK Core for Android, the merchant should display the fields to be filled by the customer in the payment form, send the obtained data to SDK Core for Android, and continue payment processing.

override fun onCustomerFields(customerFields: List<CustomerField>) {  // receiving the list of the required parameters
    interactor.sendCustomerFields(customFields) // sending the data received from the customer
}

Informing about payment session

SDK Core for Android supports sending notifications with the payment session information. Intermediate notifications which are sent during payment session creation fall under the InitDelegate group and provide information about various events and possible errors that can happen before the request for payment creation is sent. Such notifications include the following ones:

• onInitReceived—the payment session has been created in the ecommpay payment platform.

  override fun onInitReceived() {
      val stringResourceManager = msdkSession.getStringResourceManager()
      val title = stringResourceManager.payment.methodsTitle
    
      val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
      val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
    
      val paymentMethods = msdkSession.getPaymentMethods()
      val savedAccounts = msdkSession.getSavedAccounts()
  }

• onPaymentRestored—the payment session has been created with a payment identifier used previously. If the payment has not been assigned a final status yet, you can use the PaymentRestoreRequest method and continue processing the previously initiated payment.

  override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_payment_restore)
          progressDialog = ProgressDialog(this@PaymentRestoreActivity)
          progressDialog.setMessage("Payment restoring")
          progressDialog.setCancelable(false)
          progressDialog.show()
  
          interactor.execute(PaymentRestoreRequest(), this)
      }

• onError—an error has occurred.

  override fun onError(code: "Network & Server API", 
  message: "{"status":"validation","code":"501",
  "errors":{"sid":"Make payment before check status"}}")

Informing about payment

Intermediate and final notifications sent during payment creation fall under the PayDelegate group. Such notifications can contain the information about a payment status, the requirement of performing additional actions, and arising errors.

• onPaymentCreated—the payment has been created.
• onStatusChanged—the payment status has been changed.
• onCustomerFields—additional customer data is required.
• onThreeDSecure—3-D Secure authentication is required.
• onClarificationFields—additional payment information is required.
• onCompleteWithSuccess—the payment has been completed.
• onCompleteWithFail—the payment has been rejected.
• onCompleteWithDecline—the payment has been declined.
• onError—an error has occurred.

  override fun onError(code: "Network & Server API", 
  message: "{"status":"validation","code":"501",
  "errors":{"sid":"Make payment before check status"}}")