Jio Platforms Limited

Jio Platforms Limited

JioPay Service for Set Top Box (STB) Apps Developer Guide

Rev. No. 1.1 Rev. Date: 02-09-2020

Document Classification: Confidential

Jio Platforms Limited Rev. date 02-09-2020 Rev. 1.1 of 19

JioPay Service for STB Apps_ Developer Guide

Copyright Information This Document published in electronic or hardcopy form is property of Jio Platforms Limited. No part of this document may be copied, reproduced, stored in any retrieval system, or transmitted in any form or by any means, either electronically, mechanically, or otherwise without prior written permission. JPL shall at all times remain the sole owner of the copyright in the Technical Documents.

Jio Platforms Limited, 2020

ALL RIGHTS RESERVED

TRADEMARKS

All the brand names and other products or services mentioned in this Technical document are identified by the trademarks or service marks of JPL and wherever applicable, other third parties. You are not permitted to use or reproduce these marks except as part of the unaltered Technical Documents without the prior written consent of the JPL or where applicable the third party owner.

DISCLAIMER

The Technical Documents are provided on an ‘as is’ basis without guarantees, representations, conditions or warranties as to their accuracy or completeness or that they are free from error. The information in this document is subject to change without notice and should not be construed as commitment by Jio Platforms Limited.

It is possible that use of the technical matter published in this Document may require the permission of the proprietor of one or more patents. You are entirely response for identifying and where necessary obtaining a licence under such patents should you choose to use any such technical matter. JPL has no responsibility in this regard and shall not be liable for any loss or damage suffered in relation to an infringement of any third party patent as a result of such use.

Terms of Use

You are permitted to download, use and distribute copies of JPL Technical Documents made available in electronic or physical form, except that:

a) you must only use and distribute the Technical Requirement Documents in their entirety without amendment, deletion or addition of any legal notice, text, graphics or other content; and

b) You are not permitted to make any of the Technical Documents available for download on any publically accessible bulletin board, website, ftp site or file sharing service.



Table of Contents

1 Introduction ........................................................................................................................................ 4

1.1 Scope ..................................................................................................................................................... 4

1.2 Intended Audience ................................................................................................................................. 4

1.3 Abbreviations ........................................................................................................................................ 4

2 Classes and Methods ........................................................................................................................... 5

2.1 OrderTransactionHelper ........................................................................................................................ 5

2.2 OrderInfoBuilder .................................................................................................................................... 5

2.3 OrderInfo ............................................................................................................................................... 6

2.4 JiopayActivity ........................................................................................................................................ 6

2.5 Environments ........................................................................................................................................ 6

2.6 JiopayResponseCodes ............................................................................................................................ 6

2.7 TransactionResponse ............................................................................................................................ 7

2.8 OrderConfirmationResponse ................................................................................................................. 8

2.9 IJiopayOrderConfirmation ..................................................................................................................... 8

2.10 TransactionHistory ................................................................................................................................ 8

2.11 IJiopayTransactionHistory ..................................................................................................................... 9

3 JioPay SDK Integration Guidelines ...................................................................................................... 10

3.1 Integration Steps ................................................................................................................................. 10

3.2 Order Confirmation ............................................................................................................................. 12

3.3 Get All Transactions ............................................................................................................................ 12

4 Server to Server APIs.......................................................................................................................... 13

4.1 SUCCESS Callback to Developer ........................................................................................................... 13 4.1.1 Request ........................................................................................................................................... 13 4.1.2 Response ......................................................................................................................................... 14

4.2 Purchase ACK from Third Party ........................................................................................................... 14 4.2.1 Request ........................................................................................................................................... 14 4.2.2 Response ......................................................................................................................................... 15

4.3 TXN Status ........................................................................................................................................... 15 4.3.1 Request ........................................................................................................................................... 15 4.3.2 Response ......................................................................................................................................... 16

5 Checksum Generation Guidelines ....................................................................................................... 18

5.1 Code Snippet ....................................................................................................................................... 18

5.2 Order Confirmation from 3rd Party Server ........................................................................................... 18

5.3 Transaction Status S2S Call to 3rd Party Server ................................................................................... 18

5.4 Get Transaction Status from 3rd Party Server ...................................................................................... 19



1 Introduction 1.1 Scope JioPay Service Software Development Kit (SDK) is for Developers to collect payment from the Applications on Jio Set Top Box (STB). Developer needs to be onboarded and get their App fingerprint whitelisted. Only upon whitelisting, the app can call JioPay SDK. User can use MyJio app to scan the displayed QR code. Once user makes the payment, SDK will return the result of transaction to developer. This document covers the following: • API Specification for JioPay SDK • Guidelines for JioPay SDK integration for payment collection • Guidelines for Checksum generation

1.2 Intended Audience This document is intended for Developers who want to enable JioPay services for their Applications available on the Jio STB.

