Samsung Pay Integration

Customers can push their debit and credit cards from the Infinity mobile banking application into Samsung Wallet on their Samsung devices in a secure manner to make payments via Samsung Pay using the debit and credit cards.

This section explains the process of integrating the credit or debit cards to Samsung Pay wallet. The following are covered:

Scope

The Issuer APIs are used to add the cards to Samsung Pay wallet for In-app provisioning. These APIs encrypt the card data and generate a unique card ID. The generated unique card ID is saved in the native wallet for secure payment.

Functional Flow

The following diagram depicts the functional flow of integrating credit or debit cards to Samsung Pay wallet.

Technical Flow

The following sequence diagram depicts the technical flow of integrating credit or debit cards to Samsung Pay wallet.

Prerequisites

Following are the prerequisites to integrate credit or debit card to Samsung Pay wallet.

  • Create developer Samsung account.
  • Request membership access in Samsung Pay portal after creating the Samsung account.
  • Download Samsung Pay SDK and sample application.
  • Access to card provisioning APIs from the Card Provider.
  • Banks or Card Issuers must already have the capability where the cards issued by them can be manually added to Samsung Pay. The Infinity banking application provides a mechanism to push the cards into Samsung Pay and then it follows the business as-usual flow that is followed while adding cards manually.

Enable Native Function Interface (NFI) for Samsung Pay

This section explains the procedure to integrate Samsung Pay SDK with Infinity mobile banking.

NOTE:
  • The NFIs and Utility files are provided as part of Retail Banking code base and disabled by default. If wallets functionality is required, the implementation team must generate the build by enabling NFIs and wallet specific dependencies.
  • A customer can choose to remove the NFIs and wallet integration files and only WalletsUtility.js file is required. The methods in WalletsUtility.js file will handle the APIs unavailability.

Creating Library in Android Studio

  1. Go to File > New > New Module >Android library.
  2. Provide Library name, Module name, package name, and minimum SDK.
  3. Click Finish.

Integrating Samsung Pay SDK in Android Studio

  1. Copy SamsungPay.jar (SDK) file in library's libs folder.
  2. Add the following line in the library's build.gradle file in dependency section if not already there.
    implementation fileTree(dir: 'libs', include: ['*.jar'])
  3. Go to File > Sync Project With Gradle files.

Integrating Kony Dependent Libraries for NFI

  1. Copy konywidgets.jar file in library's lib folder.
  2. Add the following line in the library's build.gradle file in dependency section if not already there.
    implementation fileTree(dir: 'libs', include: ['*.jar'])
  3. Go to File > Sync Project With Gradle files.

Generating AAR file and Importing into Visualizer

  1. After all the necessary code for Integrating SDK is ready and all dependency jars are added, build the Android library project to generate the AAR file.
  2. After generating the AAR file, remove konywidgets.jar from the file because konywidgets.jar creates duplicate class error by default as it gets pulled while building in Visualizer.
  3. Add the AAR file to generate NFI and import the same into Visualizer application.
NOTE:
  • For Generating .aar file, create a library project, or else, it will create an application project by default which in turn generates .apk.
  • The gradle file refers to (build.gradle Module :<libraryname>)
  • If any additional functionality needs to be added, add in the Android project, generate AAR file, and then import into Visualizer.

Issuer Host Methods and APIs

This section explains the Samsung Pay supported methods and APIs. The following API methods must be implemented:

void getStatus(final Function callback)

  • Params: JavaScript callback which gets triggered on success or failure.
  • Invokes: It invokes getSamsungPayStatus of Samsung Pay sdk. It returns whether device supports Samsung Pay, Samsung Pay app installed or not.
  • onSuccess: It sends status and bundle and message in form of JSON object to JavaScript layer. Status and bundle are from Samsung Pay SDK and we add message which could be SPAY_NOT_SUPPORTED, SPAY_NOT_READY, SPAY_READY, UnExpected.
  • onFail: It sends errorCode and bundle and message in form of JSON object to JavaScript layer. Error code and bundle are from Samsung Pay SDK. The Message will be Fail.

  • SDK method URL: https://d3sfvyfh4b9elq.cloudfront.net/ptr/guide/techguide/v1.4/guide/03_03_01_checking_samsung_pay_status.html. Refer the URL for status, bundle used in OnSuccess and errorCode, and bundle used in onFail.

void getAllCards(final Function callback)

  • Params: JavaScript callback which gets triggered on success or failure.
  • Invokes: It invokes getAllCards of Samsung Pay SDK. It returns all the registered cards from Samsung Pay Wallet.
  • onSuccess: It sends message as success and data which holds all registered cards in form of JSON object to JavaScript layer.
  • onFail: It sends message as error in form of JSON object to JavaScript layer.
  • SDK method URL: https://d3sfvyfh4b9elq.cloudfront.net/ptr/guide/techguide/v1.4/guide/03_03_08_requesting_list_registered.html

