Card91 Issue Card Android Library

Card91 Issue Card Android Library Integration
with Native Android Apps

Description

Purpose of this document is to illustrate the method to add Card91 ‘Issue Card’ library to any android native application written in Kotlin invoked either from a fragment or an activity.

Card91 Issue Card library allows developers to add the custom webview component into their layout as per design.

Developers need to get the view onto their activity and through invoking the init() method with certain required parameters mentioned below and a library for issuing a card and creating a card holder.

Installation (Gradle and Manifest Configuration)

Android Minimum Requirements :

Gradle Version - 7.3.3
minSdkVersion - 21
compileSdkVersion - 32
targetSdkVersion - 32

Android Permission on Manifest:

<uses-permission android:name="android.permission.INTERNET" />

Update gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip

Gradle dependencies

dependencies {
  	implementation 'androidx.core:core-ktx:1.9.0'
    implementation 'androidx.appcompat:appcompat:1.5.0'
    implementation 'com.google.android.material:material:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation files('../app/src/main/libs/card91SDK.aar') // add the card91 sdk aar file here
    implementation 'com.github.bumptech.glide:glide:4.12.0'
    implementation 'androidx.core:core-ktx:1.9.0'
    implementation 'androidx.appcompat:appcompat:1.5.0'
    implementation 'com.google.android.material:material:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
    implementation 'com.squareup.okhttp3:okhttp:4.5.0'
    implementation 'com.github.bastiaanjansen:jwt-java:1.2.0'
    implementation 'com.auth0:java-jwt:4.0.0'
    implementation 'com.auth0.android:jwtdecode:2.0.1'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    //
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.9.0'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-scalars:2.4.0'

}

Also enable the binding on the same app gradle file under android tag if the binding has been used

buildFeatures {
       viewBinding true
   }
}

Usage

Below steps is defined to followed to integrate the Library

Add AAR (Android Library Files)

Add the .aar file provided by us at the libs folder on the project eg.(card91SDK.aar)
Keep the aar file at location {Client project location}/app/src/main/libs
Add below line on the app gradle

implementation files('../app/src/main/libs/card91SDK.aar')

implementation(name: 'card91SDK', ext: 'aar' )

📘
Note
Clean and Build the android app to get the dependencies added on to the application

ADD CARD91 ISSUE CARD VIEW COMPONENT ON LAYOUT

Library class will be ready to use after their adding on gradle.
Add Card91SDKWebView onto the layout where the developer wants to use it .
Make sure not to keep any background colour of the webview since it is supposed to be transparent.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".RestAtmPinActivity">
    <com.card91.common.Card91SDKWebView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:id="@+id/transaction_page"
        android:layout_marginBottom="60dp"/>
</androidx.constraintlayout.widget.ConstraintLayout>

SETUP CARD VIEW COMPONENT

Get the instance of the added Card91SDKWebView onto your activity or fragment.
As shown in the example below .
Set the Listener as given below

 class CardSetUpApp  : AppCompatActivity(), Card91SDKWebView.Listener{ // Implement Card91SDKWebView.Listener
     private lateinit var mWebView: Card91SDKWebView
     override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_cardsetup)

        nextbutton = findViewById<Button>(R.id.nextbutton)
        previousButton = findViewById<Button>(R.id.previousbutton)
        submit = findViewById<Button>(R.id.submitbutton)
        mWebView.setListener(this, this)
        mWebView.settings.loadsImagesAutomatically=true;
      	// Below is the custom json which needs to passed in order to create the issue card form
        // Developer can customize the form based on the requirement if one or multiple pages are required to compplete the same
        var fromJsonBody:String ="{\"step1\":[{\"name\":\"fullName\",\"displayText\":\"Full Name\",\"elements\":{\"type\":\"text\",\"defaultValue\":\"\"}},{\"name\":\"mobile\",\"displayText\":\"Mobile No.\",\"elements\":{\"type\":\"text\",\"defaultValue\":\"\"}},{\"name\":\"pan\",\"displayText\":\"PAN\",\"elements\":{\"type\":\"text\",\"defaultValue\":\"\"}},{\"name\":\"nameOnCard\",\"displayText\":\"Name on card\",\"elements\":{\"type\":\"text\",\"defaultValue\":\"\"}}]}"
        Log.e("json for creating the issue card form",fromJsonBody)
        mWebView.init(this, // Instance of the activity from where it is been called
                      "230526135544169ID1OID4070270", // Organization Id of the business
                      "230528190350397ID1CP9723194", // Card program Id of the business
                      "uniqueId", // Uniqueid for validation of webhook call
                      "https://integrations.card91.io/api:3aL900Rl/auth/token", // Auth url which all application has to configure in order to get the business token
                      fromJsonBody,//Refer "customFields" // Below is the custom json which needs to passed in order to create the issue card form
       								 // Developer can customize the form based on the requirement if one or multiple pages are required to compplete the same
                      "transasia",// Tempplate id which card91 will provide for customized look and feel
                      "PROD_SANDBOX", //PROD_SANDBOX for production sandbox or PROD for production environment 
                      "DIGITAL_ONLY_CARD"// eg. DIGITAL_ONLY_CARD, type of card user wanted to generate
                     )
        submit.setOnClickListener(View.OnClickListener {
            mWebView.evaluateScriptOnly("submit");
        })

    }
     // Overriden Card91SDKWebView.Listener call back functions
     override fun onPageStarted(url: String?) {
        Log.w("Page Started", url.toString()) // When page start to load 
    }

    override fun onPageFinished(url: String?) {
        Log.w("Page onPageFinished", url.toString()) // When page load is finished
    }

    override fun onPageError(errorCode: Int, description: String?, failingUrl: String?) {
        Log.w("Page onPageError", description.toString()) // When page load ends with exception
    }

    override fun onCard91Event(type: String?, payload: String) {
        Log.w("SDK res Type and Payload", type.toString()+"+ payload.toString()) 
              /// Refer the section DIFFERENT CALLBACLK EVENTS for all event type 
              // on successfull card creation payload will have the customer id which has been created
    }
 }

