Mobile Lite SDK Integration

Zelle Toolkit Mobile SDK is a comprehensive native SDK built with native JAVA and Swift languages which can be added to common Native / Hybrid apps (Cordova, React Native, Xamarin) requiring Zelle Integrations. The following sections describe the steps to integrate and use the SDK in native apps.

Android Integration

The following section covers integration requirements for the ZTK Lite SDK to Android applications.

The ZTK Lite SDK supports tablets and mobile devices running on the most recent Android release and is backward compatible up to Lollipop 5.0.

SDK Support

The latest Android SDK is targeted for the ZTK SDK development, which supports the current Android version and is backward compatible to Lollipop 5.0. Requirements include updating the compileSdkVersion and the minSdkVersion in the app level build.gradle as follows:

SDK Versions & Build Tools

VERSIONS	API NUMBER
MinSdk	21
CompileSdk	29
Android Version	5.0 (Lollipop)
BuildTools	30.0.0
Supporting Devices	Phone, Tablet
Supporting Orientations	Portrait, Landscape

Installation

Importing the SDK

In AndroidStudio import the ZTK_Android_Lite_SDK_Release_VX.Y.Z.aar library. Add the following line in the application level build.gradle file; make the project by clicking Build menu -> Make project or sync the gradle to import the aar. The X,Y,Z represent major, minor, build version name in SDK.

implementation project(path: ': ZTK_Android_Lite_SDK_Release_VX.Y.Z ')
implementation 'com.google.code.gson:gson:2.8.6'

Adding SDK Dependencies to the Application Build.Gradle Dependencies:

The below dependencies are required to avoid appcompat and constraint layout compile issues:

ATTRIBUTE	TYPE
implementation	androidx.appcompat:appcompat:1.1.0
implementation	androidx.constraintlayout:constraintlayout:1.1.3

Integration

Contact Integration

Contact Integration dependencies and permissions are added in the SDK; therefore, the required contact permissions are received when the user accesses contacts after the ZTK_Android_Lite_SDK_Release_VX.Y.Z is launched.

Launch Zelle

Initialization

Importing the SDK into the activity and launching Zelle:

import com.jha.library.zelle.mobile.sdk.ZellePaymentLauncher;
import com.jha.library.zelle.mobile.sdk.callback.CallBackInterface;
import com.jha.library.zelle.mobile.sdk.zenum.ScreenType;

CLASS / LIBRARY	PURPOSE
ZellePaymentLauncher	Used to launch Zelle.
CallBackInterface	An interface to get the onSuccess, onFailure, and onCancel call backs from the SDK.

To import callBackInterface add the below code in the activity / fragment:

Import com.jha.library.zelle.mobile.sdk.callback.CallBackInterface

Implement the CallBackInterface in the activity / fragment as below to receive the interface call-backs:

public class <YOUR_ACTIVITY> extends AppCompatActivity implements CallBackInterface

Override methods:

    @Override
    public void onSuccess() {
        Log.d(TAG, "onSuccess() Callback");
    }
    @Override
    public void onFailure(int Error) {
        Log.d(TAG, "onFailure() Callback");
    }
    @Override
    public void onCancel() {
        Log.d(TAG, "onCancel() Callback");
    }

OnSuccess method is called when the ZTK_Mobile_Lite_SDK is successfully loaded.
OnCancel method is used:
- When the SDK needs has be closed.
- When the user clicks the back button in the landing screen.
- When the transaction is successfully completed.
OnFailure method returns error values as int types in the below table and safely closes the SDK:

ENUM	DESCRIPTION
ZTK_TIMEOUT(1000)	ZTK session timeout at React web side.
SDK_EXCEPTION(1002)	SDK Exception.
SDK_ERROR(1003)	SDK Error.
SDK_ACCESS_DENIED(1004)	SDK access denied for unauthorized way of accessing SDK.
ZTK_SSO_ERROR(1010)	ZTK SSO error at React web side.
ZTK_ACCESS_DENIED(1011)	ZTK access denied error at React web side.
SDK_ENVIRONMENT_ERROR(1005)	SDK environment error for passing other than these value PI,PROD,QA,DEV
ZTK_FIID_ENV_ERROR(1012)	The FiID should also be associated with the right environment at the ZTK level. If the FIID is not associated with the environment sent you will get this error code

