paytm developer docs logoDeveloperDocumentation
search

UPI Integration

This page explains how you can integrate the UPI payment source in your custom checkout solution to instantly collect the total amount payable from your customer with a single identifier i.e. UPI ID or VPA. Users can conveniently use their VPA to make a secure and immediate payment without entering any bank or card details and without using multiple apps (merchant, SMS, UPI app) for payments.

Paytm offers two UPI flow to collect payment on your checkout page:

  • UPI Intent
  • UPI Collect

Note: If a user wants to make a payment using the UPI payment source, it is mandatory to have the UPI apps installed on their mobile device.

UPI Intent

The UPI Intent flow to collect payment works on mobile browsers/applications with the use of UPI supported apps installed on a user’s mobile device that makes the payment process for them a lot smoother. Its Improved and seamless payment process results in an optimal user experience for your customers by avoiding the switching between multiple apps (merchant, SMS, UPI app) for payments.
 

To see the complete integration flow for UPI Intent, click here.

UPI Collect

The UPI Collect flow is a UPI payment process which allows you to collect payments by prompting the user to enter just the Virtual Payment Address (VPA) on the checkout page of your website/app. User is notified through SMS and is prompted to make the payment on the relevant bank App. The detailed integration steps for UPI Collect are explained below.

Demo of UPI Collect Flow

Integration Steps of UPI Collect Flow

This section explains the integration steps to process payment through UPI Collect flow. Make sure you have followed the Pre-requisites and Integration Steps mentioned on the Paytm Custom Checkout page.
 

  1. User selects BHIM UPI as the payment source on your checkout page and enters the VPA through which it intends to make the payment.
  2. You call the Validate VPA API to validate the VPA.
  3. User clicks the Pay button and then you call the Process Transaction API, where you pass UPI as a paymode in the request to select the UPI Collect flow.

    Note: You can hit the Process Transaction API either through Form post or JSON based.

Postman Collection - Payment processing through UPI

This postman collection lets you quickly understand the flow integration for payment processing through UPI. This will help you to understand and test the APIs with sample request/response on integration environment for UPI Collect integration.
 

Run in Postman


To set up the environment for using the Postman Collection, click  here.

  1. You hit the Process Transaction API as an HTML form post through the client and then Paytm processes the transaction. In response, a polling screen is shown to the user with a session expiry timer and a message that the UPI collect request has been sent to the user on the registered VPA. The user also receives a push notification on the UPI app and/or SMS on their mobile number registered with UPI app, inferring that a UPI Collect request has been sent to them. Please refer to the Process Transaction API sample request/response below: 
    <form method="post" type="redirect" action="https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765">
    <input type="text" name="mid"  value="INTEGR7769XXXXXX9383" />
    <input type="text" name="orderId"  value="ORDERID_98765" />
    <input type="text" name="txnToken"  value="f0bed899539742309eebd8XXXX7edcf61588842333227" />
    <input type="text" name="paymentMode"  value="UPI" />
    <input type="text" name="payerAccount"  value="7777777777@paytm" />
    <input type="submit">
