SDK Android v2

• Description
• Changelogs
• Installation
• Usage
  • Initialization
  • Configuration
  • Logging configuration
  • UI configuration
  • Card list
  • Hosted Fields
  • Native Card Form
    • Form Display Customization
  • Form Display Customization
  • The DALENYSSDKDelegate object
  • Making a payment
  • 3-D Secure
• Example usage
  • Initialization
  • Delegate handling
  • Payment via BANKCARD account type
  • Payment via Paypal account type
  • Show card list
  • Show hosted fields

Description

The Dalenys Android SDK is a java framework that provides native wrappers for interacting with the Dalenys payment REST API.
For a complete overview of the Dalenys payment system and an explanation of all of the various account types and payment options see the Dalenys developer documentation.

info

Use of the SDK requires a Dalenys account.

Changelogs

Installation

info

The SDK is distributed via Maven on Dalenys Payment’s private repository. You must ask to your payment manager to get an access to this repository in order to install the SDK.

Add the following repositories to your app module’s build.gradle:

repositories {
    maven { url 'https://ASK_TO_YOUR_PAYMENT_MANAGER' }
    maven { url 'https://maven.fabric.io/public' }
    maven { url 'https://jitpack.io' }
}

Add the SDK as a dependency:

implementation ('com.dalenys:dalenyssdk:2.2.0') {
    exclude group: 'com.android.support'
}

Usage

Initialization

DALENYSSDK.getInstance().initialize(getApplicationContext(), configuration);

The initialize method requires two parameters: the application object and an instance of a DALENYSSDK.Configuration object. This object is explained in detail below.

Configuration

The DALENYSSDK.Configuration class is used to configure the SDK and is required for initialization. The class initializer takes 4 parameters :

DALENYSSDK.Configuration configuration = new DALENYSSDK.Configuration(
    String apiKeyId,
    String apiKey,
    String directLinkUrl,
    String redirectUrl
);

• apiKeyId is your Dalenys SDK API KEY ID
• apiKey is your Dalenys SDK API KEY
• directLinkUrl is the URL used to communicate with the Dalenys backend
• redirectUrl is the URL used when redirecting from certain webform payment options such as 3DSECURE, it must match the REDIRECT_URL specified in your account setup in the Dalenys Dashboard

All of these parameters will be communicated to you via your Dalenys account. See here for more information.

In addition to these 4 required parameters, there are two additional configuration options: Logging and UI Configuration.

Logging configuration

You can set the logging level via the setLogLovel(DALENYSSDK.LogLevel) method on the DALENYSSDK.Configuration object:

DALENYSSDK.Configuration configuration = new DALENYSSDK.Configuration(...)
    .setLogLevel(DALENYSSDK.LogLevel.full);

The available levels are:

• .none
• .error
• .full

UI configuration

You can configure the UI of the SDK to match your app’s theme.
The elements available for customization can be found in the DPUiConfig class and can be set with the .setUiConfig() method of DALENYSSDK.Configuration:

DPUiConfig uiConfig = new DPUiConfig(this)
                        .setPrimaryColor(Color.parseColor("#ffffff"))
                        .setErrorColor(Color.parseColor("#ff0000"))
                        // other UI configuration options here

DALENYSSDK.Configuration configuration = new DALENYSSDK.Configuration(...)
                        .setUiConfig(uiConfig);

Available options include:

• setPrimaryColor(int)
• setSeparatorColor(int)
• setButtonTextColor(int)
• setHintColor(int)
• setTextColor(int)
• setErrorColor(int)
• setToolbarColor(int)
• setEdittextBackgroundColor(int)
• setScreenBackgroundColor(int)
• setLogo(Drawable)
• setShowCvvValidation(boolean)

All DPUiConfig parameters are optional. For an up-to-date list, see the API Reference.

Card list

As of version 2.0.0, you are responsible for saving the card alias and associated information. You can still use the SDK to present a list of cards to the user.

To show the card list, you first need to construct an array of DPCardInfo objects and call the SDK’s showCardList method:

List<DPCardInfo> cards;
//Set the card list
DALENYSSDK.getInstance().showCardList(paymentParams, cards);

Here is the structure of DPCardInfo

public DPCardInfo(String alias, String label, String expiryDateStr, String cardFullName, DPCardType type) {
        this.alias = alias;
        this.label = label;
        this.cardValidityDate = expiryDateStr;
        this.cardFullName = cardFullName;
        this.cardNetwork = type;
    }

