Integrate Turbo UPI UI

1. Integration Steps

Follow these steps:

1.1 Initialise the Razorpay Checkout

Initialise the SDK and set up the Checkout instance (Razorpay) to handle payment outcomes like success and errors by listening to delegate methods.

var razorpay = RazorpayCheckout.initWithKey(
 "YOUR_KEY_ID",
 andDelegate: self,
 withPaymentWebView: wkWebView,
 UIPlugin: RazorpayTurboUPI.UIPluginInstance
)

1.2 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})

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

   initialisation step

   , ensuring that it is refreshed upon expiry.

1.3 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?
       .upiTurboUI?
       .initialize(sessionDelegate: Any)

Create/Retry Session Token Mechanism

Using Delegate Pattern

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:

extension ViewController: TurboSessionDelegate {
    func fetchToken(completion: @escaping (Session) -> Void) {
// fetch token here and once fetched,
		// it can be passed back to Turbo SDK using completion delegate 
	completion(Session(token: <new-token>)
    }
}

1.4 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 below code samples to fetch the UPI account.

   Watch Out!

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

   • Get the customer's linked UpiAccount list using the below code. This function can be called from anywhere in the application, providing multiple entry points for customers to link their UPI account with your app.
   SwiftObjective C

   copy

   razorpay?.upiTurboUI?.getLinkedUpiAccounts("9000090000", resultDelegate: self)

   Request Parameters

   mobile_num

   string The customer's mobile number.

   Delegate

   object The Delegate to be sent is of type UpiTurboResultDelegate.

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

     SwiftObjective C

     copy

     extension ViewController: UPITurboResultDelegate {
      func onSuccessFetchingLinkedAcc(_ accList: [UpiAccount]) {
          if accList.count > 0 {
             print("Success Fetching Accounts")
          } else {
             // call linkNewUpiAccount()
          }
      }
     
      func onErrorFetchingLinkedAcc(_ error: TurboUpiPlugin.TurboError?) {
         print("Error: \(error?.errorDescription)")
         print("Error code: \(error?.errorCode)")
      }
     }

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.
   SwiftObjective C

   copy

   self.razorpay?.upiTurboUI?.linkNewUpiAccount(
    mobileNumber: "MOBILE_NUMBER",
    color: "<accent-color>",
    completionHandler: { upiAccounts, error in
        print(upiAccounts)
    }
   )

   Request Parameters

   mobile_num

   mandatory

   string Customer's mobile number needed to initialise the SDKs.

   color

   string Colour in HEX format.

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.

   SwiftObjective C

   copy

   razorpay.upiTurboUI?.getRewardForCustomer(
       mobileNumber: "9000090000", 
       action: RewardAction.payment, 
       amount: "10000", 
       rewardsDelegate: self
   )
   
   extension ViewController: UpiTurboCustomerRewardsDelegate {
       
       func onSuccess(_ reward: CustomerReward) {
           // Handle success
       }
       
       func onFailure(_ error: TurboError?) {
           // Handle failure
       }
   }

   Request Parameters

   mobileNumber

   mandatory

   string The 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.
   • payment: To check reward eligibility for Payment.

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

   SwiftObjective C

   copy

   let turboPayload: [AnyHashable: Any] = [
   "currency": "INR",
   "amount": "700",
   "email": "EMAIL_ID",
   "contact": "9000090000",
   "method": "upi",
   "upi": [
       "flow": "in_app"
      ],
     "order_id": "YOUR_ORDER_ID",  
   ]
   
   turboPayload["upiAccount"] = upiAccount
   razorpay?.authorize(turboPayload)
   
   extension ViewController: RazorpayPaymentCompletionProtocol {
   
   func onPaymentSuccess(_ payment_id: String, andData response: [AnyHashable: Any]) {
       let rewardStatus = response["rewardStatus"]
       // Show payment success screen with reward if rewarded
   }
   
   func onPaymentError(_ code: Int32, description str: String, andData response: [AnyHashable: Any])
   {
       // Handle payment error
   }
   }

   Request Parameters

   customer_id

   optional

   string Unique identifier of the customer to whom the Customer Identifier must be tagged. Create a customer using the

   Customer API

   amount

   mandatory

   integer The transaction amount expressed in the currency subunit. For example, for an actual amount of ₹299.35, the value of this field should be 29935.

   currency

   mandatory

   string The currency in which the transaction should be made.

   email

   mandatory

   string Email address of the customer.

   contact

   mandatory

   string Customer's phone number.

   order_id

   mandatory

   string Order id generated via the

   Orders API

   .

   method

   mandatory

   string The payment method used by the customer on Checkout. In this case, it is upi (default).

   upi

   mandatory

   Details of the UPI payment.

   flow

   mandatory

   string Type of the UPI method. In this case, it is in_app.

Non-Transactional Flow

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

self.razorpay?.upiTurboUI?.manageUpiAccount(
    mobileNumber: "<mobile_num>",
    color: "<accent-color>"
)

Additional Features

if RZPTurboUPI.isDeviceOnboarded() {
  // User device onboarded 
} else {
  // Call Link New Account for Device Binding
}

RZPTurboUPI.clearSDKState()

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/ios-sample-app custom_ui/turbo_ui branch.

• Switch to Prod environment and podfile.

• Replace the UAT credential with the

  Razorpay live keys

  for prod testing.

For iOS users, outgoing device binding SMS is editable by default. To ensure these SMS messages are non-editable, you must complete the following steps:

Requesting UPI Device Validation Entitlement