1.3 Abbreviations Term Description

API Application programming Interface

STB Set To Box

3PL Developers Developers of 3rd Party application

Developers Developers of 3rd Party application

PG Payment Gateway

S2S Server to Server

SDK Software Developmenet Kit



2 Classes and Methods 2.1 OrderTransactionHelper object OrderTransactionHelper

This class is used to start the SDK, stop the SDK, call various non UI APIs like OrderConfirmation and TransactionHistory.

Public Methods Description

TransactionHistory getTransactions(context:Context, packageName:String, listener: IJiopayTransactionHistory)

This method returns all the transactions done for current subscription id.

OrderConfirmationResponse doOrderConfirmation(context: Context, orderId: String, purchaseAck: String, listener: IJiopayOrderConfirmation)

This method is used to confirm that order has been successfully delivered.

2.2 OrderInfoBuilder class OrderInfoBuilder

This is a Builder class that helps the user to build the OrderInfo which acts as an input to the JioPay Service.

Usage:

OrderInfoBuilder.build() returns OrderInfo

Public Methods Description

void setOrderId (orderID String)

This function initializes the orderID for the payment.

void setSkuId(skuId String) This function initializes the skuID for the payment.

void setStartDate(date String)

This function initializes the startDate for the payment for SUBSCRIPTION products. For other types, it can be null. It is in milli seconds.

OrderInfo build()

This function initializes the OrderInfo object for payment.



2.3 OrderInfo data class OrderInfo

This is the class that represents the OrderInfo input for making a payment.

Public Members Description

String orderId This member variable holds the order id for the transaction.

String skuId

This member variable holds the sku id for the transaction.

String startDate

Start Date for payment for SUBSCRIPTION Products. For other types, it can be null. It is in milli seconds.

2.4 JiopayActivity class JiopayActivity: Activity This Activity is used to invoke JioPay Service for initiating a payment. It takes input of OrderInfo(Mandatory) and Environment(Optional, By default is SIT). Please refer the section JioPay SDK Integration Guidelines to view the sample.

2.5 Environments Enum class Environments

This class contains various Environments supported by the SDK.

Public Members

Type Member

Environments TEST

Environments PROD

2.6 JiopayResponseCodes object JiopayResponseCodes This class contains various Constants for holding result and request codes.



Public Members

Type Member

int REQUEST_PAY

int RESULT_SUCCESS

int RESULT_FAILURE

int RESULT_CANCELLED

int RESULT_TIMEDOUT

String TXN_STATUS

String RESP_MESSAGE

2.7 TransactionResponse data class TransactionResponse

This is the class that holds the result of a payment. You can refer to below fields for accessing various information about the payment:


int code The value of this variable is 200 for success.

String message In case the payment fails, this variable can hold a message depicting the reason.

String status Status of transaction as SUCCESS or FAILED.

String orderId Developer side order for which payment is made.

String txnId PG side transaction id.

Double amount Amount of transaction.

String timestamp

Timestamp at which transaction happened in millisecond.

String startDate Start Date of the purchase at which transaction occurred.

String endDate End Date calculated based on the product validity.

String skuId SKUID for which payment was successful.

String currency Currency of the transaction.

String responseSignature Signature to verify signed response.



2.8 OrderConfirmationResponse class OrderConfirmationResponse

This is the class that holds the result of an order Confirmation. You can refer to below fields for accessing various information about the response:


int code The value of this variable is 0 for success and non zero otherwise.

String message In case the payment fails, this variable can hold a message depicting the reason.

String status Status of transaction as SUCCESS or FAILED.

2.9 IJiopayOrderConfirmation interface IJiopayOrderConfirmation

This is the interface contains callback in which the result of order confirmation comes inside onOrderConfirmation() method:


Void onOrderConfirmation(orderConfirmation: OrderConfirmationResponse)

The callback in which the result of order confirmation comes.

2.10 TransactionHistory class TransactionHistory

This is the class that holds the result of transaction history API. You can refer to below fields for accessing various information about the response:


String txnId Id of the transaction.

String orderId Id of the order.

String status Status of transaction as SUCCESS, FAILED or PENDING.



2.11 IJiopayTransactionHistory interface IjiopayTransactionHistory

This is the interface that returns the TransactionHistory response in onTransactionHistory method:


Void onTransactionHistory(transactionHistory: TransactionHistory)

Result of transaction history comes in this callback.



3 JioPay SDK Integration Guidelines 3.1 Integration Steps Follow these steps for JioPay SDK integration:

1) Copy in_app_payment_client_sdk.aar to libs folder located inside <Project Directory>\app\libs.

2) Go to Project level build.gradle file and add flatDir to repositories of allprojects as shown below:

allprojects { repositories { google() jcenter() flatDir { dirs 'libs' } } }

