Integrate with Turbo UPI

Onboarding Flow

Ensure your customers

1. Integration Steps

Follow these steps to integrate with Razorpay Turbo UPI:

1.1 Import Razorpay Package

To integrate Turbo UPI with your Flutter app, start by importing the required packages.

This sets up the SDK and enables your app to handle UPI payments. Use the code snippet below to import the package:

import 'package:razorpay_flutter/razorpay_flutter.dart';

1.2 Initialise Razorpay and Register Event Listeners

Set up the Razorpay instance and register event listeners to handle payment success, failure, and session token refresh.

This ensures your app can respond appropriately to payment outcomes and keep session tokens up to date for a smooth user experience.

Add the following method during initialisation:

void initializeRazorpayWithEvents() {
 // Create a Razorpay instance
 razorpay = Razorpay("YOUR_KEY_ID");
 //Session token event
 razorpay.on(Razorpay.EVENT_FETCH_SESSION_TOKEN, _handleRefreshToken);

 //Payment Events
 razorpay.on(Razorpay.EVENT_PAYMENT_ERROR, handlePaymentErrorResponse);
 razorpay.on(Razorpay.EVENT_PAYMENT_SUCCESS, handlePaymentSuccessResponse);
}

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

   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.

   Errors

   Given below is a list of errors you may face during session token.

2. Create/Retry Session Token Mechanism

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

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

   • Handle the event using the code given below:

     dart

     copy

     void _handleRefreshToken(dynamic response) async {
       // API Call to generate token
       razorpay.upiTurbo.updateSessionToken(token: ‘<session-token>’);
     };

1.4. Handle UPI Account Linking and Payment Flow

You can link a customer's UPI account and initiate payments using the methods described below.

1.4.1 Link Customer's UPI Account

To link a customer's UPI account with your app, use the following code sample. This will prompt the customer to add and link their UPI account.

razorpay.upiTurbo.linkNewUpiAccount(
        customerMobile: mobileNumber,
        color: "#ffffff",
        onSuccess: (List<UpiAccount> upiAccounts) {
                // Handle successful linking. upiAccounts may be empty if no accounts are linked yet.
        },
        onFailure: (Error error) {
                // Handle error during linking.
        }
);

1.4.2 Initiate Payment Using Standard Checkout

To initiate a payment, call the Standard Checkout’s open method with the required payload:

Map<String, Object> payload = {
        'amount': 100, // Amount in the smallest currency unit (e.g., paise)
        'currency': 'INR',
        'prefill': {
                'contact': 'YOUR_MOBILE_NUMBER',
                'email': 'YOUR_EMAIL'
        },
        'theme': {'color': '#0CA72F'},
        'key': 'YOUR_KEY_ID',
        'image': 'https://spaceplace.nasa.gov/templates/featured/sun/sunburn300.png'
};

razorpay.open(payload);

1.4.3 Handle Payment Events

Handle payment success and failure responses:

• Handle Payment Failure:

  Log and display error details such as error code, description, and metadata.

  dart

  copy

  void handlePaymentErrorResponse(PaymentFailureResponse response) {
          /**
           * PaymentFailureResponse contains:
           * 1. Error Code
           * 2. Error Description
           * 3. Metadata
           **/
          print('Payment Error Response: $response');
  }

• Handle Payment Success:

  Log and display key information like order ID, payment ID, and signature.

  dart

  copy

  void handlePaymentSuccessResponse(PaymentSuccessResponse response) {
          /**
           * PaymentSuccessResponse contains:
           * 1. Order ID
           * 2. Payment ID
           * 3. Signature
           **/
          print('Payment Success Response: $response');
  }

By following these steps, you can seamlessly link customer UPI accounts and handle payments using Razorpay Turbo UPI in your Flutter app.

Non-Transactional Flow

Razorpay provides a single exposed function that allows you to manage linked UPI accounts and access all non-transactional flows seamlessly.

razorpay.upiTurbo.manageUpiAccounts(
       customerMobile: "MOBILE_NUMBER", 
       color: "#ffffff", 
       onFailure:(Error error) {   
      
       }
);

Models Exposed from the SDKs

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