To receive events from the card list you need to register a DPCardListDelegate object (usually in your activity’s onCreate() override)

DALENYSSDK.getInstance().registerCardlistDelegate(this);

And unregister it when you are done, usually in onDestroy():

DALENYSSDK.getInstance().unregisterCardlistDelegate();

A DPCardListDelegate must implement two methods:

• void cardDidSelect(DPCardInfo cardInfo): notifies the delegate that the user has selected a card
• void addButtonDidClicked(): notifies the delegate that the user wants to pay with a new card

info

You can also create your own card list. In this case, you need to set the alias on the operation params.

Example:

    private void onCardSelected(String alias){
        DPPaymentParamsBankCard paymentParams = new DPPaymentParamsBankCard();
        paymentParamsBankCard.setAlias(alias);

        //Add other datas

        DALENYSSDK.getInstance().payment(identifier, amount, clientIdent, cartDescription, orderId, paymentParams);
    }

Hosted Fields

The hosted-fields mode is the best compromise between security, ease of customization and payment form integration.

This integration mode aims to diminish your PCI-DSS constraints down to SAQ-A level requirements.

For more information about the technical implementation of hosted-fields mode, see the REST API documentation

info

In the latest version of the SDK, hosted fields is the preferred payment mode. The native payment-form mode is deprecated and will be removed shortly.

To display your Hosted Fields form, call the SDK’s showHostedFields(String) method:

String url = "https://...";
DALENYSSDK.getInstance().showHostedFields(url)

Your are responsible of the HostedFields Webpage. When the HFToken will be returned by the Dalenys Javascript SDK, call the dalenyssdk://hostedfields url with result parameters described below. The SDK will intercept this url and transform Url Encoded Data into a DPHostedFieldsResult.

The accepted url encoded keys are :

• hfToken as String
• cardFullName as String
• createAlias as boolean
• cardType as String. The accepted values are :
  • unknown
  • cb
  • visa
  • mastercard
  • bancontact
  • sepa
  • americanExpress
• cardCode as String
• cardValidityDate as String (MM-YY)

You can add other parameters in the redirect url. They will be stored into vendorDatas.

To receive events from the hosted fields form, you need to register a DALENYSHostedFieldsDelegate object (usually in your activity’s onCreate() override). This is done directly on the DALENYSSDK class:

DALENYSSDK.getInstance().registerHostedFiledsDelegate(this);

And unregister it when you are done, usually in onDestroy():

DALENYSSDK.getInstance().unregisterHostedFieldsDelegate();

A DALENYSHostedFieldsDelegate must implement one method:

• void deliverHostedFieldsResult(DPHostedFieldsResult hostedFieldsResult): the delegate receives the result of the hosted fields in the form of a DALENYSSDK.DPHostedFieldsResult object.

Native Card Form

For credit card operation, the SDK presents a form so the user can complete their personal details.

info

if the payment method is called with an implementation of DPAliasable and no alias or hftoken is provided, the SDK will automatically show the native card form.

Form Display Customization

The SDK exposes four customization options that allow you to control the fields that will be displayed.

Three of these options are found on the DPAliasable interface which you use via one of it’s concrete subclasses of DPPaymentParamsAliasable or DPAuthorizationParamsAliasable :

• showCreateAlias: If true, the option to save the card for future use will be displayed. Default is false
• hideCardFullName: If true, the DPBasePayAuthParams.cardFullName field will be hidden. Default is false
  • Note: if set to true, the cardFullName must not be null
• hideClientEmail: If true, the DPPaymentParamsBankCard.clientEmail field will be hidden. Default is false
  • Note: if set to true, the clientEmail must not be null

The fourth option is found on DPUiConfig:

• setShowCvvValidation(boolean): If false, the CVV textfield will not be displayed on the validation screen for a One-click payment. The default is true

Form Display Customization

For credit card payments, the SDK presents a form so the user can complete their personal details. The SDK exposes four customization options that allow you to control the fields that will be displayed.

Three of these options are found on the DPAliasable class, which you use via one of it’s concrete subclasses (DPPaymentParamsAliasable, DPAuthorizationParamsAliasable):

And the fourth option is found on DPUiConfig:

The DALENYSSDKDelegate object

When you are ready to make a payment via the SDK, you first need to register a delegate object, usually in your activity’s onCreate():

DALENYSSDK.getInstance().registerDelegate(this);