3) Now go to module level build.gradle and add following dependencies to build.gradle file. These dependencies are needed by sdk and are not coupled inside the aar file. Hence hosting application must include them. Please check for duplication as some might already be there. Duplication will break build.

implementation fileTree(dir: 'libs', include: ['*.jar']) implementation 'androidx.appcompat:appcompat:1.1.0' implementation 'androidx.constraintlayout:constraintlayout:1.1.3' implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version" implementation 'androidx.core:core-ktx:1.2.0' implementation (name: in_app_payment_client_sdk', ext:'aar' )

4) You are ready to launch SDK now. Clean build the project. 5) To launch SDK, you need to provide following inputs in a class named OrderInfo with the

help of OrderInfoBuilder. All details should be converted to String to be provided for SDK. Mandatory details that are required as below: skuId: ID of product orderId: 3rd party order id

6) Sample code to start the SDK is as given below:

val orderInfo = OrderInfoBuilder() .setSkuId("sku12345") .setOrderId("ORDERN007020")



.setStartDate(“123456789”) .build() val intent = Intent(this@MainActivity, JiopayActivity::class.java) intent.putExtra(ORDER_INFO, orderInfo) intent. putExtra (ENVIRONMENT, Environments.TEST.name) startActivityForResult(intent, JiopayResponseCodes.REQUEST_PAY)

7) You should listen to results as shown below:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) val resultOfPayment = data?.extras?.getParcelable<TransactionResponse>(JiopayResponseCodes.TXN_STATUS) val message = data?extras?.getString(JiopayResponseCodes.RESP_MESSAGE) Log.i("PGSDK", "resultOfPayment = " + resultOfPayment) when (requestCode) { JiopayResponseCodes.REQUEST_PAY -> { when (resultCode) { JiopayResponseCodes.RESULT_SUCCESS -> { Toast.makeText( this, "" + "Payment Success : " + resultOfPayment?.status, Toast.LENGTH_SHORT ).show() } JiopayResponseCodes.RESULT_FAILIUR -> { Log.i("PGSDK", "Something went wrong on sdk") Toast.makeText( this, "" + "Payment Failed : " + "${resultOfPayment?.status ?: “”} \n ${message ?: ""}", Toast.LENGTH_SHORT).show() } JiopayResponseCodes.RESULT_CANCELLED -> { Toast.makeText(this, "" + "Cancelled", Toast.LENGTH_SHORT).show() } JiopayResponseCodes.RESULT_TIMEDOUT -> { Toast.makeText(this, resultOfPayment?.status, Toast.LENGTH_SHORT).show() } else -> { Toast.makeText( this, "" + "Something wrong happened. Please contact admin", Toast.LENGTH_SHORT ).show() } }



} else -> { Toast.makeText(this, "Something went wrong.", Toast.LENGTH_LONG).show() } } }

8) TransactionResponse is the Model you receive as output. It can be null if transaction is

cancelled by pressing back button. If it comes, data present in TransactionStatusResponse can be explained in the file description above.

9) Upon receiving the result, client can close the order and display order confirmation.

3.2 Order Confirmation Once you are done with the transaction, you will get the txnId in response with which we have to do purchase acknowledgement once the product or service is delievered.

• For the API call, use below code:

OrderTransactionHelper.doOrderConfirmation( context, txnId, SUCCESS, listener )

• Here, the mandatory parameters are context, txnId and purchase acknowledgement. • txnId is transaction Id of the transaction for which you have delivered the product or service. • Purchase acknowledgement is the delivery status, it may be SUCCESS / FAILED. Success

denotes that product or service has been successfully delivered. Failed denotes otherwise. If FAILED, Money will be refunded to user. If you do not confirm SUCCESS in a designated time, money will be automatically refunded.

• This API will do the order confirmation for the transaction and gives the response like as OrderConfirmationResponse.

3.3 Get All Transactions • For getting all the transactions made for current subscription id and given package name,

you can add the following snippet: OrderTransactionHelper.getTransactions(context, packageName, listener)

• This will return you json String which contains all the transactions and the response as

TransactionHistroy object.



4 Server to Server APIs 4.1 SUCCESS Callback to Developer This API will send the transaction notification to developer. This is used to confirm that the product or service transaction is successful.

4.1.1 Request

Endpoint The API endpoint would be developer’s server URL shared during the application onboarding.

Sample Request

( “txnId”:"JIOJP1234567",

“transactionStatus”:"SUCCESS",

“timeStamp”:" 2020-04-16’T’ 12:16:26",

“amount”:”199”,

“skuId”:”510”,

“orderId”:"307qe9r",

“startDate”: “2020-08-16 12:16:26.695”,

“endDate”:” 2020-12-16 12:16:26.695”,

“checkSum”:"adirn86w9xye9ay9",

“currency”:”INR”,

“code”:”200”,

“message”:”SUCCESS” )

