PayUBolt SDK Integration

PayUBolt SDK will provide a way to integrate in-app UPI payment in merchant app with their own UI. They can manage the checkout options on their checkout screen. Features included in this SDK are:

• Registration - This SDK provides APIs for device binding and registration. Merchant App can consume these APIs and build their own registration journey.
• Payment - This SDK provides payment and verify transaction APIs. Merchant App can consume these APIs to build payment journey as well.
• Management - This SDK provides account management APIs. Merchant App can check balance, set/change pin and add/delete account in their own user journeys.

This integration involves the following steps:

1. Add permissions to Manifest file
2. Include Bolt SDK and AAR Files
3. Initialize the SDK

Later, you can integrate the following flows:

• Integrate Registration Flow
• Integrate Repeat Flow
• Integrate Payment Flow
• Integrate Management flow

For hash generation logic and Listener/Callback integration, the Hash generation logic and o Listener or Callback logic sub-sections.

Prerequisites

• Minimum Android SDK Version - 23 and above.
• Compile SDK Version - 31 and above.
• The following .aar (Android archive) files provided by PayU during onboarding:
  1. NPCI Secure Component
  2. AXIS Olive

Step 1: Add permissions to Manifest file

Update the manifest file to include the following so that permissions are provided for SDK:

// To send SMS for device binding
<uses-permission android:name="android.permission.SEND_SMS"/>
// To check current network state
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
// To access internet for API calls 
<uses-permission android:name="android.permission.INTERNET" />
// To get sim details from devices below or equal to 29
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
// Too get sim details from devices above 29
<uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
// To provide location details for transaction
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Step 2: Include Bolt SDK and AAR Files

To include the PayU UPI Bolt SDK in your project, add the following code snippet to your app’s build.gradle.

implementation 'in.payu:payu-upi-bolt-axis-wrapper-sdk:1.0.0' // PayU AXIS Wrapper
implementation 'in.payu:payu-upi-bolt-sdk:1.0.0' // PayU Bolt SDK

Add the .aar files provided by PayU during onboarding. in the libs directory of your android module and add these in module level build.gradle. For the list of files, refer to Prerequisites.

api(files("$projectDir/libs/SecureComponent-release-prod_05062024_9d3904ab.aar")) // NPCI .aar
api(files("$projectDir/libs/oliveupi-payu-release_PROD_02-12-2024_2.0.2.aar")) // AXIS .aar 

The screenshot of libs directory is similar to the following:

Step 3: Initialize the SDK

It is used to initialize the SDK. This method returns a object that will be used to access other methods available in PayUUPIBoltUI.

val bolt = PayUUPIBolt.getInstance(
    activity: AppCompatActivity,
    config: PayUUPIBoltConfig,
    hashGenerationListener: PayUHashGenerationListener
)

The following fields are needed as a request for this API:

The PayUUPIBoltConfig includes the following fields:

Response

📘

Callback: After the SDK is initialised, use the same object to call the sdk methods.

De-initialise PayUBolt SDK

reset: This method is used to deinitailise the bolt object. 

`PayUUPIBolt.reset()`

Listener or Callback logic

Listerner/Callback contains 3 methods where the merchant app will get the API response and hash-related callbacks

PayUUPIResponse

Note: If result object is null or empty. Kindly use the response from message

Response type

Response codes

Hash Generation logic

The PayU SDKs use hashes to ensure the security of the transaction and prevent any unauthorized intrusion or modification.

For generating and passing dynamic hashes, the merchant will receive a call from the generateHash() method of PayUUPIBoltUiListener. The generateHash() method is called by the SDK each time it needs an individual hash.

fun generateHash(map: HashMap<String, String>, hashGenerationListener: PayUHashGeneratedListener): Merchant will get map with type of hash and hash string as value of map.
  
  They have to sign that string using salt to create hash value and pass that to hashGenerationListener.onHashGenerated().
      In the map you have to check for three keys to generate hash.
      1. hashString
      2. hashName
      3. postSalt
  At the end of that hashString append your salt and use SHA-512 algo on that final string to generate hash.
  Note: If you got postSalt also in the map, first use hash string append salt and then append postSalt value to that string and use SHA-512 algo on that final string to generate hash.
  Once the hash is generated use hashGenerationListener parameter to pass the hash to SDK. Example code:
         val hashMap: HashMap<String, String> = HashMap()
         hashMap[hashName] = hash //hashName is the value you got in map and hash is the hash value.
         hashGenerationListener.onHashGenerated(hashMap)     

Integrate Registration Flow

The following methods are used to integrate registration flow:

• Check if UPI Bolt is enabled
• Get registered mobile number
• Get subscriber info
• Check device status
• Initiate SDK
• Fetch bank list
• Fetch accounts of a selected bank
• Set VPA
• Set PIN

Check if UPI Bolt is enabled

Use the isUpiBoltEnabled method to check whether the UPI bolt is enabled for the merchant or not enabled.

bolt.core.isUpiBoltEnabled(callback: PayUUPIBoltCallBack)

The following parameters are needed as a request for this API:

Response: Response type : REQUEST_UPI_BOLT. For more information, refer to Response type.

Get registered mobile number

Use the getRegisteredMobile method to get already registered mobile number.

 bolt.core.getRegisteredMobile(): String

The following parameters are needed as a request for this API:

Get subscriber info

Use the getSubscriberInfo method to get SIM info from device.

bolt.core.getSubscriberInfo(mobile: String, callback: PayUUPIBoltCallBack)

📘

Callback reference:

For callback logic refer to Listener or Callback logic sub-section.