And unregister it when you are done, usually in onDestroy():

DALENYSSDK.getInstance().unregisterDelegate();

In order for your activity to act as a delegate, you must implement the interface DALENYSSDKDelegate:

public class MainActivity extends AppCompatActivity implements DALENYSSDK.DALENYSSDKDelegate

There are 3 delegate methods:

• getContext(): returns the app context that will be used to present the SDK’s internal user interface.
• logged(String s): receives all text that is logged to the console by the SDK
• deliveryResult(DPResult b2BResult): receives the result of an operation in the form of a DPResult object.
• userDidCancelTransaction(): Call when user cancel the current transaction

Making a payment

Currently the Dalenys SDK supports two operation types: Payment and Authorization. To make a payment, you use the method payment():

DALENYSSDK.getInstance().payment(
        String identifier,
        DPAmount amount,
        String clientIdent,
        String cartDescription,
        String orderId,
        DPPaymentParams options
);

where

• identifier: The identifier of the Dalenys account that you want to receive payment on
• amount: A DPAmount instance representing either a single or n-times payment amount
• clientIdent: The client’s identifier
• cartDescription: a description of the cart
• orderId: The client’s order ID
• options: an instance of one of the available account types (ex. DPPaymentParamsBankCard)

info

The DPBaseParams and its subclasses provide three types of information to the SDK:

• The class type (ex. DPPaymentParamsPaypal) provides the account type to be used for this transaction (in this case, Paypal)
• The operation type (ex. .payment or .authorization) to be used for this transaction
• The transaction parameters (ex. clientEmail, shipToFirstName, etc.)

For more information on DPBaseParams see the API Reference and the Dalenys Documentation

info

The DPAmount encapsulates a transaction amount and has 2 usable subclasses:

• DPSingleAmount: specifies a one-time payment
• DPMultipleAmount: specifies an n-times payment

These classes are instantiated with the static methods singleAmount(String, Locale) and multipleAmount(Locale) on the DPAmount class, where the locale is the locale of the client’s selected currency. The locale is only used to display the currency symbol and is not transmitted to the Dalenys backend. The currency is tied to the vendor account used for the transaction, it is not controlled by the SDK.

For more information on DPAmount see the API Reference.

3-D Secure

warning

From Android 2.2.0, the 3DSECURE field has been deprecated. Use the 3DSECUREPREFERENCE field to control the triggering of the 3DS.

Here are the possible values:

• sca ask for a strong authentication;
• frictionless ask for a frictionless authentication;
• nopref or absent, the decision will be made by Dalenys;
• scamandate strong authentication required by regulation

Example:

I want to activate 3DS => 3DSECUREPREFERENCE = SCA ou SCAMANDATE

Example usage

Initialization

public class TestApp extends Application {


    @Override
    public void onCreate() {

        super.onCreate();

        // Configure UI

        DPUiConfig uiConfig = new DPUiConfig(this)
                .setPrimaryColor(ContextCompat.getColor(this, R.color.colorPrimary))
                .setSeparatorColor(Color.GRAY)
                .setButtonTextColor(Color.BLUE)
                .setHintColor(Color.GREEN)
                .setTextColor(Color.BLACK)
                .setErrorColor(Color.RED)
                .setToolbarColor(ContextCompat.getColor(this, R.color.colorPrimary))
                .setEdittextBackgroundColor(Color.WHITE)
                .setScreenBackgroundColor(Color.WHITE)
                .setLogo(ContextCompat.getDrawable(this, R.mipmap.ic_launcher))
                .setShowCvvValidation(true);


        // Configure SDK

        DALENYSSDK.LogLevel logLevel;
        if(BuildConfig.DEBUG) {
            logLevel = DALENYSSDK.LogLevel.full;
        } else {
            logLevel = DALENYSSDK.LogLevel.none;
        }

        DALENYSSDK.Configuration configuration = new DALENYSSDK.Configuration(
                "MyAPIKeyId,
                "MyAPIKey",
                "MyDirectLinkUrl",
                "MyRedirectUrl"
        )
        .setLogLevel(logLevel)
        .setUiConfig(uiConfig);

        // Initialize
        try {
            DALENYSSDK.getInstance().initialize(this, configuration);
        } catch (Throwable t) {
            t.printStackTrace();
        }
    }

}

Delegate handling