Parameter Type Mandatory (M) / Optional (O)

Description

txnID String M Transaction ID of the transaction done.

transactionStatus String M This is the status of the delivery of product or service. (SUCCESS/ FAILED)

Timestamp String M Transaction timestamp.

orderId String M Order ID used for transaction.

Checksum String M Checksum generated based on payload and other keys.




Description

Amount String M Amount of the transaction.

skuId String M Sku id used for the transaction.

startDate String M Date when the transaction was performed.

endDate String M End date of the subscription.

Code String M Status code.

Message String M Status message.

Currency String M Currency used for the transaction.

4.1.2 Response Response parametres are sent as json String.

Sample Response

{

"code": 0,

"message": "Payment Successful",

"status": "TXN_SUCCESS"

}


Description

status String M It is mandatory param. It can be SUCCESS or FAILURE.

message String O If any failure occurs, it can be referred to understand the reason of failure.

code Integer M 0 for success and non-zero otherwise.

4.2 Purchase ACK from Third Party This API is called by the developer for sending purchase acknowledgement.

4.2.1 Request

Endpoint https://<environment-url>/cr/v1/jiopay/stbservice/puchase/ack



Sample Request

( “checksum”:"efh34gkk4tll23 ",

“orderId”:"adoafyf1342 ",

“purchaseAck”:”SUCCESS” )


Description

orderId String M Order ID of the transaction.

checksum String M Checksum generated.

purchaseAck String M SUCCESS / FAILURE.

4.2.2 Response Response parameters are sent as json String.

Sample Response

{

"code": 0,

"message": "Purchase Ack Successful",

"status": "SUCCESS"

}


Description

status String M It is mandatory param. It can be SUCCESS or FAILURE.

message String O If any failure occurs, it can be referred to understand the reason of failure.

code Integer M 0 for success and non-zero otherwise.

4.3 TXN Status This API is called by the developer for getting the transaction status.

4.3.1 Request

Endpoint https://api-sit.jio.com/cr/v1/jiopay/stbservice/txn/get

https://api-sit.jio.com/cr/v1/jiopay/stbservice/txn/get



Sample Request

(

“orderId”:"adoafyf1342 "

“packageName”:”com.sample.android”,

“checksum”:”cf4t4gegwef” )


Description

orderId String M Order ID of the transaction

packageName String M App package name of the transaction

checksum String M Checksum generated using the payload and clientId

4.3.2 Response Response params are sent as json String.

Sample Response

( “txnId”:"JIOJP1234567",

“transactionStatus”:"SUCCESS",

“timeStamp”:" 2020-04-16 12:16:26.695",

“amount”:”199”,

“skuId”:”510”,

“orderId”:"307qe9r",

“startDate”: “2020-08-16 12:16:26.695”,

“endDate”:” 2020-12-16 12:16:26.695”,

“checkSum”:"adirn86w9xye9ay9",

“currency”:”INR”,

“code”:”200”,

“message”:”SUCCESS” )


Description

txnID String M Transaction ID of the transaction done.

transactionStatus String M This is the status of the delivery of product or service. (SUCCESS/ FAILED)




Description

timestamp String M Transaction timestamp.

orderId String M Order ID used for transaction.

checksum String M Checksum generated based on payload and other keys.

amount String M Amount of the transaction.

skuId String M SKU id used for the transaction.

startDate String M Date when the transaction was performed.

endDate String M End date of the subscription.

code String M Status code.

message String M Status message.

currency String M Currency used for transaction.



5 Checksum Generation Guidelines 5.1 Code Snippet The algorithm used to generate checksum is HMACSHA256. Below is the code snippet used to generate checksum in Java:

Code Snippet

String key = "the shared secret key here";

String message = "the message to hash here";

Mac hasher = Mac.getInstance("HmacSHA256");

hasher.init(new SecretKeySpec(key.getBytes(), "HmacSHA256"));

byte[] hash = hasher.doFinal(message.getBytes());

// to lowercase hexits

DatatypeConverter.printHexBinary(hash);

For other platoform, refer

https://gist.github.com/jasny/2200f68f8109b22e61863466374a5c1d

5.2 Order Confirmation from 3rd Party Server To generate checksum for purchase acknowledgment, we can use the below function:

CheckSumService.getCheckSumService(). generatePayloadCheckSum(param1, param2);

Param1 format: “orderId|purchaseAck”

Param2 is the clientId.

5.3 Transaction Status S2S Call to 3rd Party Server To generate checksum for transaction acknowledgment, we can use the below function:


Param1 format: “txnId|transactionStatus|code|message|amount|timestamp|startDate|endDate|skuId|checksum|currency”


https://gist.github.com/jasny/2200f68f8109b22e61863466374a5c1d

Jio Platforms Limited

Documents

Transcript of Jio Platforms Limited