TPV S2S Integration - Debit Card

Understand Third-Party Validation (TPV) support on S2S Integration with the debit card payment method by Razorpay.

Investors can pay with a debit card and input the necessary card details (card number, CVV, expiry information). When a debit card payment request is made, the system checks to confirm that the bank account associated with the debit card matches the registered bank account details. If this verification is successful, the customer is prompted to enter a one-time password (OTP) from the card to complete the payment.

Checkout Flow

Guest Checkout: Investors can add a new debit card for their purchase in this flow. They are given the option to save the card for future use or proceed with the purchase without saving the card details.
[Coming Soon] Tokenized or Saved Card: We will introduce a streamlined checkout experience where customers can select a saved debit card for their purchase, eliminating the need to re-enter the card information.

Handy Tips

You must have a PCI compliance certificate to enable this feature on your account. For more details, refer to the
PCI Compliance
website.
To begin accepting Debit Card payment requests, make sure to prominently display Debit Cards as a payment option in your user interface (UI).

Prerequisites

Contact our
Support Team
to get this feature enabled for your account.
Keep the API key (combination of Key_Id and Key_Secret) handy for integration.
Generate API Keys from the Dashboard
if you have not done already.
Configure the payment capture settings
on the Razorpay Dashboard.

Integration

Given below are the steps:

Step 1: Collect Investor Bank Account details

Collect the investor's bank details or UPI ID at the time of investor registration.

Step 2: Create an Order

If the user is choosing debit cards on your UI, pass the method as card.

POST

/orders

Request Parameters

Create a request payload using the following attributes:

amount

mandatory

integer The transaction amount expressed in paise (currency supported is INR). For example, for an actual amount of ₹1, the value of this field should be 100.

currency

mandatory

string The currency in which the transaction should be made. You can create orders in INR only.

receipt

optional

string Receipt number that corresponds to this order, set for your internal reference. Maximum length is 40 characters.

notes

optional

json object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

method

mandatory

string The payment method used to make the payment. If this parameter is not passed, investors will be able to make payments using both netbanking and UPI payment methods. Possible values:

netbanking: Investors can make payments only using netbanking.
card: Investors can make payments using debit card.
upi: Investors can make payments only using UPI.

bank_account

mandatory

object Details of the bank account that the investor has provided at the time of registration.

account_number

mandatory

string The bank account number from which the investor should make the payment. For example, 765432123456789 Payments will not be processed for an incorrect account number.

name

mandatory

string The name linked to the bank account. For example, Gaurav Kumar.

ifsc

mandatory

string The bank IFSC. For example, HDFC0000053.

Step 3: Create a Payment

POST

/payments/create/json

curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \
-X POST https://api.razorpay.com/v1/payments/create/json \
-H "Content-Type: application/json" \
 -d '{
  "amount": "500",
  "currency": "INR",
  "email": "gaurav.kumar@example.com",
  "contact": "9000090000",
  "order_id": "order_GAWN9beXgaqRyO",
  "method": "card",
  "card":{
    	   "number": "4111111111111111",
    	   "name": "Gaurav",
    	   "expiry_month": "11",
    	   "expiry_year": "30",
    	   "cvv": "100"
  },
}'

Request Parameters

amount

mandatory

integer The transaction amount expressed in paise (currency supported is INR). For example, for an actual amount of ₹1, this field's value should be 100.

currency

mandatory

string The currency in which the transaction should be made. You can create Orders in INR only.

order_id

mandatory

string Unique identifier of the order created in the previous step.

method

mandatory

string The payment method used to make the payment. Possible value: card

card

mandatory

`object`` Details associated with the card.

number

string Unformatted card number.

name

string Name of the cardholder.

expiry_month

string Expiry month for the card in MM format.

expiry_year

string Expiry year for the card in YY format.

cvv string CVV printed on the back of the card.

mandatory

string The customer's email address.

contact

mandatory

string The customer's phone number.

Response Parameters

If the payment request is valid, the response contains the following fields:

razorpay_payment_id

string Unique identifier of the payment. Present for all responses.

array A list of action objects available to you to continue the payment process. Present when the payment requires further processing.

action

string An indication of the next step available to you to continue the payment process. Possible values:

redirect - Use this URL to redirect the customer to the bank page.
poll - A payment request notification is sent to the customer's UPI PSP app.

url

string URL to be used for the action indicated.

Step 4: Store Fields in your Server

A successful payment returns the following fields to the Checkout form.

You need to store these fields in your server.
You can confirm the authenticity of these details by verifying the signature in the next step.

razorpay_payment_id

string Unique identifier for the payment returned by Checkout only for successful payments.

razorpay_order_id

string Unique identifier for the order returned by Checkout.

razorpay_signature

string Signature returned by the Checkout. This is used to verify the payment.

Step 5: Verify the Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

To verify the razorpay_signature returned to you by the Checkout form:

Create a signature in your server using the following attributes:
- order_id: Retrieve the order_id from your server. Do not use the razorpay_order_id returned by Checkout.
- razorpay_payment_id: Returned by Checkout.
- key_secret: Available in your server. The key_secret that was generated from the
  Razorpay Dashboard
  .

Use the SHA256 algorithm, the razorpay_payment_id and the order_id to construct a HMAC hex digest as shown below:

generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);

  if (generated_signature == razorpay_signature) {
    payment is successful
  }

If the signature you generate on your server matches the razorpay_signature returned to you by the Checkout form, the payment received is from an authentic source.

Generate Signature on Your Server

Given below is the sample code for payment signature verification:

RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String secret = "EnLs21M47BllR3X8PSFtjtbd";

JSONObject options = new JSONObject();
options.put("razorpay_order_id", "order_IEIaMR65cu6nz3");
options.put("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");
options.put("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");

boolean status =  Utils.verifyPaymentSignature(options, secret);

Post Signature Verification

After you have completed the integration, you can

set up webhooks

, make test payments, replace the test key with the live key and integrate with other

APIs

Payment Capture Settings

After payment is authorized, you need to capture it to settle the amount to your bank account as per the settlement schedule. Payments that are not captured are auto-refunded after a fixed time.

Watch Out

You should deliver the products or services to your customers only after the payment is captured. Razorpay automatically refunds all the uncaptured payments.
You can track the payment status using our
Fetch a Payment API
or webhooks.

How to Capture Payments

Auto-capture payments (recommended)
Authorized payments can be automatically captured. You can auto-capture all payments
using global settings
on the Razorpay Dashboard.

Watch Out!
Payment capture settings work only if you have integrated with Orders API on your server side. Know more about the
Orders API
.
Manually capture payments
Each authorized payment can also be captured individually. You can manually capture payments using:
- Payment Capture API
- Dashboard

Know more about

Capture Settings for payments

Is this integration guide useful?

ON THIS PAGE

Request Parameters

Step 3: Create a Payment