To get callBackInterface context add this line to the activity / fragment:

    private CallBackInterface callBackInterface;
    this.callBackInterface = this; // add this in activity/ fragment’s onCreate.
    Public CallBackInterface getCallBackInterface(){
        return callBackInterface;
    } 

Launching the SDK

Once the class – “com.jha.library.zelle.mobile.sdk.ZellePaymentLauncher” is imported, the method ZellePaymentLauncher::initZelleSDK can be called to launch the Zelle Experience:

    ZellePaymentLauncher.initZelleSDK(Context context,
        String fiId,
        String jweToken,
        int screenTypeValue,
        CallBackInterface callBackInterface,
        String pid,
        String orientation,
        String EnvID,
    )

    @Deprecated - Will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
        ZellePaymentLauncher.initZelleSDK(Context context,
        String fiId,
        String jweToken,
        int screenTypeValue,
        CallBackInterface callBackInterface,
        String pid
    )

Parameters Explanation

The parameters of the ZellePaymentLauncher::initZelleSDK are explained in the below table:

PARAMETER	TYPE	DESCRIPTION
Context	context	context
fiId	string	The three letter ID of the Financial Institution (Org ID) assigned by the JHA PayCenter install coordinator during on-boarding.
jweToken	string	JWE token as a string to be passed from financial institution app.
screenTypeValue	int	See launch method explanation.
callBackInterface()	callbackInterface	A call back interface to handle call backs.
pId	string	Three letter ID of the technology partner. If there is no technology partner, the value should default to empty string.
orientation	string	null or "" - SKD to support portrait and landscape orientation “PORTRAIT”– SKD to support only portrait orientation “LANDSCAPE” – SKD to support only landscape orientation
EnvID	string	PROD - SKD to use production environment. “PI” – SKD to use partner integration environment. “QA” – SKD to use qa environment. “DEV” – SKD to use development environment.

Activity

Different ENUM values are used to distinguish the screens and based on the ENUM values, the user will be redirected to the expected screen.+

ENUM	PURPOSE
LANDING_SCREEN(0)	Landing Screen
SEND_MONEY(1)	Send Money
REQUEST_MONEY(2)	Request Money
VIEW_ACTIVITY(3)	View Activity
MANAGE_RECIPIENT(4)	Manage Recipient
SETTINGS(5)	Setting

Use these ENUM to redirect the user to the corresponding screen in the SDK. E.g. usage - Screen-Type.VIEW_ACTIVITY.getValue().

note

The SDK status bar uses FI status bar theme/color, usage of the translucent status bar will get overlapped status bar and app content in SDK. If you are using translucent status bar in FI app Kindly remove the translucent status bar and add a solid FI color to SDK.

Remove:

<item name="android:windowTranslucentStatus">true</item>

Add:

<item name="android:statusBarColor">@color/colorPrimary </item>

IOS Integration

The following section covers integration requirements for the ZTK Lite SDK to an FI application on iOS. The ZTK Lite SDK supports iPads and iPhone devices running on the latest available versions and is backward compatible to iOS 10.0.

SDK Support

The latest SDK is targeted for the SDK development as described in the below table.

Deployment Target

ATTRIBUTE	VALUES
Deployment Target	10
Supporting Device	iPhone, iPad
Supporting Orientations	Portrait, Landscape

note

If the deployment target must be changed, navigate to General -> Deployment Info.

Installation

Importing SDK

Drag and drop the framework into the project, validating the target while adding the framework.

Integration

Contact Integration

The below mentioned key / value pair must be added to the info.plist to support contact integration:

KEY	VALUE
Privacy - Contacts Usage Description	Contacts list used for creating recipients.

Launch Zelle

Initializaton

Add the following snippet in the AppDelegate file:

Objective – C:

#import <ZTK/ZTK.h>

Swift:

import ZTK

Launching the SDK

