Android SDK and example app

Introduction

The native SDK for Android helps you to communicate with the Client API. It offers

• convenient Java wrappers for API responses,
• caching of payment product logos and caching of images used to offer additional information about payment products,
• localization of various labels and messages,
• user-friendly formatting of payment data such as card numbers and expiry dates,
• validation of input,
• a check to determine to which payment provider a card number is associated, and
• handling of all the details concerning the encryption of payment details.

Its use is demonstrated by an example app, which constructs the user interface elements used throughout the payment process on the fly. The source code of the SDK and the example app are available on Github . There you can also find installation instructions.

The main payment steps

Setting up and completing a payment using the Android SDK requires the following steps:

1. Initialize the Android SDK. This is done using information such as session and customer identifiers, connection endpoints and payment information like currency and total amount.
2. Retrieve the payment items and accounts on file that can be used for this payment from the Client API. Your app can use this data to create the payment product selection screen.
3. Retrieve all the details about the payment product fields from the Client API. Your app can use this information to create the payment product details screen. Your customer will need to provide the information requested, based on the selected payment product or account on file.
4. Encrypt all the provided payment information using the Client API. Your app sends the encrypted result to your e-commerce server, which sends it to our Server API.
5. Use the response from the Server API call to guide the customer to the next step in the payment process. This can be a simple "payment successful" or "payment failed" screen or a redirect to a third party that completes the payment.

These steps are explained in more detail in the next paragraphs.

Initialize the Android SDK

Once the SDK is initialized you can use the singleton class ConnectSDK from anywhere in your application. This class contains the Client API class that gives access to all calls to the Worldline platform.

To initialize the SDK, you have to provide the SDK with the required authentication information to connect the Client API. Also required is the payment context, needed to return the correct data.

This information can be provided using the parameters ConnectSDKConfiguration and PaymentConfiguration. The ConnectSDKConfiguration object also has some optional properties:

• SessionConfiguration object (mandatory)
• ApplicationContext (mandatory)
• enableNetworkLogs (optional)
• preLoadImages (optional)
• applicationId (optional)
• ipAddress (optional)

The PaymentConfiguration object needs the following information:

• paymentContext (mandatory)
• groupPaymentProducts (optional)

The code fragment below shows how initialize the SDK.

val connectSDKConfiguration = ConnectSDKConfiguration.Builder(
            sessionConfiguration,
            context
        )
            .enableNetworkLogs(false)
            .preLoadImages(false)
            .applicationId("my application name")
            .build()

        val paymentConfiguration = PaymentConfiguration.Builder(paymentContext)
            .groupPaymentProducts(false)
            .build()

        ConnectSDK.initialize(connectSDKConfiguration, paymentConfiguration)

Session configuration

SessionConfiguration must be initialized with the information needed to authenticate with our servers. This can be retrieved by making a Client Session API request using one of our Server SDKs. The following data will be returned, and serve as input for SessionConfiguration:

• A client session identifier and a customer identifier, which identify you and the created session.
• The client-api-url and asset-url that the SDK will connect to. The asset-url serves static resources that are used by the SDK, such as logos of payment products and tooltip images.

Payment context

PaymentContext holds the information needed to request available payment items, such as an AmountOfMoney object that contains a total amount and a currency code, a country code, and a setting for whether the payment is a single payment or a recurring payment.

Making requests to the Client API

The class ClientApi wraps the Worldline Connect API, making it easy for you to send and receive network requests. An instance of ClientApi can be obtained from ConnectSDK after initialization. All Client APIs are available through the SDK. When making a request, the result will be one of three statuses:

1. Success, the call was successful and a response object is returned.
2. Error, the call failed and an ApiErrorResponse object is returned.
3. Failure, an unknown error has occurred and a throwable is returned.

Get payment items

