Business Seeks Customer Consent, Saves Card Details With Razorpay

New Card Workflow

New cards are the cards that are not saved with Razorpay previously. Follow the below integration steps:

Changes on checkout UI.
Changes in integration code.

1. Checkout UI

You should modify your user interface to explicitly receive customer consent for saving card details as tokens with card networks.

2. Integration Code

2.1 Create a Customer

You can create customers using the Create a Customer API. The customer_id received in the response should be passed in the Create Payment request.

2.2 Create Payment

Use the following code to Create a Payment.

Custom Checkout

  Pay
  
       var razorpay = new Razorpay({
        key: "",
        image: "https://i.imgur.com/n5tjHFD.jpg",
        name: "Gaurav Kumar",
       });
       var data = {
        amount: 6666,
        currency: "INR",
        order_id: "order_ISsp1ekSCHgoAw",
        email: "gaurav.kumar@example.com",
        contact: +919876543210,
        notes: {
          address: "Ground Floor, SJR Cyber, Laskar Hosur Road, Bengaluru",
        },
        customer_id: "cust_1Aa00000000001",
        save: 1,
        method: "card",
        card[number]: '4242424242424242',
        card[expiry_month]: '11',
        card[expiry_year]: '23',
        card[cvv]: '123',
        card[name]: 'Gaurav Kumar'
       };

       document.getElementById("rzp-button1").onclick = function(){
        razorpay.createPayment(data);
        razorpay.on("payment.success", function(resp) {
          alert(resp.razorpay_payment_id)
          });
        razorpay.on("payment.error", function(resp){alert(resp.error.description)});
}

Request Parameters

save mandatory : integer Determines whether Razorpay should save customer card details as tokens with the card networks. Possible values:

1: Razorpay should save customer card details as tokens with the card networks. This will work only if explicit customer consent has been received from the customer.
0: Razorpay should not save the card details.

card mandatory : The details of the card that should be entered while making the payment. number : string Unformatted card number. name : string The name of the cardholder. expiry_month : string Expiry month for card in MM format. expiry_year : string Expiry year for card in YY format. cvv : string The card’s CVV number.

Handy Tips

CVV is not required by default for tokenised cards across all networks.
CVV is optional for tokenised card payments. Do not pass dummy CVV values.
To implement this change, skip passing the cvv parameter entirely, or pass a null or empty value in the CVV field.
We recommend removing the CVV field from your checkout UI/UX for tokenised cards.
If CVV is still collected for tokenised cards and the customer enters a CVV, pass the entered CVV value to Razorpay.

customer_id mandatory : string Unique identifier of the customer. This can be obtained from the response of the previous step.

2.3 Fetch all Tokens of Customer

Fetch all tokens created for a customer using the API given below. /customers/:customer_id/tokens

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/customers/:customer_id/tokens
```php: PHP
$api = new Api($key_id, $secret);
$api->customer->fetch($customerId)->tokens()->all();
```python: Python 
import razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.all(customerId)
```javascript: Node.js
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })
instance.customers.fetchTokens(customerId)
```ruby: Ruby
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

Razorpay::Customer.fetch(customerId).fetchTokens
```java: Java 
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_DtHaBuooGHTuyZ";

List customer = instance.customers.fetchTokens(customerId);
```go: Go 
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token.All("", nil, nil)
```json: Response
{
  "entity" : "collection",
  "count" : 2,
  "items" : [
    {
      "id" : "token_4lsdksD31GaZ09",
      "entity" : "token",
      "method" : "card",
      "card" : {
        "entity" : "card",
        "last4" : 1111,
        "network" : "Visa",
        "emi" : true,
        "issuer" : "HDFC",
        "international": false,
        "sub_type": "consumer",
        "token_iin": "453335",
        "type": "credit"
      },
      "used_at" : 1473765044,
      "created_at" : 1473765044,
      "status": "active",
      "compliant_with_tokenisation_guidelines": true  // This is for Indian Cards only
    },
    {
      "id" : "token_4lsdksD31GaZ08",
      "entity" : "token",
      "method" : "card",
      "card" : {
        "entity" : "card",
        "last4" : 1111,
        "network" : "Visa",
        "emi" : true,
        "issuer" : "HDFC",
        "international": false,
        "sub_type": "consumer",
        "token_iin": "453325",
        "type": "credit"
      },
      "used_at" : 1473765044,
      "created_at" : 1473765044,
      "status": "active",
      "compliant_with_tokenisation_guidelines": true // This is for Indian Cards only
    }
  ]
}

Path Parameter

customer_id : string Unique identifier of the customer.

Response Parameters

id : string The unique identifier of the Razorpay token. entity : string The name of the entity. Here, it is token. method : string The type of saved instrument. In the current use case, the value is card. card : object The customer card details. last4 : string The last 4 digits of the tokenised card. network : string The card network. Possible values:

Visa
RuPay
MasterCard
American Express
Diners Club
Maestro
JCB
Union Pay

issuer : string The 4-character issuer code unique to each issuing bank in India. For example, HDFC, SBIN and so on. type : string The type of card. Possible values:

credit
debit
prepaid

international : boolean Indicates whether the card is international (issued outside India) or domestic. Possible values:

true: The card is international.
false: The card is domestic.

emi : boolean Indicates whether the card is eligible for EMI payments or not. Possible values:

true: The card is eligible for EMI payments.
false: The card is not eligible for EMI payments.

sub_type : string The card sub_type for the given IIN. Pricing of card payment may change on the basis of card type. Possible values:

consumer
business
unknown

compliant_with_tokenisation_guidelines : boolean Indicates whether the token is compliant with the RBI guidelines. Possible values:

true: The token is compliant with RBI guidelines.
false: The token is not compliant with RBI guidelines.

status : string The overall status for the token. Possible values:

initiated: The token attains this state after Razorpay has received the tokenisation request and is working with token service providers for creating the token.
active: The token attains this state if the token is activated for at least one of the token service providers.
suspended: The token attains this state if:
The token is not activated for any one of the token service providers.
The token is suspended for at least one of the token service providers.
- deactivated: The token attains this state if the token is not active/suspended for any one of the token service providers and is deactivated for at least one token service provider. Know about the complete list of token states.

2.4 Fetch Card Properties of an Existing Token

Use this API to retrieve card details such as network, issuer and so on for a given token. /customers/:customer_id/tokens/:token_id

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X GET https://api.razorpay.com/v1/customers/:customer_id/tokens/:token_id

```java: Java
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_DtHaBuooGHTuyZ";

