Integrate Turbo UPI UI

Integrate Steps

Follow these steps:

Transactional Flow

1.1 Create a Session Token

To enhance security, you must create a session token via a server-to-server (S2S) call between your backend and Razorpay's backend. This session token ensures secure communication between the Turbo SDK and Razorpay's systems.

How to Create a Session Token

1. Trigger the S2S API from your Backend. Use the following API to generate a session token:

   Request Parameters

   customer_reference

   mandatory

   string A unique identifier for the customer provided by the business. The recommended value is mobile number. For example, 9000090000.

   Response Parameters

   token

   string A session token to be used in subsequent session-protected APIs.

   expire_at

   long Expiry time (in seconds) for the session token, used to optimise session handling and reduce unnecessary reinitialisations.

   error

   object The request failure due to business or technical failure.

2. Pass the Generated Token to Turbo SDK. Use the session token in the

   initialisation step

   , ensuring that it is refreshed upon expiry.

1.2 Initialise Turbo SDK

After generating the session token, initialise the Turbo SDK with the session delegate.

Use the initialize(...) method to configure the session.

razorpay
    .upiTurbo
    .initialize(sessionDelegate: Any)

Create/Retry Session Token Mechanism

Using Lambda Callback

To ensure a smooth experience during token expiry, the Turbo SDK provides the TurboSessionDelegate interface with a fetchToken method. This method dynamically fetches and updates the session token without reinitialising the session.

Initialise the TurboSessionDelegate object anonymously and pass it through the initialize method. The SDK will call fetchToken as needed and use the provided callback to handle the updated token. This allows you to seamlessly refresh the session by retrieving a new token via a server-to-server (S2S) call.

Below is an example of creating an instance of the TurboSessionDelegate interface using an anonymous object expression:

val turboSessionDelegate: TurboSessionDelegate = object : TurboSessionDelegate {
        override fun fetchToken(completion: (Session) -> Unit) {
        	// fetch token here and once fetched,
		// it can be passed back to Turbo SDK using completion lambda callback
 	completion(Session(token: <new-token>))
        }
}

// pass the above created turboSessionDelegate object through initialize method
razorpay
    .upiTurbo
    .initialize(turboSessionDelegate)

1.3 Handle UPI Account Linking and Payment Flow

After initialising the Turbo SDK, proceed to securely link UPI accounts and complete the payment flow

1. You need to link the customer's UPI account with your app. Use the code samples given below to fetch the UPI account.

   • If your customer has already linked the UPI account, use the following code to fetch it. If there are no linked UPI accounts, an empty list is returned.

     Code

     Customer Interaction Walkthrough Video

     Kotlin

     copy

     razorpay.upiTurbo?.getLinkedUpiAccounts("9000090000", object : UpiTurboResultListener {
         override fun onSuccess(accList: List<UpiAccount>) {
             if (accList.isNotEmpty()) {
                 Log.d("UpiTurbo", "UpiAccount list")
             } else {
                 // call linkNewAccount()
             }
         }
         override fun onError(error: Error) {
             Log.d("UpiTurbo", error.message)
         }
     })

2. If the customer has not linked any UPI account, they can link UPI accounts using the following method:

   • Link one UPI account at a time:
     Use the following code to link the newly created UPI account with your app. This function can be called from anywhere in the application, providing multiple entry points for customers to link their UPI account with your app.

     Code

     Customer Interaction Walkthrough Video

     Kotlin

     copy

     razorpay.upiTurbo?.linkNewUpiAccountWithUI("9000090000",object: 
     UpiTurboLinkAccountResultListener{
         override fun onSuccess(upiAccount: List< UpiAccount>){
         }
         override fun onError(error: Error){
         }       
     }, "<color>")

3. The Reward feature allows you to allocate rewards to users without specific criteria. To avail rewards, you need to configure them from the dashboard. You can seamlessly integrate this function into your application, providing multiple entry points for users to check their rewards eligibility before completing a payment.

   Kotlin

   copy

   razorpay.upiTurbo.getRewardForCustomer("9000090000", "<action>", "10000", object : Callback<CustomerReward> {
   override fun onFailure(error: Error) {
   
   }
   
   override fun onSuccess(object: CustomerReward) {
   
   }
   })

   Request Parameters

   mobileNumber

   mandatory

   string Customer's mobile number.

   action

   mandatory

   RewardAction This parameter specifies the action to check reward eligibility. Possible values:

   • onboarding: To check reward eligibility for onboarding process.
   • payment: To check reward eligibility for payment process.

   amount

   optional

   string The transaction amount expressed in the currency subunits.

   rewardsDelegate

   mandatory

   delegate This parameter allows you to receive callbacks regarding reward eligibility.

