Credit/Debit Cards Integration

This page explains how you can integrate Credit/Debit Cards in the Custom Checkout solution to collect payment from your customers. You can fetch the large database of around 200 million cards saved with Paytm users accounts and present them on your payment page. This allows the users to make quick and easy payments using their saved cards without the need of entering the complete card details.

Demo

Integration Steps

This section explains the integration steps to process payment through a new Debit/Credit Card or saved cards with a user's Paytm account. Make sure you have followed the Pre-requisites and Integration Steps mentioned on the Paytm Custom checkout page.

Paytm user's Saved Cards

In case you want to show Paytm user’s saved cards on your checkout page, follow the steps below:

User selects Paytm for payment on your checkout page and enters their Paytm registered mobile number.
You call the Send OTP API to verify their account and then Paytm triggers the OTP on a mobile number passed in the request.
To validate the OTP entered by a user, you call the Validate OTP API.
Your backend server calls the Fetch Payment Options API using the transaction token received in a response to Initiate transaction API request.
You receive the Paytm user’s saved credit and debit cards In response to Fetch Payment Options API. In the response, you also receive the card type, issuing bank, and current success rate on that card.

Note:
a. For maestro cards, CVV and Expiry Date are not required for any transaction.
b. You can consume the success rate of the card and intimate a user so they could choose any other payment method.
User selects the saved card of its Paytm account, enters the required details like CVV and clicks the Pay button, at which point you call the Process Transaction API.

Note: You can hit the Process Transaction API either through Form post or JSON based. Using JSON based integration, you can also collect OTP for 2FA on your page for major banks.

Postman Collection - Payment processing through Cards

This postman collection lets you quickly understand the flow integration for payment processing through credit/debit cards. This will help you to understand and test the APIs with sample request/response on integration environment for both new and paytm user’s saved credit/debit cards integration.

Run in Postman

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

You hit the Process Transaction API as an HTML form post through the client. Paytm processes the transaction and redirects the user to the bank page to complete the payment by entering the OTP. Please refer to the sample request/response below:

<form method="post" type="redirect" action="https://securestage.paytmpayments.com/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="CREDIT_CARD" />
    <input type="text" name="cardInfo" value="1159332987||111|" />
    <input type="text" name="AUTH_MODE" value="otp" />
    <input type="submit" />
</form>

After the user completes the transaction on the bank page, Bank redirects the user back to Paytm which in turn redirects the user back on your payment confirmation page.
You receive the transaction status on the Callback URL. Please refer to the sample response here.
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.
Validate the transaction response via server-side request using theTransaction 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.
After the transaction status verification, you show final payment status to the user.

You hit the Process Transaction API as a JSON request (S2S) from the client or backend server. Paytm processes the request and passes the Direct Bank Form and Redirect Bank form flow in response to your request. Please refer to the sample request/response below:

Request

curl -X POST 'https://securestage.paytmpayments.com/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":"CREDIT_CARD","cardInfo":"1159332987||111|","authMode":"otp"}}'

Response

