Integrate Turbo UPI Headless

1. Integration Steps

Follow these steps:

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:

   Environment based URLs:

   • UAT: https://api-web-turbo-upi.ext.dev.razorpay.in

   • Production: https://api.razorpay.com

   Authorization Header Creation: Base64.encode(${public_key}:${secret})

   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.

1.2 Initialise Turbo SDK

Initialise the TurboSessionDelegate object anonymously and pass it through the initialize method. The SDK will call fetchToken as needed and internally get the token using your implementation.

Inside the fetchToken function implementation, you must get a new token from your server, as mentioned in section

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 Interacting With Turbo SDK

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

1. Get already linked accounts.

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

   JavaKotlin

   copy

   razorpay.upiTurbo.getLinkedUpiAccounts({10 digit mobile number / random customer id}, new UpiTurboResultListener(){
       @Override
         public void onError(@NonNull Error error) {
           //Display error message to user. 
         }
   
       @Override
         public void onSuccess(@NonNull List<UpiAccount> accList) {
           if (accList.size()==0){
             //Display: no UpiAccounts onboarded yet. Please onboard an account.
           }else{
             //Display onboarded UpiAccounts. 
           }
         }
   });

   Watch Out!

   If the device binding is not completed and the getLinkedUpiAccounts is triggered, it will return an OnError with a DEVICE_BINDING_INCOMPLETE error code.

   Request Parameters

   customerMobile

   mandatory

   string The customer's mobile number.

   listener

   object The listener to be sent should be of type UpiTurboResultListener.

   Response Parameters

   onSuccess

   This function is triggered if the list is fetched successfully. accList can be empty to indicate that no accounts have been linked yet.

   onError

   This function is triggered in case an error is thrown during the retrieval process, either by the Razorpay SDK or the Bank SDK.

2. New user onboarding / Linking additional accounts

   If you get DEVICE_BINDING_INCOMPLETE error code in the above section, you will need the user to complete the new onboarding. For already onboarded users, this function will help to link more accounts.

   JavaKotlin

   copy

   razorpay.upiTurbo.linkNewUpiAccount({10 digit mobile number / random customer id}, new UpiTurboLinkAccountListener() {
       @Override
       public void onResponse(@NonNull UpiTurboLinkAction action) {
           switch (action.getCode()) {
               case ASK_FOR_PERMISSION:
                   action.requestPermission();
                   break;
               case SHOW_PERMISSION_ERROR:
                   //Show dialog to redirect the user to the settings page of the application to grant permissions
                   break;
               case SELECT_SIM:
                   if (action.getError() != null) {
                       //Display error message
                       return;
                   }
                   if (action.getData() != null && action.getData() instanceof List) {
                       try {
                           List << ? > simList = (List << ? > ) action.getData();
                           Sim sim1 = (Sim) simList.get(0);
                           Sim sim2 = (Sim) simList.get(1);
                           //Show dialogue with a list of sims
                           action.selectedSim(sim1);
                       } catch (ClassCastException e) {}
                   }
                   break;
               case SELECT_BANK:
                   if (action.getError() != null) {
                       return;
                   }
                   if (action.getData() != null && action.getData() instanceof AllBanks) {
                       AllBanks allBanks = (AllBanks) action.getData();
                       List < Bank > popularBanks = allBanks.getPopularBanks();
                       List < Bank > allBanksList = allBanks.getBanks();
                       //show dialog with bank list
                       action.selectedBank(popularBanks.get(0));
                   }
                   break;
               case SELECT_BANK_ACCOUNT:
                   if (action.getError() != null) {
                       return;
                   }
                   if (action.getData() != null && action.getData() instanceof List) {
                       List << ? > bankAccountList = (List << ? > ) action.getData();
                       if (bankAccountList.get(0) instanceof BankAccount) {
                           //Show dialog with bank account list
                           action.selectedBankAccount((BankAccount) bankAccountList.get(0));
                       }
                   }
                   break;
               case SETUP_UPI_PIN:
                   Card card = new Card("01", "28", "234567");
                   action.setupUpiPin(card);
                   break;
               case STATUS:
                   if (action.getError() != null) {
                       //Show error message
                       return;
                   }
                   if (action.getData() != null && action.getData() instanceof List) {
                       List << ? > onboardedUpiAccounts = (List << ? > ) action.getData();
                       showUpiAccount((UpiAccount) onboardedUpiAccounts.get(0));
                   }
                   break;
               case LOADER_DATA:
                   //Use this trigger to easily show background process happening in the SDK during onboarding
                   showLoaderData((String) action.getData());
                   break;
           }
       }
   });

   Handy Tips

   Turbo SDK will auto-select the SIM card in few cases and the SELECT_SIM action will not be triggered in such cases:

   • Device has only one SIM card.

   • Device has multiple SIM cards and the mobile number provided by you matches the number on one of the SIM cards.