The following parameters are needed as a request for this API:

The response is PayUSimInfo array list that contains the following fields:

Check device status

Use the checkDeviceStatus method to check the device binding status.

bolt.core.checkDeviceStatus(mobile: String, subscriptionId: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is CHECK_DEVICE_STATUS.

Initiate SDK

Use the initiateSDK method to start device binding and triggering SMS.

bolt.core.initiateSDK(subscriptionId: String, phone: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_SDK_HANDSHAKE

Fetch bank list

Use the fetchBankList method to fetch a list of all banks.

bolt.core.fetchBankList(callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_LIST_BANKS

The response is PayUBankData array list that contains the following fields:

Fetch accounts of a selected bank

Use the fetchAccountsWithIin method to fetch accounts of selected bank.

bolt.core.fetchAccountsWithIin(iin: String, bankName: String, bankCode: String?, vpa: String?, requestType: String?, isCCTxnEnabled: Boolean, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

</td>

<td>
`String`Issuer identification number of bank
</td>
</tr>

<tr>
<td>
bankname ```

mandatory

</td>

<td>
`String`UPI handle
</td>
</tr>

<tr>
<td>
requestType```

optional

</td>

<td>
`String`The default value is false. Set it true if bank is CC.
</td>
</tr>

<tr>
<td>
callback ```

mandatory

Response: Response type is REQUEST_FETCH_ACCOUNT_V3

The response is PayUCustomerBankAccounts array list that contains the following fields:

Set VPA

Use the setVpa method to update the vpa of the registered account.

bolt.core.setVpa(accountDetail: PayUAccountDetail, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_SAVE_VPA_V3

Set PIN

Use the setPin method to set PIN for new account..

bolt.core.setPin(accountDetail: PayUAccountDetail, cardNo: String, exp: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_ACCOUNT_MOBILE_REG

Integrate Repeat Flow

Fetch linked accounts

Use the fetchLinkedAccounts method to fetch registered account with the device.

bolt.core.fetchLinkedAccounts(callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_ALL_ACCOUNTS_V3

The response is PayUCustomerBankAccounts array list that contains the following fields:

Integrate Payment Flow

The following methods can be used to integrate payment flow:

• Initiate payment
• Check transaction status
• Cancel transaction

Initiate payment

Use the pay method to initiate payment..

bolt.core.pay(paymentParams: PayUUPIBoltPaymentParams, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

paymentParams field description

</td>

<td>
`String` User defined field
</td>

<td>

</td>
</tr>

<tr>
<td>
udf3```

optional

</td>

<td>
`String` User defined field
</td>

<td>

</td>
</tr>

<tr>
<td>
udf5```

optional

Response: Response type is REQUEST_PAY

Check transaction status

Use the checkTransactionStatus method to check the transaction status.

bolt.core.checkTransactionStatus(txnId: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_CHECK_PAYMENT_STATUS

Cancel transaction

Use the cancelTransaction method to cancel the current transaction.

bolt.core.cancelTransaction(callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_CANCEL_TRANSACTION

Integrate Management flow

The following methods can be used to integrate management flow:

• Fetch transaction history
• Check balance
• Remove account
• Change mPIN
• Fetch VPA profile
• Save VPA
• Delete VPA
• Raise query or dispute
• Fetch query list
• Deregister
• Check required permissions
• Check clear cache
• Clear data

Fetch transaction history

Use the fetchTransactionHistory method to fetch the transaction history.

bolt.core.fetchTransactionHistory(fromDate: String, toDate: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_TRANSACTION_HISTORY_V3

The response is PayUTransactionHistory array list.

Check balance

Use the checkBalance method to check registered account balance.

bolt.core.checkBalance(accountDetail: PayUAccountDetail, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_BALANCE

Remove account

Use the removeAccount method to remove registered account from your device.

bolt.core.removeAccount(accountDetail: PayUAccountDetail, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_ACCOUNT_REMOVE_V3

Change mPIN

Use the changeMpin method to change the mobile PIN of the registered account.

bolt.core.changeMpin(accountDetail: PayUAccountDetail, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_CHANGE_MPIN

Fetch VPA profile

Use the fetchVpaProfile method to fetch the VPA profile.

bolt.core.fetchVpaProfile(vpa: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_PROFilE_VPA_V3

Save VPA

Use the saveVpa method to save a VPA profile.

bolt.core.saveVpa(vpa: String, name: String, nickName: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_SAVE_VPA_V3

Delete VPA

Use the deleteVpa method to delete a VPA profile.

bolt.core.deleteVpa(vpa: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_VPA_REMOVE_V3

Raise query or dispute

Use the raiseQuery method to raise query/ dispute for the transaction.

bolt.core.raiseQuery(txnId: String, txnRefId: String, amount: Double, query: String, callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

</td>

<td>
`String` Query or dispute description
</td>
</tr>

<tr>
<td>
callback```

mandatory

Response: Response type is REQUEST_GET_RAISE_QUERY_V3

Fetch query list

Use the fetchQueryList method to fetch the query list.

bolt.core.fetchQueryList(callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_LIST_QUERIES_V3

Deregister

Use the deregister method to deregister your device from UPI.

bolt.core.deregister(callback: PayUUPIBoltCallBack)

The following fields are needed as a request for this API:

Response: Response type is REQUEST_GET_CUSTOMER_DEREGISTER_V3

Check required permissions

Use the hasPermissions method to check if all required permissions are granted.

Check clear cache

Use the clearCache method to clear all ongoing callbacks.

Clear data

Use the clearData method clears user data saved on device. It also clears the device binding.

PayU Account Detail Parameters