String tokenId = "token_HouA2OQR5Z2jTL";

Customer customer = razorpay.customers.fetchToken(customerId, tokenId)

```Python: Python
import razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.fetch(customerId, tokenId)

```php: PHP
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->fetch($tokenId);

```ruby: Ruby
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

Razorpay::Customer.fetch(customerId).fetchToken(tokenId)

```javascript: Node.js
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.fetchToken(customerId, tokenId)

```go: Go
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token.Fetch("", "", nil, nil)

```json: Response
{
  "id": "token_4lsdksD31GaZ09",
  "entity": "token",
  "method": "card",
  "card": {
    "entity": "card",
    "last4": 0153,
    "network": "Visa",
    "emi": true,
    "issuer": "HDFC",
    "international": false,
    "sub_type": "consumer",
    "token_iin": "453335",
    "type": "credit"
  },
  "used_at": 1473765044,
  "created_at": 1473765044,
  "status": "active",
  "compliant_with_tokenisation_guidelines": true  // This is for Indian Cards only
}

Path Parameter

customer_id : string Unique identifier of the customer. token_id : string Unique identifier of the token.

Response Parameters

Visa
RuPay
MasterCard
American Express
Diners Club
Maestro
JCB
Union Pay

issuer : string The 4-character issuer code unique to each issuing bank in India. For example, HDFC, SBIN and so on. type : string The type of card. Possible values:

credit
debit
prepaid

international : boolean Indicates whether the card is international (issued outside India) or domestic. Possible values:

true: The card is international.
false: The card is domestic.

emi : boolean Indicates whether the card is eligible for EMI payments or not. Possible values:

true: The card is eligible for EMI payments.
false: The card is not eligible for EMI payments.

sub_type : string The card sub_type for the given IIN. Pricing of card payment may change on the basis of card type. Possible values:

consumer
business
unknown

compliant_with_tokenisation_guidelines : boolean Indicates whether the token is compliant with the RBI guidelines. Possible values:

true: The token is compliant with RBI guidelines.
false: The token is not compliant with RBI guidelines.

status : string The overall status for the token. Possible values:

initiated: The token attains this state after Razorpay has received the tokenisation request and is working with token service providers for creating the token.
active: The token attains this state if the token is activated for at least one of the token service providers.
suspended: The token attains this state if:
The token is not activated for any one of the token service providers.
The token is suspended for at least one of the token service providers.
- deactivated: The token attains this state if the token is not active/suspended for any one of the token service providers and is deactivated for at least one token service provider. Know about the complete list of token states.

2.5 Create Payments Using Saved Card

After the card is saved, customers can quickly complete the payment for every subsequent online transaction by entering only the cvv.

Custom Checkout

  Pay
  
       var razorpay = new Razorpay({
        key: "",
        image: "https://i.imgur.com/n5tjHFD.jpg",
        name: "Crime Master Gogo",
       });
       var data = {
        amount: 6666,
        currency: "INR",
        email: "gaurav.kumar@example.com",
        order_id: "order_ISsp1ekSCHgoAw",
        contact: 9123456780,
        notes: {
          address: "Ground Floor, SJR Cyber, Laskar Hosur Road, Bengaluru",
        },
        customer_id: "cust_1Aa00000000001",
        token: "token_4zwefDSCC829ma",
        method: "card",
        card[cvv]: '123'
       };

       document.getElementById("rzp-button1").onclick = function(){
        razorpay.createPayment(data);
        razorpay.on("payment.success", function(resp) {
          alert(resp.razorpay_payment_id)
          });
        razorpay.on("payment.error", function(resp){alert(resp.error.description)});
}