3. Invoke the below function in your Activitys onRequestPermissionsResult function.

   JavaKotlin

   copy

   @Override
   public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults){
       if (requestCode == 101) {
           // make sure not to use the 101 requestCode for your other cases 
           razorpay.upiTurbo.onPermissionsRequestResult()
           return
       }
       super.onRequestPermissionsResult(requestCode, permissions, grantResults);
   }

4. Additionally razorpay.onBackPressed() is triggered when a user tries to exit the app or return to the previous page. The releaseActivityReference() function releases the allocated memory.

   JavaKotlin

   copy

   @Override
   public void onBackPressed() {
       razorpay.onBackPressed();
       releaseActivityReference();
       super.onBackPressed();
   }

5. To process the payment, first create a payload, which will be a JSONObject as shown in the code below.

   JavaKotlin

   copy

   JSONObject payload = new JSONObject();
   payload.put("currency", "INR");
   payload.put("email", "gaurav.kumar@example.com");
   payload.put("contact", "9000090000");
   payload.put("amount", "10000");
   payload.put("method", "upi");
   JSONObject upiBlock = new JSONObject();
   upiBlock.put("flow", "in_app");
   payload.put("upi", upiBlock);
   payload.put("order_id", "order_L2MUBUOeFItcpU");//mandatory
   payload.put("customer_id", "cust_KQlMczYKcDIqmB");//optional

6. Pass the upiAccount and payload objects as shown in the code below.

   Java

   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) {
       }
       @Override
       public void onPaymentError(int code, String response, PaymentData paymentData) {
           //Show error message
       }
   });

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.getBalance(upiAccount, new Callback<AccountBalance>() {
@Override
public void onSuccess(AccountBalance accountBalance) {
}

@Override
public void onFailure(@NonNull Error error) {
}
});

razorpay.upiTurbo.changeUpiPin(upiAccount, new Callback<UpiAccount>() {
@Override
public void onSuccess(UpiAccount upiAccount) {
}

@Override
public void onFailure(@NonNull Error error) {
}
});

razorpay.upiTurbo.resetUpiPin(card, upiAccount, new Callback<Empty>() {
@Override
public void onSuccess(Empty empty) {
}

@Override
public void onFailure(@NonNull Error error) {
}
});

razorpay.upiTurbo.delink(upiAccount, new Callback<Empty>() {
@Override
public void onSuccess(Empty empty) {
}

@Override
public void onFailure(@NonNull Error error) {  
}
});

Additional Features

1. To get the device binding status, please use the method isDeviceOnboarded() which returns a boolean. It indicates whether the device binding, which is a prerequisite for adding UPI accounts, is done with the user's mobile number.

   Kotlin

   copy

   if (Razorpay.UpiTurbo.isDeviceOnboarded(activity: Activity)) {
       // User Device Binded
   } else {
       // Call Link New Account for Device Binding
   }

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.

• As a compliance requirement, you need to get approval from Google for READ_SMS permission. Refer

  to the Google article

  for more details.

• 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.