public class MainActivity extends AppCompatActivity implements DALENYSSDK.DALENYSSDKDelegate {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        DALENYSSDK.getInstance().registerDelegate(this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

        DALENYSSDK.getInstance().unregisterDelegate();
    }

    @Override
    public void deliverResult(DPResult dpResult) {
        if(dpResult.getExecCode() == DPExecCode.success) {
            Toast.makeText(getContext(), "success", Toast.LENGTH_SHORT).show();
        } else {
            Toast.makeText(getContext(), dpResult.getError().toString(), Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public Context getContext() {
        return this;
    }

    @Override
    public void logged(String s) {
        // can be used to display logging info in-app
    }

    @Override
    public void userDidCancelTransaction () {
        // Handle the cancel action
    }
}

Payment via BANKCARD account type

private void payWithBankcard() {

    DPPaymentParams options = new DPPaymentParamsBankCard();
    options.threeDsecure = true;
    // set other parameters here, see the API Reference for more info

    String identifier = "myDalenysVisaAccountIdentifierInUSD";

    DPAmount amount = DPAmount.singleAmount("10000", new Locale("en", "US"));

    DALENYSSDK.getInstance().payment(
            identifier,
            amount,
            "my client's identifier",
            "my client's cart description",
            "my client's order ID",
            options
    );
}

Payment via Paypal account type

private void payWithPaypal() {

    DPPaymentParams options = new DPPaymentParamsBankCard();
    options.clientEmail = "test@test.com";  // PayPal requires the client email
    // set other parameters here, see the API Reference for more info

    String identifier = "myDalenysPayPalAccountIdentifierInEUR";    // Dalenys PayPal accounts only accept euros

    DPAmount amount = DPAmount.singleAmount("10000", new Locale("fr", "FR"));

    DALENYSSDK.getInstance().payment(
            identifier,
            amount,
            "my client's identifier",
            "my client's cart description",
            "my client's order ID",
            options
    );
}

Show card list

public class MainActivity extends AppCompatActivity implements DALENYSSDK.DALENYSSDKDelegate, DALENYSSDK.DPCardListDelegate {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        DALENYSSDK.getInstance().registerCardlistDelegate(this);
        DALENYSSDK.getInstance().registerDelegate(this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

        DALENYSSDK.getInstance().unregisterDelegate();
        DALENYSSDK.getInstance().unregisterCardlistDelegate();
    }


    private void showCardList(DPBasePayAuthParams paymentParam){

            String alias = "aerchbezdznnlezel";
            String label = "MyVisaCard";
            String expiryDateStr = "12-20";
            String cardFullName = "ABC";
            String type = DPCardType.cb;

            DPCardInfo cardInfo1 = new DPCardInfo(alias, label, expiryDateStr, cardFullName, type);

            List<DPCardInfo> cards = new ArrayList();
            cards.add(cardInfo1);

            DALENYSSDK.getInstance().showCardList(paymentParams, cards);
    }

    @Override
    public void cardDidSelect(DPCardInfo cardInfo) {
        //Put the DPCardInfo datas in the DPAliasable instance
    }

    @Override
    public void addButtonDidClicked() {
        //Show the hosted fields form, or the native card form
    }
}

Show hosted fields

public class MainActivity extends AppCompatActivity implements DALENYSSDK.DALENYSSDKDelegate, DALENYSSDK.DPHostedfieldsDelegate {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        //register to the SDK delegates
        DALENYSSDK.getInstance().registerHostedFiledsDelegate(this);
        DALENYSSDK.getInstance().registerDelegate(this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

        //unregister to the SDK delegates
        DALENYSSDK.getInstance().unregisterDelegate();
        DALENYSSDK.getInstance().unregisterHostedFieldsDelegate();
    }


    private void showHostedFields(){
            String hostedFieldsUrl = "https://..."

            //Call the showHostedFields method to show the webpage associated with the hostedFieldsUrl
            DALENYSSDK.getInstance().showHostedFields(hostedFieldsUrl);
    }

    @Override
    public void onHostedFieldsResult(DPHostedFieldsResult result) {
        //Store result data into DPHostedFieldsParams subclass
        DPPaymentParamsBankCard paymentParam = new DPPaymentParamsBankCard();
        paymentParam.setHfToken(result.hfToken);
        paymentParams.cardFullName = result.cardFullName;

        // configure more options here, see API Reference for more
        DALENYSSDK.getInstance().payment(identifier, amount, clientIdent, cartDescription, orderId, paymentParams);
    }
}