</form>
  2. User accepts the collect request either through the push notification sent over the UPI app or the SMS and completes the payment on the PSP app.
  3. On successful payment, the user gets the payment confirmation on their UPI app.
  4. User goes back to the polling screen and after successful payment, the polling screen is redirected to the Callback URL.
  5. You receive the transaction status on the Callback URL. Please refer to the sample response here.
  6. Prior to verifying the payment, you must validate the checksumhash received in response to the Process Transaction API. To verify it, use the Paytm library with all the parameters in key-value pairs on the merchant server.
  7. Validate the transaction response via server-side request using the Transaction Status API. You must verify the order Id and amount with your DB entries and consider the status as the final status of the transaction in all cases.
  8. After the transaction status verification, you show the final payment status to the user.
  1. You hit the Process Transaction API as a JSON request (S2S) from the client or backend server and then Paytm processes the transaction. In response, a polling screen is shown to the user with a session expiry timer and a message that the UPI collect request has been sent to the user on the registered VPA. The user also receives a push notification on the UPI app and/or SMS on their mobile number registered with UPI app, inferring that a UPI Collect request has been sent to them. Please refer to the sample request/response below:

    Request

    curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"head":{"txnToken":"f0bed899539742309eebd8XXXX7edcf61588842333227"},"body":{"requestType":"NATIVE","mid":"INTEGR7769XXXXXX9383","orderId":"ORDERID_98765","paymentMode":"UPI","payerAccount":"7777777777@paytm"}}'

    Response

    {
    "head": {
        "responseTimestamp": "1595910861048",
        "version": "v1"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "bankForm": {
            "pageType": "redirect",
            "isForceResendOtp": false,
            "redirectForm": {
                "actionUrl": "https://securegw-stage.paytm.in/theia/api/v1/upiPollPage?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765",
                "method": "POST",
                "type": "redirect",
                "headers": {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                "content": {
                    "MERCHANT_VPA": "tlalit5-testintegration@paym",
                    "CHANNEL": "PGPTM",
                    "externalSrNo": "90200728000284938800",
                    "MCC": "5641",
                    "payerVpa": "7777777777@paytm",
                    "txnAmount": "1",
                    "txnToken": "f0bed899539742309eebd8XXXX7edcf61588842333227"
                }
            }
        }
    }
}

    Note: Merchant can also make its own polling screen. Please contact us for more details.

  2. User accepts the collect request either through the push notification sent over the UPI app or the SMS and completes the payment on the PSP app.
  3. On successful payment, the user gets the payment confirmation on their UPI app.
  4. User goes back to the polling screen and after successful payment, the polling screen is redirected to the Callback URL.
  5. You receive the transaction status on the Callback URL. Please refer to the sample response here.
  6. Prior to verifying the payment, you must validate the checksumhash received in response to the Process Transaction API. To verify it, use the Paytm library with all the parameters in key-value pairs on the merchant server.
  7. Validate the transaction response via server-side request using the Transaction Status API. You must verify the order Id and amount with your DB entries and consider the status as the final status of the transaction in all cases.
  8. After the transaction status verification, you show final payment status to the user

Post integration steps

Post completion of integration in your staging environment, it is mandatory to test the Paytm payment sources integration on your website/app before moving into the live environment with production account details (received from Paytm team)

  1. You can view the staging transaction details in the “Test Data” mode on your dashboard.
  2. You must ensure to re-verify the transaction response with Transaction Status API via server to server call for payment flow and not as a one-time activity.

Post successful testing in your staging environment, move your code to the live environment with production account details. These credentials will be available after you activate your business account with Paytm on the Merchant Dashboard.
 

Paytm recommends you to read about Managing Refunds and late payment notifications for a better understanding of the integration.
 

For any issues with the integration, refer to Get in touch.

 

<form method="post" type="redirect" action="https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765">
    <input type="text" name="mid"  value="INTEGR7769XXXXXX9383" />
    <input type="text" name="orderId"  value="ORDERID_98765" />
    <input type="text" name="txnToken"  value="f0bed899539742309eebd8XXXX7edcf61588842333227" />
    <input type="text" name="paymentMode"  value="UPI" />
    <input type="text" name="payerAccount"  value="7777777777@paytm" />
    <input type="submit">
</form>

Request

curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"head":{"txnToken":"f0bed899539742309eebd8XXXX7edcf61588842333227"},"body":{"requestType":"NATIVE","mid":"INTEGR7769XXXXXX9383","orderId":"ORDERID_98765","paymentMode":"UPI","payerAccount":"7777777777@paytm"}}'

Response

{
    "head": {
        "responseTimestamp": "1595910861048",
        "version": "v1"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "bankForm": {
            "pageType": "redirect",
            "isForceResendOtp": false,
            "redirectForm": {
                "actionUrl": "https://securegw-stage.paytm.in/theia/api/v1/upiPollPage?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765",
                "method": "POST",
                "type": "redirect",
                "headers": {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                "content": {
                    "MERCHANT_VPA": "tlalit5-testintegration@paym",
                    "CHANNEL": "PGPTM",
                    "externalSrNo": "90200728000284938800",
                    "MCC": "5641",
                    "payerVpa": "7777777777@paytm",
                    "txnAmount": "1",
                    "txnToken": "f0bed899539742309eebd8XXXX7edcf61588842333227"
                }
            }
        }
    }
}