Request Parameters

customer_id : string Unique identifier of the customer. token : string Unique identifier of the token saved with the card networks. card[cvv] : string CVV of the card.

Handy Tips

CVV is not required by default for tokenised cards across all networks.
CVV is optional for tokenised card payments. Do not pass dummy CVV values.
To implement this change, skip passing the cvv parameter entirely, or pass a null or empty value in the CVV field.
We recommend removing the CVV field from your checkout UI/UX for tokenised cards.
If CVV is still collected for tokenised cards and the customer enters a CVV, pass the entered CVV value to Razorpay.

2.6 Delete Tokens

If the customers want to remove the saved cards from their respective accounts, use the following API to delete the tokens. /customers/:customer_id/tokens/:token_id

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X DELETE https://api.razorpay.com/v1/customers/cust_1Aa00000000001/tokens/token_4zwefDSCC829ma

```java: Java
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

String customerId = "cust_DtHaBuooGHTuyZ";

String tokenId = "token_HouA2OQR5Z2jTL";

Customer customer = razorpay.customers.deleteToken(customerId, tokenId);

```Python: Python
import razorpay
client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

client.token.delete(customerId, tokenId)

```php: PHP
$api = new Api($key_id, $secret);

$api->customer->fetch($customerId)->tokens()->delete($tokenId);

```ruby: Ruby
require "razorpay"
Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

customerId = "cust_1Aa00000000004"

tokenId = "token_Hxe0skTXLeg9pF"

Razorpay::fetch(customerId).deleteToken(tokenId)

```javascript: Node.js
var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

instance.customers.deleteToken(customerId, tokenId)

```go: Go
import ( razorpay "github.com/razorpay/razorpay-go" )
client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

body, err := client.Token.Delete("", "", nil, nil)

```json: Response
{
    "deleted": true
}

Path Parameters

customer_id : string Unique identifier of the customer. token : string Token of the saved method that needs to be deleted.

Delete Saved Card Details

Customers can delete their card details. Check this demo and follow the on-screen instructions.

Existing Saved Card

Existing cards are those cards whose details are saved with Razorpay on Razorpay servers.
Razorpay saves the existing card details as network tokens if the customer provides explicit consent.
The businesses signify customer consent by sending the consent_to_save_card=1 parameter in the Create Payment request.

Handy Tips

To save the card details, you must share consent_to_save_card=1 till 30 June 2022. You do not need to send it from 01 July 2022 onwards.
If you share consent_to_save_card=0, Razorpay will not save cards. You do not need to send it from 01 July 2022 onwards.
If the customer does not provide consent, the card details are not saved.

Handy Tips

The existing card details are saved as network tokens whether the Collect Consent from Customers feature is enabled on the Dashboard or not, provided consent_to_save_card=1. Given below is the sample code:

Custom Checkout

  Pay
  
       var razorpay = new Razorpay({
        key: "",
        image: "https://i.imgur.com/n5tjHFD.jpg",
        name: "Gaurav Kumar",
       });
       var data = {
        amount: 6666,
        currency: "INR",
        email: "gaurav.kumar@example.com",
        order_id: "order_ISsp1ekSCHgoAw",
        contact: 9123456780,
        notes: {
          address: "Ground Floor, SJR Cyber, Laskar Hosur Road, Bengaluru",
        },
        customer_id: "cust_1Aa00000000001",
        token: "token_4zwefDSCC829ma",
        method: "card",
        card[cvv]: '123',
        consent_to_save_card: 1
       };

       document.getElementById("rzp-button1").onclick = function(){
        razorpay.createPayment(data);
        razorpay.on("payment.success", function(resp) {
          alert(resp.razorpay_payment_id)
          });
        razorpay.on("payment.error", function(resp){alert(resp.error.description)});
}

​New Card Workflow

​1. Checkout UI

​2. Integration Code

​2.1 Create a Customer

​2.2 Create Payment

​Request Parameters

​2.3 Fetch all Tokens of Customer

​Path Parameter

​Response Parameters

​2.4 Fetch Card Properties of an Existing Token

​Path Parameter

​Response Parameters

​2.5 Create Payments Using Saved Card

​Request Parameters

​2.6 Delete Tokens

​Path Parameters

​Delete Saved Card Details

​Existing Saved Card

New Card Workflow

1. Checkout UI

2. Integration Code

2.1 Create a Customer

2.2 Create Payment

Request Parameters

2.3 Fetch all Tokens of Customer

Path Parameter

Response Parameters

2.4 Fetch Card Properties of an Existing Token

Path Parameter

Response Parameters

2.5 Create Payments Using Saved Card

Request Parameters

2.6 Delete Tokens

Path Parameters

Delete Saved Card Details

Existing Saved Card