void addCard(JSONObject obj, final Function callback)

  • Params
    • JSON object obj holds cardType, tokenizationProvider, and payload provided by provider.
    • JavaScript callback which gets triggered on success or failure.
  • Invokes: It invokes addCard method of Samsung Pay SDK. It adds the card into Samsung Pay Wallet if no issues.
  • onSuccess: It sends message, status, and card. Status and card are from Samsung Pay SDK. Message will be success.
  • onFail: It sends message, error, and errorData. Error and errorData are from Samsung Pay SDK. Message will be error.
  • SDK method URL: https://d3sfvyfh4b9elq.cloudfront.net/ptr/guide/techguide/v1.4/guide/03_03_10_adding_card.html. Refer the URL for status, card used in OnSuccess and error, and errorCode used in onFail.

Steps for Registering SPay with Samsung

  1. Register the application and create a service in Samsung Pay developer portal. After creating the service, service ID and app debug key are received.
  2. Add the app debug key and API level(2.5) in Android manifest in Visualizer project settings.
    Path: Visualizer Settings > Native > Android Mobile/Tablet > Tags

Add the following in child tag entries under <application> tags in path provided above.
Debug mode

<meta-data
android:name="debug_mode"
android:value="Y" />
<meta-data
android:name="spay_debug_api_key"
android:value="apikeypovidedinportal " />
<meta-data
android:name="spay_sdk_api_level"
android:value="2.5" />

Release mode 

<meta-data
android:name="debug_mode"
android:value="N" />
<meta-data
android:name="spay_sdk_api_level"
android:value="2.5" />

Common Wallets Utility File and APIs

This section explains the common utility files and APIs.

NOTE: If a customer chooses to remove the NFIs, the methods in WalletsUtility.js file handles the APIs unavailability.

The WalletsUtility.js file is a common utility file that communicates between the integration layer and Retail Banking code. The utility file has the following methods:

API to check whether wallets are supported in specific device

isSamsungPaySupported(callback) - Returns Callback with true or false based on the support. Currently returns false for even SPAY supported devices as Samsung Membership ID is not available to access the APIs in Retail Banking code base

API to check whether card is already added to wallet

isCardAlreadyAdded_Spay(cardIdentifier,callback) - Method to check if card is already added to the wallet or not.

API to add cards to wallet

addCardtoSPayWallet(cardsData,succCallback,errCallback) - API to add card to Spay wallet.

NOTE: CardsData in params is tokenized cardData which differs from wallet to wallet. In-app provisioning data obtained from issuer APIs (VISA) is used in Retail Banking code base.

API for Creating Tokenized Data for Wallets (VISA)

Visa In-App Provisioning currently supports Universal Card Enrollment and In-App Provisioning for Apple Pay, Google Pay, or Samsung Pay.

Universal Card Enrollment API enables Visa clients to digitally register accounts with Visa in real time. Once registered, client developers receive back a universal card identifier, that can be used inter-operably for accessing certain other Visa services like Visa In-App Provisioning without directly having to handle sensitive PAN data or without having to re-register and maintain card data repetitively across multiple Visa products in the future.

In-App Provisioning API enables clients to request encrypted card data using the universal card identifier from Universal Card Enrollment API. Clients can pass this encrypted card data payload to Samsung Pay wallet for tokenization. This token then becomes active on the Pay Wallet and is pushed to the consumer's device.

The following APIs are used in the Retail Banking application for Samsung Pay:

API Description API Reference
enrollCardForVisa Create a card object (if it doesn’t exist) and link it to an existing customer record. Reference Link
createCardDataForSamsungPay Generate encrypted card data to perform in-app token provisioning for Samsung Pay. This is an orchestration service. Reference Link

enrollCardForVisa

{{URL}}/services/data/v1/RBObjects/operations/Cards/enrollCardForVisa

Sample Request

{ 

    "paymentService": "applePay", 
    "cardID": "115", 
    "nameOnCard": "Digital Issuance",
    "cvv2": "123", 
    "billingAddress": "[{'name': 'Digital Issuance',
'line1': '12301 Research Boulevard',
'line2': 'Research Boulevard',
'line3': 'Visa USA','city': 'Austin',
'state': 'TX','countryCode': 'US','postalCode': '78759'}]" 

}

Sample Response

{ 

    "vCardID": "v-123-ba75fedc-cd55-40ef-8187-77fabab34501", 
    "paymentAccountReference": "V1234567890124514236833852412", 
    "last4": "2412", 
    "expiryMonth": "01", 
    "expiryYear": "2021", 
    "opstatus": 0, 
    "httpStatusCode": 0 


}