4. To process the payments, call the authorize method of custom checkout with the provided payload.

   Submit method

   copy

   val payload = JSONObject("""
   {
    "currency":"INR",
    "amount":"700",
    "email":"gaurav.kumar@example.com",
    "contact":"9000090000",
    "method":"upi",
    // the below upi block is specific for Turbo UPI Payment
    "upi":{ 
      "flow":"in_app"
    },
    "order_id":"order_L2MUBUOeFItcpU",//optional
    "customer_id":"cust_KQlMczYKcDIqmB"//optional
   }
   """.trimIndent())

5. Pass the vpa and payload objects as shown in the code below. Upon receiving the PaymentData response, you will also receive rewardStatus along with the payment response. Please note that the rewardStatus key will be present in the response only if your eligible for a reward.

   Function call

   copy

   HashMap < String, Object > turboPayload = new HashMap < > ();
   turboPayload.put("upiAccount", upiAccount);
   turboPayload.put("payload", payload);
   razorpay.submit(turboPayload, new PaymentResultWithDataListener() {
       @Override
       public void onPaymentSuccess(String razorpayPaymentID, PaymentData paymentData) {
           JSONObject rewardData = paymentData.getData();
           //show success message with reward data
       }
       @Override
       public void onPaymentError(int code, String response, PaymentData paymentData) {
           //Show error message
       }
   });

   • The payment.getData() function will return a JSONObject.
   Java

   copy

   {
   "reward": {
       "rewardStatus": true
       }
   }

Non-Transactional Flow

You can directly interact with the exposed methods of the Turbo Framework to perform the non-transactional flows listed below.

razorpay.upiTurbo?.manageUpiAccounts("9999999999",
    object : UpiTurboManageAccountListener {
        override fun onError(error: JSONObject)  {
            /*Throws error if UPI Turbo cannot be initialized or throws error*/}

        override fun onSuccess(data: Any) {/*Can be safely ignored*/}
})

razorpay.upiTurbo?.setUpiPinWithUI(accountsWithPinNotSet[0],
    object: UpiTurboSetPinResultListener {
        override fun onSuccess(upiAccount: UpiAccount) {
            // Continue payment
        }
        override fun onError(error: Error) {
            // Show error
        }
    }
)

Additional Features

1. The below function is triggered internally after integrating with the Razorpay Android Custom SDK.

   Initialise SDK

   copy

   import com.razorpay.Razorpay
   
   Razorpay razorpay = new Razorpay(activity);

2. The .onBackPressed() is triggered when a customer tries to exit the app or return to the previous page. The razorpay.upiTurbo.destroy() function clears that particular session. Therefore, when the customer returns, the payment process starts from the beginning.

   Kotlin

   copy

   override fun onBackPressed() {
   razorpay.onBackPressed()
   razorpay.upiTurbo.destroy()
   super.onBackPressed()
   }

Models Exposed from the SDKs

The SDKs given below provide access to exposed models for seamless integration.

2. Test Integration

We recommend the following:

• Complete the integration on UAT before using the prod builds.
• Perform the UAT using the Razorpay-provided API keys.

3. Go-live Checklist

Complete these steps to take your integration live:

• You should get your app id whitelisted by Razorpay to test on prod.

  Handy Tips

  Contact our

  integrations team

  to get your mobile number and app whitelisted.

• Import the prod library from the Github repository → https://github.com/upi-turbo/android-turbo-sample-app/tree/prod/app/libs prod branch.

• Add Proguard rules:

  • keepclassmembers,allowobfuscation class * { @com.google.gson.annotations.SerializedName <fields>; }
  • keepclassmembers enum * { *; }
  • keepclassmembers class * { @android.webkit.JavascriptInterface <methods>; }
  • dontwarn com.razorpay.**
  • keep class com.razorpay.** {*;}
  • keep class com.olivelib.** {*;}
  • keep class com.olive.** {*;}
  • keep class org.apache.xml.security.** {*;}
  • keep interface org.apache.xml.security.** {*;}
  • keep class org.npci.** {*;}
  • keep interface org.npci.** {*;}
  • keep class retrofit2.** { *; }
  • keep class okhttp3.** { *; }

• Replace the UAT credential with the

  Razorpay live keys

  for prod testing.