{
    "head": {
        "responseTimestamp": "1595585135939",
        "version": "v1"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "bankForm": {
            "pageType": "redirect",
            "isForceResendOtp": false,
            "redirectForm": {
                "actionUrl": "https://securestage.paytmpayments.com/mockbank/MockJSP/PAReqEntry.jsp?TrackID=90200724000183473830&amt=1&cardnum=NDExMTExMTExMTExMTExMQ==",
                "method": "post",
                "type": "redirect",
                "headers": {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                "content": {
                    "MD": "1466814881",
                    "PaReq": "eJxVUsFy4jAM/ZVMzrvYSgokjOIOhdJmZklYCoc9ehy3pEMcapsCf792IO3uTU9PfpKejPfnZh98Sm3qVmUhDGgYSCXaqlZvWbjdLH4m4T3DzU5LOX+R4qglw6U0hr/JoK6ycFEJoeBpltdrU552kP5WpiCvCchlFjJcTdfyg+GtAXP6gwhJD52SFjuuLEMuPh7ygg2HNB67ihvERup8ziACGtEYyRWi4o1kZfGYjoNZuVxui3w23eRl8RL82syRdDSK9qisvrB4OELSAzzqPdtZezATQg78YpuBaJtrdOL7vbRIfAmS79FWRx8ZJ3muKzZ9f10YSEq9PenRiBf6j1XwubqodZsh8RVYcStZRGFMU4gCChNIJtEdki6PvPGzsLWBH5CmA0rdttcUHnyn6RWAIz33bw6d/9qdp1+qRyjPh1ZJV+Gs+4qRfE8+e/YWC+vcG8UJ9MNBDOO7zu6O8jq1cymKadoJeYDEPya3S5Lb8V3036f4C56Zvls=",
                    "TermUrl": "https://securestage.paytmpayments.com/instaproxy/bankresponse/HDFC/CC/90200724000183473830"
                }
            }
        }
    }
}

You select one of the following flows supported by Paytm to complete the transaction:

Direct Bank Form - Direct bank form enables you can collect and verify the bank's One-time password (OTP) on your app or website guaranteeing higher success rates. It is supported for majority banks. For more details refer to this section

OTP on Merchant Page -

In the traditional card transaction, customers are redirected to a 3rd party bank page for user authentication. Depending on the bank there are multiple methods for authentication, the most prevalent is via OTP. Once authentication is complete, the user gets redirected to the aggregator. Aggregator completes the payment process and redirects the customer to the merchant APP/website. There are multiple drawbacks of this process -

Multiple Redirections - A user undergoes at least 3-7 redirections to complete a single payment. Often these redirections take place on the user's internet and hence are susceptible to dropout leading to transaction failure
Cannot track the user's actions - Since the user moves to 3rd party bank environment for authentication, it is not possible to track his action. The tracking is required as the maximum failures happen as the user drops out during the payment journey
Bad User journey - Bank's user journey is often not up to the standards of modern-day UX on APPs and websites. Multiple banks have their OTP page designed of desktops and are not adaptive to small mobile screens. Lastly, the experience and UX of bank pages are not similar to a merchant's website/APP giving a disconnected experience to the user

Paytm powered OTP pages :

In order to bypass these problems, Paytm has come up with the Paytm Powered OTP pages. This is an API-based solution that helps you complete the credit/debit and EMI transactions on your APP/website without a single redirection. Additionally, you can auto-read OTP on a customer's APP to provide a seamless experience. There are multiple upsides of this product

High Success Rate - The seamless experience of zero redirection and auto-capture of OTP transcends to higher success rates of card transactions
Reduction in payment time - The average payment time of a user is less than 15 seconds on this flow. For traditional transactions happening on bank pages, this is between 30 - 50 seconds
User tracking - One is able to track the user actions like receiving of OTP, entering the OTP, the correctness of OTP entered, and frequency of clicks on resend OTP, Cancel, Submit on the OTP Page, etc to better understand the user journey
Consistent user experience - You can keep the UX of the complete payment journey consistent with your APP/website standards.

Demo :

Integration Steps:

User selects the Credit Card and Debit Card on the merchant checkout page or enters fresh card details. He clicks on pay to proceed
On click of pay, you call the Process Transaction API from the client or backend server.
In response from the Paytm site, you will get one of the following -
1. Redirect Bank Form Object- This means that you cannot capture the OTP on your page. You are required to redirect the customer bank's page (action URL within redirect form object)
2. Redirect Bank Form and direct bank form object - In this scenario, you can capture the OTP on your page
  1. Use the direct form object to capture the OTP on your page Or
  2. Use the redirect bank form, to complete the transaction on the bank page
While creating your own page to capture the customer's OTP, You can display the card scheme and issuing bank logo on the OTP page(action URL within the Process Transaction API response). and the following workflows are possible -
1. Submission on OTP - After entering the OTP, When the user clicks on submit
  1. You call the Direct Bank Request API with the submit request type to validate bank OTP in your app or website. There are two possible scenarios:
    - In Case OTP is correct: Validate the transaction response via server-side request using the Transaction Status API
    - In Case OTP is incorrect: Paytm provides a response with incorrect OTP information and provides the retry status flag in the response, This flag indicates whether a retry is allowed or not for the transaction.
2. Cancellation of the transaction - In case the user does not want to complete the transaction and clicks on the cancel button on the OTP page.
  1. You call the Direct Bank Request API with the cancel request type to cancel the transaction.
  2. Validate the transaction response via server-side request using the Transaction Status API
3. Resending of OTP - In case the user resends OTP to get the OTP for the transaction again.
  1. To resend the OTP to the user you call the Direct Bank Request API with the resend request type.
  2. Paytm send a request to Bank to initiate a new OTP.
    - *Note - You can request a maximum of 2 times to resend OTP.
4. Pay on Bank feature - In case the user does not complete the transaction on your OTP page and click on the "Pay on Bank".
  1. You call the action URL within the Direct form object in the "Pay on Bank" payload and Redirect the customer to the bank page.
  2. After completion of authentication, the customer is redirected back to Paytm where we complete the payment. Post this the customer is redirected to the merchant's callback URL
  3. Validate the transaction response via server-side request using the Transaction Status API

Things to keep in mind :

Onboarding Process: To integrate or enable this product, reach out to merchant helpdesk or CMT team member and request enablement of "Merchant on OTP Page" preference
Controlling the page where OTP is captured: While the option of the transaction on the bank page is always possible via the redirect form, the option to capture OTP on your page via direct form may or may not come. The availability of this option is dependent on a variety of factors like the bank and scheme of cards, acquiring banks configured on you, the real-time performance of the pages, etc. Hence there are three possible integrations -
- Integration 1: You invoke the flow to capture the OTP depending upon the availability of process transaction API response
- Integration 2: You request where do you intend to capture the OTP in the Process Transaction API via attribute preferredOtpPage. This attribute has two possible value
  - "merchant" - We will try to get the direct form to you. If we are unable to do so, then we will fail the transaction
  - "bank" - We will try to get get the redirect form to you. If we are unable to do so, then we will fail the transaction=
Auto Read OTP: To reduce incorrect OTP cases, you can integrate Paytm Assist SDK. Paytm Assist automatically reads the OTP and fills it in the assist window.
OTP on Paytm Page: If you wish to avoid integration effort, Paytm can provide a consistent authentication experience via Paytm OTP pages. To enable this feature reach out to merchant helpdesk or CMT team member and request enablement of "Merchant Redirection Flow Enabled" preference.

Issuer Coverage:

Issuer coverage is available at issuing bank-card schemes and BIN Mapping is provided below. BIN Mapping is more accurate as few BINs within a given issuing bank are not supported.

Credit Card: Based on the issuing bank coverage below, we are complete transaction 80% of transactions on the merchant page
Debit Card: Based on the issuing bank coverage below, we are complete transaction 40% of transactions on the merchant page

Credit Card Issuing Bank	Card Scheme
AXIS	VISA
AXIS	Mastercard
CITI	VISA
CITI	Mastercard
HDFC	VISA
HDFC	Mastercard
HDFC	Diners
ICICI	VISA
ICICI	Mastercard
RBL	Mastercard
SBI	VISA
SBI	Mastercard

Debit Card Issuing Bank	Card Scheme
AXIS	Mastercard
AXIS	VISA
BOB	VISA
BOB	Rupay
CITI	Mastercard
CANARA	Mastercard
CANARA	VISA
DBS	VISA
HDFC	VISA
HDFC	Mastercard
ICICI	Mastercard
ICICI	VISA
KOTAK	VISA
PNB	Rupay
PAYTM	Rupay
PAYTM	VISA
YES	Mastercard

Bin List:

Paytm powered OTP - Bin List

Redirect Bank Form - In this flow, the user is redirected to the bank page to complete the payment where you collect and verify the OTP. User completes the transaction on the bank page and the bank redirects the user back to Paytm which in turn redirects the user back on your payment confirmation page.

You receive the transaction status on the Callback URL. Please refer to the sample response here.
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.
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.
After the transaction status verification, you show the final payment status to the user.

New Credit/Debit Card

In case you want to integrate payment with new Credit/Debit Cards on your checkout page, follow the steps below:

User selects the Credit/Debit Card on your checkout page and starts entering the card details. As soon as the first 6 digits are entered, you call the Fetch Bin Detail API to get the BIN details of the card.
Paytm validates the card and returns the BIN details like the card type (VISA, Master, AMEX etc.), issuing bank, and the current success rate of bin.

Note:
a. For maestro cards, CVV and Expiry Date are not required for any transaction.
b. You can consume the success rate of the card and intimate a user so they could choose any other payment method.
User clicks Pay to proceed for checkout and you call the Process Transaction API.

You can hit the Process Transaction API either through Form post or JSON based. Using JSON based integration, you can also collect OTP for 2FA on your page for major banks.

<form method="post" type="redirect" action="https://securestage.paytmpayments.com/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="DEBIT_CARD" />
    <input type="text" name="cardInfo" value="|5129670406454327|983|122025" />
    <input type="text" name="AUTH_MODE" value="otp" />
    <input type="submit" />
</form>

After the user completes the transaction on the bank page, bank redirects the user back to Paytm which in turn redirects the user back on your payment confirmation page.
You receive the transaction status on the Callback URL. Please refer to the sample response here.
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.
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.
After the transaction status verification, you show final payment status to the user.

You hit the Process Transaction API as a JSON request (S2S) from the client or backend server. Paytm processes the request and passes the Direct Bank Form and Redirect Bank Form flow in response to your request. Please refer to the sample request/response below:

Request

curl -X POST 'https://securestage.paytmpayments.com/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":"CREDIT_CARD","cardInfo":"1159332987||111|","authMode":"otp"}}'

Response

{
    "head": {
        "responseTimestamp": "1595585135939",
        "version": "v1"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "bankForm": {
            "pageType": "redirect",
            "isForceResendOtp": false,
            "redirectForm": {
                "actionUrl": "https://securestage.paytmpayments.com/mockbank/MockJSP/PAReqEntry.jsp?TrackID=90200724000183473830&amt=1&cardnum=NDExMTExMTExMTExMTExMQ==",
                "method": "post",
                "type": "redirect",
                "headers": {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                "content": {
                    "MD": "1466814881",
                    "PaReq": "eJxVUsFy4jAM/ZVMzrvYSgokjOIOhdJmZklYCoc9ehy3pEMcapsCf792IO3uTU9PfpKejPfnZh98Sm3qVmUhDGgYSCXaqlZvWbjdLH4m4T3DzU5LOX+R4qglw6U0hr/JoK6ycFEJoeBpltdrU552kP5WpiCvCchlFjJcTdfyg+GtAXP6gwhJD52SFjuuLEMuPh7ygg2HNB67ihvERup8ziACGtEYyRWi4o1kZfGYjoNZuVxui3w23eRl8RL82syRdDSK9qisvrB4OELSAzzqPdtZezATQg78YpuBaJtrdOL7vbRIfAmS79FWRx8ZJ3muKzZ9f10YSEq9PenRiBf6j1XwubqodZsh8RVYcStZRGFMU4gCChNIJtEdki6PvPGzsLWBH5CmA0rdttcUHnyn6RWAIz33bw6d/9qdp1+qRyjPh1ZJV+Gs+4qRfE8+e/YWC+vcG8UJ9MNBDOO7zu6O8jq1cymKadoJeYDEPya3S5Lb8V3036f4C56Zvls=",
                    "TermUrl": "https://securestage.paytmpayments.com/instaproxy/bankresponse/HDFC/CC/90200724000183473830"
                }
            }
        }
    }
}

You select any one of the following flows supported by Paytm to complete the transaction:

Direct Bank Form - You can collect and verify the bank OTP on your page on the web or app. Currently, it is supported for ICICI, HDFC, Citibank, Axis and SBI only. Paytm calls the bank to send OTP to the user. Bank returns OTP to the user and confirmation to Paytm. Paytm returns a set of supported functions for validating bank OTP. You call the Direct Bank Request API to validate bank OTP in your app or website.
Redirect Bank Form - It redirects the user to the bank page to complete the payment where you collect and verify the OTP. User completes the transaction on the bank page. Bank redirects the user back to Paytm which in turn redirects the user back on your payment confirmation page.

You receive the transaction status on the Callback URL. Please refer to the sample response here.
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.
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.
After the transaction status verification, you show the 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).

You can view the staging transaction details in the “Test Data” mode on your dashboard.
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.