Issue card submit form

In order to submit the form client application has to create a "submit" button below added Card91SDKWebView and on click event they have call the method as below

submit.setOnClickListener(View.OnClickListener {
            mWebView.evaluateScriptOnly("submit");
        })

Sample steps JSON for "customFields" param

{
    "step1": [
        {
            "name": "fullName",
            "displayText": "Full Name",
            "elements": {
                "type": "text",
                "defaultValue": "",
              "disabled": true // For making the non editable field pass the value as true 
            }
        },
        {
            "name": "mobile",
            "displayText": "Mobile No.",
            "elements": {
                "type": "text",
                "defaultValue": "",
              "disabled": true // For making the non editable field pass the value as true 
            }
        },
        {
            "name": "pan",
            "displayText": "PAN",
            "elements": {
                "type": "text",
                "defaultValue": "",
              "disabled": true // For making the non editable field pass the value as true 
            }
        },
        {
            "name": "nameOnCard",
            "displayText": "Name on card",
            "elements": {
                "type": "text",
                "defaultValue": "",
              "disabled": true // For making the non editable field pass the value as true 
            }
        }
    ]
}

INPUT PARAMETER DETAILS

Call the init() method of the Card91SDKWebView with the below parameter .

Name	Type	Required	Description
templateId	string	true	Use to indicate key for design template
env	string	false	Use "PROD_SANDBOX" for production sandbox environment and "PROD" for production environment .
cardProgramId	string	true	Card program id which come when you login with MPIN/Auth token
organizationId	string	true	Need to pass business id
uniqueId	string	true	Need to pass secret key auth url validation
authUrl	string	true	Auth Url from client need pass in responses attached with token
customFields	object	true	Fields which represent which step have to show

SUBSCRIBE FOR LISTENING CALLBACK EVENTS

Implement Interface Card91ResetAtmPin.Listener for listening to the call back event from the Reset Atm Pin library .

Interface has below and their usage .

 override fun onPageStarted(url: String?) {
        Log.w("Page Started", url.toString()) // When page start to load 
    }

    override fun onPageFinished(url: String?) {
        Log.w("Page onPageFinished", url.toString()) // When page load is finished
    }

    override fun onPageError(errorCode: Int, description: String?, failingUrl: String?) {
        Log.w("Page onPageError", description.toString()) // When page load ends with exception
    }

    override fun onCard91Event(type: String?, payload: String) {
        Log.w("SDK res Type and Payload", type.toString()+"+ payload.toString()) 
              /// Refer the section DIFFERENT CALLBACLK EVENTS for all event type 
              // on successfull card creation payload will have the customer id which has been created
    }

onPageStarted is called when the webpage is loaded.
onPageFinished is called when webpage loading is finished .
onPageError is called when there is any error while loading the page.
onCard91Event is called when issue card is initialised, error occurred, on successful card creation.

DIFFERENT CALLBACLK EVENTS

Call Back Event Type Description

Event Name	Description
C91_ISSUE_CARD_SCREEN_INITIALISED	The issue card screen SDK has been initialised.
C91_ISSUE_CARD_SCREEN_SUCCESS	The API request related to the issue card was successful. That means card holder is created successfully.
C91_ISSUE_CARD_API_FAILURE	The API request related to the issue card has failed. That means card holder is created not created due to api failed. Find the reason on the payload which client will receive in the widget.
C91_ISSUE_CARD_AUTHENTICATION_FAILURE	Authentication for the issue card screen has failed. Thats mean Business Token generated from the AuthURL web-hook does not return the valid token which is passed to issue card API.
C91_ISSUE_CARD_SERVER_FAILURE	The server encountered an error while processing the issue card API request.
C91_ISSUE_CARD_MISSING_PARAMETER	A required parameter is missing in the issue card request. Client application has to make sure validate the params they are passing to SDK should correct and not empty.
C91_ISSUE_CARD_TOKEN_API_SUCCESS	Thats means Business Auth Token from the Auth URL web hook received successfully.
C91_ISSUE_CARD_TOKEN_API_FAILURE	While retrieving the Business Auth Token service has encounter a issue.
C91_ISSUE_CARD_EXTERNAL_SERVER_FAILURE	An external server encountered an error while retrieving the Business Auth Token.
C91_ISSUE_CARD_EXTERNAL_MISSING_PARAMETER	A required parameter is missing in the external issue card request.
C91_ISSUE_CARD_EXTERNAL_AUTHENTICATION_FAILURE	Authentication for the external issue card request has failed.

Card91 Issue Card Android Library

Description

Installation (Gradle and Manifest Configuration)

Android Minimum Requirements :

Android Permission on Manifest:

Update gradle-wrapper.properties

Gradle dependencies

Usage

Add AAR (Android Library Files)

📘Note

ADD CARD91 ISSUE CARD VIEW COMPONENT ON LAYOUT

SETUP CARD VIEW COMPONENT

Issue card submit form

Sample steps JSON for "customFields" param

INPUT PARAMETER DETAILS

SUBSCRIBE FOR LISTENING CALLBACK EVENTS

DIFFERENT CALLBACLK EVENTS

📘
Note