After importing the ZTK, launchZelle method is called inside the ViewController class as below:

    func launchZelle( fiId:  String,
        jwtToken: String,
        screenType: ScreenType,
        pid: String?,
        sourceViewController: UIViewController
                orientation: String?,
    EnvID: String) - This method directly launches the Zelle experience.
    func launchZelle( fiId:  String,
                jwtToken: String,
        screenType: ScreenType,
        pid: String?,
        sourceViewController: UIViewController
                orientation: String?,
    EnvID: String)  -> UIViewController  - This method FI side need to handle the present and dismiss the Zelle experience.

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    func launchZelle( fiId: String,
        jwtToken: String,
        screenType: ScreenType,
        pid: String?,
        sourceViewController: UIViewController
    ) - This method directly launches the Zelle experience.

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    func launchZelle( fiId: String,
        jweToken: String,
        screenType: ScreenType,
        deepLinkURL: String?,
        pid: String? ) -> UIViewController  - This method FI side need to handle the present and dismiss the Zelle experience.

Parameter Explanation

The table below captures the details of the parameters.

PARAMETER	TYPE	PURPOSE
fiId	string	The three letter ID of the Financial Institution (Org ID) assigned by the JHA PayCenter install coordinator during on-boarding.
jweToken	string	JWE token as a string.
screenType	int	Enum value for the screen to launch.
pId	string	Three letter ID of the technology Partner ID
sourceViewController	viewcontroller	Source view controller.
orientation	string	nil or "" - SKD to support portrait and landscape orientation PORTRAIT- SKD to support only portrait orientation LANDSCAPE - SKD to support only landscape orientation
EnvID	string	PROD - SKD to use production environment. PI - SKD to use partner integration environment. QA - SKD to use qa environment. DEV - SKD to use development environment.

Use these parameters as follows:

Objective – C:

    [zelleToolKit launchZelleWithFiId:@"FI ID",
        JweToken:@"JWE Token"
        screenType:ScreenTypeLandingScreen
        pid:@"Technology Partner ID"
    sourceViewController:self
    orientation: @"", EnvID: @""]

    UIViewController *zelleViewController = [zelleToolKit launchZelleWithFiId:@"FI ID",
        JweToken:@"JWE Token"
        screenType:ScreenTypeLandingScreen
        pid:@"Technology Partner ID"
    sourceViewController:self
    orientation: @"", EnvID: @""]

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    [zelleToolKit launchZelleWithFiId:@"FI ID",
        JweToken:@"JWE Token"
        screenType:ScreenTypeLandingScreen
        pid:@"Technology Partner ID"
        sourceViewController:self]

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    UIViewController *zelleViewController = [zelleToolKit launchZelleWithFiId:@"FI ID",
        JweToken:@"JWE Token"
        screenType:ScreenTypeLandingScreen
        pid:@"Technology Partner ID"]

