iOS initialization

Overview

D1Task is the main entry point to D1 SDK. It should be called as soon as the issuer application is launched or at the earliest possible time.

Configure the D1 SDK

1

Create a D1Task instance

D1Task.Builder is used to set a one-time configuration. The values can be retrieved from Thales delivery team.

2

Configure the SDK

After setting up D1Task, the issuer application has to call the D1Task.configure API to initialise the SDK. There are certain parameters that are required to be provided by the issuer application, for example consumerID.

3

Provide configuration parameters

• If the issuer application enables D1 Card Display or D1 Physical Card services, then the ConfigParams.buildConfigCore(consumerID) parameter is required for D1Task.configure.
• If the issuer application enables D1 Tokenization or D1 Push services, then the ConfigParams.buildConfigCore(consumerID) and ConfigParams.buildConfigCard(activity, oemPayType, serviceId, visaClientAppId) parameters are required for D1Task.configure, where the serviceId parameter is only required for Samsung Pay and visaClientAppId parameter is only required for the Visa payment network.

• Since D1 SDK 4.0.0 version, Integrator should not use Debug version of D1 SDK for Release version of application, otherwise D1 SDK will throw ERROR_DEBUG_SDK_USED error.
• Since D1 SDK 3.2.0 version, activity is not mandatory for ConfigParams.buildConfigCard(activity, oemPayType, serviceId, visaClientAppId), the user should pass the activity parameter when calling the D1PushWallet.addDigitalCardToOEM(cardID, oemType, activity, callback) API.
• As D1 SDK may need to be initialized in different places (refer to NFC Payment service initialization), issuer application needs to create multiple D1Task instances. Hence, it is recommended to clean the old D1Task instances, and always use the latest instance.
• consumerID is typically available on the activity level. However, if the issuer application is able to obtain it earlier, the issuer application can call D1Task.configure with the parameter ConfigParams.buildConfigCore(consumerID) once consumerID is ready.
• Android issuer application must use the D1PushWallet API if it supports multiple xPay Wallets such as Samsung Pay and Google Pay.
• For the Visa payment network, Visa Client App ID is required in the buildConfigCard parameter. This value must be the same as defined in the Visa portal.

Examples

D1 Push Single feature initialization

Single feature initialization (Java)

// Ask Thales delivery team for the following information
String d1ServiceUrl = "https://www.123.com";
String issuerID = "IssuerID";
byte[] rsaExponent = new byte[]{};
byte[] rsaModulus = new byte[]{};
String digitalCardUrl = "https://www.456.com";
Context applicationContext = null; // Issuer application should assign the application context.

// Initialize all necessary settings for D1 SDK.
D1Task d1Task = new D1Task.Builder()
        .setContext(applicationContext)
        .setD1ServiceURL(d1ServiceUrl)
        .setIssuerID(issuerID)
        .setD1ServiceRSAExponent(rsaExponent)
        .setD1ServiceRSAModulus(rsaModulus)
        .setDigitalCardURL(digitalCardUrl)
        .build();

// Initialize the required SDKs.
// Application is required to provide consumerId.
String consumerID = "consumerID";
D1Params coreConfig = ConfigParams.buildConfigCore(consumerID);

// Required for Card Processing & Wallet Pay
// Since D1 SDK 3.2.0 version, the first parameter activity is not mandatory during configuration part, user should assign it when calling D1PushWallet.addDigitalCardToOEM() API, which is used to receive callback. D1Task.handleCardResult
// Third parameter is mandatory for Samsung Pay Service ID (Samsung Pay only).
// Last parameter is Visa Client App ID, if the value is not set, then it is assumed that the value is similar with Issuer ID.
D1Params cardConfig = ConfigParams.buildConfigCard(null, OEMPayType.GOOGLE_PAY, null, "visaClientAppId");

D1Task.ConfigCallback<Void> configCallback = new D1Task.ConfigCallback<Void>() {
    @Override
    public void onSuccess(@Nullable Void ignored) {
        // D1 configuration is successful.
    }

    @Override
    public void onError(@NonNull List<D1Exception> exceptions) {
        // D1 configuration failed, check the exception for more details.
    }
};

d1Task.configure(configCallback, coreConfig, cardConfig);

D1 Push Multiple features initialization

Multiple features initialization (Java)