When retrieving payment Items, all methods that are available within the current payment context are returned. This includes payment products, groups and accounts on files. These are then bundled into a list as BasicPaymentItems. Possible AccountOnFiles are in a separate list. The code fragment below shows how an instance of BasicPaymentItems can be obtained.

 ConnectSDK.getClientApi().getPaymentItems(
            { basicPaymentItems: BasicPaymentItems ->
                // Process basicPaymentItems object
            },
            { apiError: ApiErrorResponse ->
                // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

BasicPaymentProduct & BasicPaymentProductGroup

The SDK offers four classes to represent information about payment products: BasicPaymentProduct, its subclass PaymentProduct, BasicPaymentProductGroup and its subclass PaymentProductGroup. Practically speaking, instances of BasicPaymentProduct and BasicPaymentProductGroup contain the information to display a payment product (group) distinguishable from others in a list of available options.

Use the information in PaymentItems and the instances of BasicPaymentProduct and BasicPaymentProductGroup it contains, to display a list of available payment items. Each instance of BasicPaymentProduct contains

• an identifier,
• a field indicating the payment method of this product,
• a field indicating the payment product group this product belongs to,
• two fields that indicate the minimal and maximal amount required to pay with this payment product,
• a field indicating whether payment data can be stored as an account on file,
• a field indicating whether payment data can be stored automatically as an account on file,
• a field indicating whether or not a recurring payment can be processed with this payment product,
• a field indicating whether the payment method uses a redirect to a 3rd party,
• a MobileIntegrationLevel indicating whether there is optimised, basic or no mobile support for this payment product,
• a list of accounts on file for this payment product,
• display hints that can be used to render the BasicPaymentProduct, containing:
  • an index indicating at which position the payment product belongs in a list of payment products,
  • a label, and
  • a logo.

Instances of BasicPaymentProductGroup contain

• an identifier,
• a list of accounts on file for payment products in this group,
• display hints that can be used to render the BasicPaymentProductGroup, containing:
  • an index indicating at which position the payment product belongs in a list of payment products,
  • a label, and
  • a logo.

AccountOnFile

Instances of the class BasicPaymentProduct and BasicPaymentProductGroup also contain a list of accounts on file that are available within the session. An AccountOnFile contains the following fields

• an identifier for the account on file,
• an identifier for the corresponding payment product,
• a collection of key value pairs that have been stored as part of the account on file,
• display hints that contain information about how the account on file should be rendered
• a method that produces a label that describes the account on file.

Get payment product

This method retrieves a single payment product, containing all details, including field information that can be used to show a payment product detail page. The code fragment below shows how a PaymentProduct call can be made.

 ConnectSDK.getClientApi().getPaymentProduct(paymentProductId = "1",
            { paymentProduct: PaymentProduct ->
                // Process paymentProduct object
            },
            { apiError: ApiErrorResponse ->
                // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

Get payment product group

This method retrieves a single payment product group. Currently the only available group is "cards". The code fragment below shows how a PaymentProductGroup call can be made.

 ConnectSDK.getClientApi().getPaymentProductGroup(paymentGroupId = "cards",
            { paymentProductGroup: PaymentProductGroup ->
                // Process paymentProductGroup object
            },
            { apiError: ApiErrorResponse ->
                // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

PaymentProduct & PaymentProductGroup

The classes PaymentProduct and PaymentProductGroup extend BasicPaymentProduct and BasicPaymentProductGroup, and therefore contain the same information that can be used to display them. They also contain extra information in the form of PaymentProductFields. For some payment products, the customer is required to provide additional information, such as an address, a bank account number, a credit card number, or an expiry date. Each payment item can have a number of fields that need to be provided to process a payment. These fields need to be displayed to your customer, so that they can provide the information.

PaymentProductField

The fields of payment items are represented by instances of PaymentProductField. Each field has an identifier, a type, a list of restrictions that apply to the value of the field, and information about how the field should be presented graphically to the customer. Additionally, there are some helper functions that can be used to determine whether a given value is a valid value for the field.

In the code fragment below, the field with identifier “cvv” is retrieved from a payment product. The data restrictions of the field are inspected to see whether this field is a required field or an optional field. Additionally, the display hints of the field are inspected to see whether the values a customer provides should be obfuscated in a user interface. Finally, the value “123” is validated and the number of validation errors is inspected to see whether the provided value is valid.

val field = paymentProduct.getPaymentProductFieldById("cvv")
val isRequired = field.getDataRestrictions().isRequired()

val errorMessageIds = field.validateValue("123")
val isFieldValid = errorMessageIds.isEmpty()

ValidationErrorMessage, ValidationRule and its subclasses

The class PaymentProductField contains a list of instances of ValidationRule, which determine how a field value is validated. When validating a value of a PaymentProductField, all those validation rules are applied to the value of the field. This returns a list of instances of ValidationErrorMessage, each containing a translatable error message identifier, and the corresponding ValidationRule. When translating this error message identifier, you can use the ValidationRule that triggered the validation error to get additional information that you can show to the customer. For example, the minlength and maxlength properties on a ValidationRuleLength indicate the smallest and largest valid field values. This error can be used to give customers feedback when there are issues with the information they provide. The following subclasses of ValidationRule have extra information that can be used while constructing an error message:

• ValidationRuleLength indicates that the supplied value has an invalid length. The minimal length is defined by the property minLength and the maximal length is defined by the property maxLength.
• ValidationRuleRange indicates that the supplied value does not fall within the required range of values. The smallest value is defined by the property minValue and the largest value is defined by the property maxValue.

Get IIN details

The first six digits of a payment card number are known as the Issuer Identification Number (IIN). An instance of ClientApi can be used to check which payment products are associated with an IIN. The check is performed asynchronously, which means that the result of the check is not available immediately. The result of this check is an instance of IinDetailsResponse. This class has a couple of properties, being:

• An IinStatus that indicates the result of the check. The different possible statusses are:
  • The value SUPPORTED indicates that the IIN is associated with a payment product that is supported by the Worldline platform.
  • The value UNKNOWN indicates that the IIN is not recognized.
  • The value NOT_ENOUGH_DIGITS indicates that fewer than six digits have been provided.
  • The value EXISTING_BUT_NOT_ALLOWED indicates that the IIN is recognised, but that it cannot be payed with in the current situation.
• A field that holds the identifier of the primary payment product that is associated with this IIN.
• A field that holds the country code of the primary payment product that is associated with this IIN.
• A field that indicates whether it is allowed to do a payment with the primary payment product based on the payment context.
• A list of instances of IinDetail, which depict co-brands for the current IIN.

It is possible that a single credit card has multiple brands associated to it. We call these co-brands. The details of the first payment product, that can be payed with in the current payment context, are always stored in the toplevel fields of the IinDetailsResponse. If a card is a multibranded card, the list of instances of IinDetail contains all brands associated with the card, including the payment product that is stored in the toplevel fields. This list should be used to provide your customer with the option to select the brand they want to use for the current payment. If there is only one payment product associated with the credit card the list of IIN Details is empty.

If the value of status is not SUPPORTED the other fields of IinDetailsResponse will all be null (or false in case of the isAllowedInContext field).

The code fragment below shows how an instance of IinDetailsResponse can be obtained.

ConnectSDK.getClientApi().getIINDetails(bin = "411111",
            { iinDetailsResponse: IinDetailsResponse ->
                // Process iinDetailsResponse object
            },
            { apiError: ApiErrorResponse ->
                // log error
            },
            { failure: Throwable ->
                // Indicate that an error occurre
            }
        )

Convert amount

To help converting amounts from one currency to another, the SDK offers the convertAmount method of the ClientApi class. This method takes an amount in cents, and a source and target currency, which are both three-letter ISO currency codes, and returns the converted amount in cents. The code fragment below shows how an amount can be converted.

ConnectSDK.getClientApi().convertAmount(source = "EUR", target = "USD", amount = 100,
            { convertedAmount: Long ->
                // Process converted amount
            },
            { apiError: ApiErrorResponse ->
                // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

Get drawables

If you disabled the preLoadImages property when initializing the SDK, you are responsible for retrieving logos and tooltip images. You can use this method or use your own implementation. If you choose to use this method, you can omit the asset-url, which is automatically added by the SDK. The code fragment below shows how an drawable can be obtained.

 ConnectSDK.getClientApi().getDrawableFromUrl(drawableUrl = "url/example.png",
            { drawable: Drawable ->
                // Process drawable
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

Get third party status

Polls a third party for the status of the payment.

Currently only available for payments performed with payment products 3012 (Bancontact) and 863 (WeChat Pay). In the case of Bancontact, it is used to determine if the customer is paying using the Bancontact app and if so, what the payment status is. The code fragment below shows how a ThirdPartyStatus can be obtained.

  ConnectSDK.getClientApi().getThirdPartyStatus(paymentId = "payment id",
            { thirdPartyStatus: ThirdPartyStatus ->
                // Process thirdPartyStatus object
            },
            { apiError: ApiErrorResponse ->
                // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

Get payment product directory

Certain payment products have directories that the consumer needs to pick from. An example is the list of banks for the Dutch iDeal payment product from which the consumer needs to select a bank. If you want to retrieve the directory information, you can use the getPaymentProductDirectory method of the ClientApi class.

This method takes a payment product identifier and returns an instance of PaymentProductDirectoryResponse, as shown in the code fragment below.

 ConnectSDK.getClientApi().getPaymentProductDirectory(paymentProductId = "809",
            { paymentProductDirectoryResponse: PaymentProductDirectoryResponse ->
                // Process paymentProductDirectoryResponse object
            },
            { apiError: ApiErrorResponse ->
               // Indicate that an API error occurred
            },
            { failure: Throwable ->
                // Indicate that an error occurred
            }
        )

Encrypt payment details

To protect the payment details that are provided by your customer, they must be encrypted before sending them to your servers. The code fragment below shows how ConnectSDK can be used to encrypt an instance of PaymentRequest. The result is an instance of the class EncryptedPaymentRequest which contains two properties, encryptedFields and encodedClientMetaInfo. These should be sent to the Worldline platform from your e-commerce server in the Create Payment API.

ConnectSDK.encryptPaymentRequest(
            paymentRequest,
            { encryptedPaymentRequest: EncryptedPaymentRequest ->
               // Process encryptedPaymentRequest object
            },
            { failure: Throwable ->
               // Indicate that an error occurred
            }
        )

Payment request

When your customer selected a payment product and you have retrieved this product from the API, a payment request can be constructed. In the payment request, the payment details can be stored, such as the product retrieved, field values and other payment settings. The code fragment below shows how to construct a payment request.

val paymentRequest = PaymentRequest().apply {
            paymentProduct = paymentProduct
            accountOnFile = accountOnFile
            tokenize = false
            setValue("cardNumber","4111111111111111")
            setValue("expiryDate", "1225")
            setValue("cardholderName", "John Doe")
            setValue("cvv", "123")
        }

        if (paymentRequest.validate().isNullOrEmpty()) {
            // encrypt payment request
        } else {
            // Indicate that an validation error occurred
        }

Once all values have been provided, the payment request can be used to validate the values, as shown below. After validation, a list of errors is available. If this list is empty, the provided values are valid and the payment request is ready for encryption.

val validationResult = paymentRequest.validate()
if (validationResult.size() > 0) {
    // Notify the customer that some fields contain invalid data.
} else {
    // The payment request is valid, and can be encrypted and sent to
    // the Worldline platform via the merchant's server.
}

Logging

During development, you may want to turn on logging of the requests and responses that make up the communication with Worldline. You can enable request and response logging in the SDK by initializing with "enableNetworkLogs" set to "true".

Example app

The example app illustrates the possibilities of the Android SDK and the services offered by the Worldline platform. Its source code is available on Github . The example app consists of four screens:

• The first screen asks for the information necessary to communicate with the Client API and retrieves a list of payment products. This screen should not be part of an actual app in the app store. It is provided to illustrate which information is needed to initialize an instance of the ConnectSDK.
• The second screen is a dynamically generated payment item selection screen. Based on the input provided in the first screen, a list of available payment items and previously stored accounts on file is shown. This screen or a similar screen would typically be part of an actual app.
• After selecting a payment item, the third screen is shown. This screen requests the information needed to complete the payment for the selected payment product. The provided information can only be submitted by the customer if it has been validated by the SDK. Also this screen or a similar screen would be part of an actual app.
• The fourth screen indicates that the initiated payment has been successfully processed by the SDK. This screen should not be part of an actual app in the app store.