createCardDataForSamsungPay

Orchestration service created for createCardData.

{{URL}}/services/data/v1/RBObjects/operations/Cards/createCardDataForSamsungPay

Sample Request

{
"paymentAccountReference" : "V0010014619294087332641009370",
"deviceID" : "uztEQocBRFrbK5hCgcDbxqw_",
"clientCustomerID" : "ae25OGhjZTk2dsr452dgsr51",
"paymentService": "samsungPay",
"cardID": "4514234413926268",
"nameOnCard": "Digital Issuance",
"cvv2": "123",
"expiryMonth": "01",
"expiryYear": "2021",
"billingAddress": "[{'name': 'Digital Issuance','line1': '12301 Research Boulevard','line2': 'Research Boulevard','line3': 'Visa USA','city': 'Austin','state': 'TX','countryCode': 'US','postalCode': '78759'}]"
}

Sample Response

{
			"vCardID": "v-123-ecf4ead1-1913-40d6-bf53-dd23a3b6ab02",
			"paymentAccountReference": "V0010014619294087332641009370",
			"opaquePaymentCard": "eyJhdWQiOiIxODk5NzZhNi0yZmFjLTRlZDEtOTM0ZS03MjY5NmVhMDgxMzEiLCJraWQiOiJYS1ZYNUlHNTVDWTFRM0FVR0JLQTExbV9VNGR2b2FROVVzZ3lESUxqQjNUempCYmU4IiwiaXNzIjoiYmJlZWUwMzgtNDgzMS00MjUzLWE3MjItMHY3NWNsMTNuNzFkIiwidHlwIjoiSk9TRSIsImNoYW5uZWxTZWN1cml0eUNvbnRleHQiOiJTSEFSRURfU0VDUkVUIiwiZW5jIjoiQTI1NkdDTSIsInRhZyI6Il9MVU40bkpuZE1CQjROSGo2Rng1cEEiLCJpYXQiOjE2MTYwNzIxMzYsImFsZyI6IkEyNTZHQ01LVyIsIml2IjoiVlFtMEp1RmRKUlhtaHhVVSJ9.MBl9o0sgghy2z6niR4wE59AeCUAYAfXpS9Tq7pFO7jE.UOpZE1LBQRGYRpjp.TYjZEQVHKZM1p8bfhzPoOjUtfB6GS_b5D69E8ggTH-xageomswJRyf3vEC31qOf8rEjwpgejCC0VqIPAq8Q_8DjRgM4dZQ3F0LaYAr-OqFNY8fnHXrpHkDD04QcDn1BMgupclYttJ6nPyuPrr5W4Tzt4KUOmiXoGvFgnUD-lo7AoBqwHos1LQE6A1bN4gDtR9b135VjGlidv8ynkKY_BlhU--Fk7cy7sFhHbW16cYLi2YUOzGEqljREu_t5bWL_ge-acA8YidyCQwpO_ETzxaTZr4cxp7K3IIf-pR2ZypK1om_WxQDfh4uqYkDyTGzvVgD76eZl_O8QTSKEdtWC5CM_U40njedv6jmZYhkev0TD3YNbBocLsYa2OzR5onlQ7FwYVd2A-5BlJQ7C4-Rvn4LdedIEZAi9UKojt-xjw5Jl06hUtn6Yuwgr2GFa5T08BWGl3EYzdOUDFF_SCHoQ41S9j9e9k0t27P5TAq1vn_2hHNugtQrRMF5hnfzcH4jmAnWtFtBpJJSRm2gFM9JBWfedu90XrabdPQS5V5LPqrk6aq_wBVXqPVz_mMsjo9NFscpDEhDyRYDiMkOq6Gm10z9S6sLv_CJ-0MCK6SP1LlLX0WoGejTbG_gzxISmrUEoPt2BbqyPlJ40TWYeVIt1M8MLQM0hFiDLmPTN_yw.rkia3K0TOSgDtFummWWo7Q",
			"last4": "6268",
			"expiryMonth": "01",
			"expiryYear": "2021",
			"cardType": "CREDIT",
			"opstatus": 0,
			"httpStatusCode": 0
		}

Limitations

  • VISA Sandbox environment is used for card provisioning that has certain limitations. To test the flow end-to-end, it is a must to get a license for VISA Certification environment and go through the certification process. The process is the same for any other Card Provider.
  • The end-to-end feature is not available in the demonstration system as we were not able to get access to the Samsung Pay membership.

 

Expand/Collapse
Share
Print

In this topic

Copyright © 2020- Temenos Headquarters SA

Published on :
Monday, May 2, 2022 5:52:14 PM IST

Feedback
x