Swift:

    zelleToolkit.launchZelle( fiId:  "FI ID",
        jwtToken: Constants.JWEToken,
        screenType: .LandingScreen,
        pid: "Technology Partner ID",
        sourceViewController: self
        orientation: "ORIENTATION”,
        EnvID: "PROD”) - This method directly launches the Zelle experience.

    zelleToolkit.launchZelle(fiId:  "FI ID",
        jwtToken: Constants.JWEToken,
        screenType: .LandingScreen,
        pid: "Technology Partner ID",
        sourceViewController: self
        orientation: "ORIENTATION”,
        EnvID: "PROD”)  -> UIViewController  - This method FI side need to handle the present and dismiss the Zelle experience.

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    zelleToolkit.launchZelle( fiId: "FI ID",
                jweToken: Constants.JWEToken,
                screenType: .LandingScreen,
                pid: "Technology Partner ID",
                sourceViewController: self )

    @Deprecated - Not in use will get removed in future. From sdk version 3.3.5 onwards calling this method directly points to PROD environment.
    let zelleViewController = zelleToolkit.launchZelle( fiId: "FI ID",
                jweToken: Constants.JWEToken,
                screenType: .LandingScreen,
                pid: "Technology Partner ID" )

Activity

ENUM values are used to distinguish the screens, based on the Enum values redirected to the expected screen.

The following Enum values are used navigate to the corresponding screen in the SDK by using it like:

ScreenType.<ENUM_VALUE>.

ENUM	PURPOSE
LandingScreen(0)	Landing Screen
SendMoney (1)	Send Money
RequestMoney (2)	Request Money
ViewActivity (3)	View Activity
ManageRecipients (4)	Manage Recipient
ZelleSettings (5)	Setting

Import And Implement Zelletoolkitdelegate

After the Zelle Toolkit is launched, to determine if it was successful or not, delegates can be used. ZelleToolKitDelegate must be extended into the ViewController to receive didSuccess, didFailure, and didCancel call-backs from the SDK.

Objective – C:

    @interface ViewController ()< ZelleToolKitDelegate >

Swift:

    class ViewController: ZelleToolKitDelegate
Once the ZelleToolKitDelegate is extended, the delegate must also be set.

The below snippet can be used to set the delegate:

Objective – C:

    ZelleToolkit *zelleToolKit = [[ZelleToolkit alloc]init];
    zelleToolKit.delegate = self;

Swift:

    let zelleToolkit = ZelleToolkit()
    zelleToolkit.delegate = self

By extending ZelleToolKitDelegate, a list of call-backs interface will be received in the View Controller.

Objective – C:

   // MARK: - Zelle toolkit delegate
    - (void)didSuccess {
                    NSLog(@"Success");
    }
    // Zelle Toolkit operation error delegate method.
    - (void)didFailure:(Int*)error {
                NSLog(@"Fail");
    }
    // Zelle Toolkit operation cancel delegate method
    - (void)didCancel {
                NSLog(@"Cancel");
    }

Swift:

    func didSuccess() {
        print("Success")
    }
    func didFailure(_ error: int) {
        print("Failure")
    }
    func didCancel() {
        print("Cancel")
    }

didSuccess method returns when the ZTK_Mobile_Lite_SDK is successfully loaded.
didCancel method is used:
- When the SDK needs to be closed.
- When the user clicks the back button in the landing screen.
- When the transaction is successfully completed.
didFailure method returns error values as int types as shown in the below table:

ENUM	DESCRIPTION
ZTK_TIMEOUT(1000)	ZTK session timeout at React web side.
SDK_EXCEPTION(1002)	SDK Exception.
SDK_ERROR(1003)	SDK Error.
SDK_ACCESS_DENIED(1004)	SDK access denied for unauthorized way of accessing SDK.
ZTK_SSO_ERROR(1010)	ZTK SSO error at React web side.
ZTK_ACCESS_DENIED(1011)	ZTK access denied error at React web side.
SDK_ENVIRONMENT_ERROR(1005)	SDK environment error for passing other than these value PI,PROD,QA,DEV
ZTK_FIID_ENV_ERROR(1012)	The FiID should also be associated with the right environment at the ZTK level. If the FIID is not associated with the environment sent you will get this error code

Android Integration​

SDK Support​

SDK Versions & Build Tools​

Installation​

Importing the SDK​

Adding SDK Dependencies to the Application Build.Gradle Dependencies:​

Integration​

Contact Integration​

Launch Zelle​

Initialization​

Launching the SDK​

Parameters Explanation​

Activity​

IOS Integration​

SDK Support​

Deployment Target​

Installation​

Importing SDK​

Integration​

Contact Integration​

Launch Zelle​

Initializaton​

Launching the SDK​

Parameter Explanation​

Import And Implement Zelletoolkitdelegate​

Android Integration

SDK Support

SDK Versions & Build Tools

Installation

Importing the SDK

Adding SDK Dependencies to the Application Build.Gradle Dependencies:

Integration

Contact Integration

Launch Zelle

Initialization

Launching the SDK

Parameters Explanation

Activity

IOS Integration

SDK Support

Deployment Target

Installation

Importing SDK

Integration

Contact Integration

Launch Zelle

Initializaton

Launching the SDK

Parameter Explanation

Import And Implement Zelletoolkitdelegate