// Request the following information from the Thales delivery team.
String d1ServiceUrl = "https://www.123.com";
String issuerID = "IssuerID";
byte[] rsaExponent = new byte[]{};
byte[] rsaModulus = new byte[]{};
String digitalCardUrl = "https://www.456.com";
Context applicationContext = null; // Issuer application should assign the application context.

// Initialize all the necessary settings for D1 SDK.
D1Task d1Task = new D1Task.Builder()
        .setContext(applicationContext)
        .setD1ServiceURL(d1ServiceUrl)
        .setIssuerID(issuerID)
        .setD1ServiceRSAExponent(rsaExponent)
        .setD1ServiceRSAModulus(rsaModulus)
        .setDigitalCardURL(digitalCardUrl)
        .build();

// Initialize the required SDKs.
// Application is required to provide consumerId.
String consumerID = "consumerID";
D1Params coreConfig = ConfigParams.buildConfigCore(consumerID);

// Since D1 SDK 3.2.0 version, the first parameter activity is not mandatory during configuration part, user should assign it when calling D1PushWallet.addDigitalCardToOEM() API, which is used to receive callback. D1Task.handleCardResult
// Third parameter is mandatory for Samsung Pay Service ID.
// Last parameter is Visa Client App ID, if the value is not set, then it is assumed that the value is similar with Issuer ID.
D1Params spayConfig = ConfigParams.buildConfigCard(null, OEMPayType.SAMSUNG_PAY, "serviceId", "visaClientAppId");
D1Params gpayConfig = ConfigParams.buildConfigCard(null, OEMPayType.GOOGLE_PAY, null, "visaClientAppId");
D1Params d1PayConfig= D1PayConfigParams.getInstance();

D1PushWallet d1PushWallet = d1Task.getD1PushWallet();

D1Task.ConfigCallback<Void> configCallback = new D1Task.ConfigCallback<Void>() {
    @Override
    public void onSuccess(@Nullable Void ignored) {
        // D1 configuration is successful.
    }

    @Override
    public void onError(@NonNull List<D1Exception> exceptions) {
        // D1 configuration failed, check the exception for more details.
        for (D1Exception exception : exceptions) {
            if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_SPAY_NEED_TO_UPDATE) {
                try {
                    d1PushWallet.updateSamsungPay();
                } catch (D1Exception e) {
                    //Handles the error
                }
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_SPAY_SETUP_NOT_COMPLETED) {
                try {
                    d1PushWallet.activateSamsungPay();
                } catch (D1Exception e) {
                    //Handles the error.
                }
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_SPAY_APP_NOT_FOUND) {
                // Request the end user to install Samsung Pay app.
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_SPAY_NOT_SUPPORTED) {
                // Samsung Pay is not supported.
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_GPAY_NOT_SUPPORTED) {
                // Google Pay is not supported.
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_D1PAY_NOT_SUPPORTED) {
                // D1 Pay is not supported.
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE) {
                // Device is unsafe for security reason. All APIs will be disabled.
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE) {
                try {
                    D1PayWallet.reset(context); // issue on D1Pay initialization, we need to reset all D1Pay data
                } catch (D1Exception e) {
                    //Handles the error.
                }
            } else if (exception.getErrorCode() == D1Exception.ErrorCode.ERROR_INVALID_ARGUMENT) {
                // Programmer error, check your data or parameters such as Service ID for Samsung Pay and ensure that your app is registered on the Samsung portal.
            } else {
                // For other errors, please provide the details to support  troubleshooting.
            }
        }
    }
};

// To initialize all SDKs in one line.
d1Task.configure(configCallback, coreConfig, gpayConfig, spayConfig, d1PayConfig);

Wallet-specific requirements

Google Pay

For Google Pay, the Activity.onActivityResult() method must be overridden in order to pass the content back to the SDK for further processing.

Google Pay activity result handling (Java)

// Handling onActivityResult callback
// Activity Result: onActivityResult received in issuer application from GPay SDK is passed back to D1 SDK to handle the result.
@Override
public void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    d1Task.handleCardResult(requestCode, resultCode, data);
}

Samsung Pay

For Samsung Pay, the Samsung Service ID must be specified in the buildConfigCard parameter. The value must be synchronized with that in the Samsung Developer Portal.

Package Name

D1 SDK uses the com.thalesgroup.gemalto.d1 package. Ensure that the classes under this package are used.