Token Sharing for Partner Auth Model

Provide a superior card payments experience to customers using the Token Sharing feature available under Partner Auth model.


According to new

, businesses cannot save their customer's card credentials (card number and other card data) on their own servers.

Razorpay has introduced an end-to-end RBI-compliant solution,

, that allows you to save customer credentials as tokens with card networks and card-issuing banks. Customers can then make repeat purchases on your website without re-entering card details.

  • If you are a single legal entity with multiple businesses, you can get onboarded as a Razorpay partner. For example, consider Acme Corp as a legal entity which runs the businesses Acme Groceries, Acme Fashions and Acme Beauty. All these businesses will have unique Razorpay merchant identifiers (MIDs).

  • Currently, if a customer makes an online purchase from Acme Groceries, they would need to enter their card details. If they want to purchase form Acme Fashions, the customer will have to re-enter their card details, though both Acme Groceries and Acme Fashions belong to the same main entity, Acme Corp.

  • With Razorpay's Token Sharing feature, while each business under your entity will have a unique MID to accept payments, tokens issued under any one MID will be automatically shared across all MIDs under that entity.

  • This means that if a customer has made a card payment to Acme Beauty, they need not enter their card details to make a payment at Acme Fashions or Acme Groceries. By saving the customer's card details as a token, you can provide them a smooth payment experience on subsequent transactions.

Handy Tips

  • Token sharing is only possible if you have multiple lines of businesses under the same legal entity. For example, ABC corp can be operating through 3 business lines under the one legal entity of ABC corp. Then, ABC corp can share a token and use it for processing payments for any of its MIDs with Razorpay.
  • Token Sharing between MIDs will not work if you wish to use another PA/PG as the token requestor.

Feature Enablement

This is an on-demand feature that is available only to businesses that operate through multiple lines of businesses under a single legal entity.

with us to get this feature enabled on your account.

You need to create tokens and accept payments from customers as a parent merchant on behalf of your sub-merchants. Razorpay TokenHQ helps you create, manage and use tokens for sub-merchants' payments.

Token Sharing Model

A token goes through various states in its lifecycle.

Handy Tips

  • Status will be available for the service provider token and the overall token entity.
  • The status of overall token entity is derived from the individual service provider tokens.
  • You may choose to consume the status of either the overall token entity or the individual service provider token, based on your integration.

Given below is a diagram representing the token lifecycle:

Token Lifecycle

A token can have following statuses:

StatusDescription
initiatedThis is the token's primary state. This status indicates that Razorpay is working with token service providers to create the token. It may take a few seconds for the token to move to the active state.
activeThe token reaches the active state when the token is successfully created and activated by a token service provider, that is, card networks. A token in active status can be used for payment processing.
suspendedThe status changes to suspended when the token is suspended temporarily by the card issuing bank or network. A suspended token may become active later. A suspended token cannot be used for payment processing.
failedThe token status changes to failed when Razorpay fails to create the token with the token service providers due to:
  • The card not being eligible.
  • The issue not being supported.
  • An invalid card number.
deactivatedStatus will be deactivated when:
  • The token has expired.
  • The token is deactivated by the bank.

A deactivated token cannot become active again, and cannot be used for payment processing.

In this flow, you are onboarded with card networks and Issuers as token requestors as well as a merchant. This requires PCI compliance.

Use this API to create a token using customer card details, on behalf of a sub-merchant.

POST
/tokens
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X POST https://api.razorpay.com/v1/tokens
-H "content-type: application/json"
-d'{
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"number": "4111111111111111",
"cvv": "123",
"expiry_month": "12",
"expiry_year": "21",
"name": "Gaurav Kumar"
},
"authentication": {
"provider": "razorpay",
"provider_reference_id": "pay_123wkejnsakd",
"authentication_reference_number": "100222021120200000000742753928"
},
"notes": []
}'

customer_id

optional

string The unique identifier of the customer created using

.

method

mandatory

string The type of object that needs to be tokenised. Currently, card is the only supported value.

card

mandatory

object The card details.

number

string The card number. If the card number has spaces, it will be trimmed by Razorpay for further processing.

cvv

string The card CVV.

Handy Tips

  • CVV is not required by default for Visa and Amex tokenised cards.
  • To enable CVV-less flow for Rupay and MasterCard, contact our .
  • CVV is mandatory for Diners tokenised cards.
  • CVV is an optional field. Skip passing the cvv parameter to Razorpay to implement this change.

expiry_month

string The card expiry month in mm format.

expiry_year

string The card expiry year in yy or yyyy format.

name

string The cardholder's name.

authentication

object Token authentication details.

provider

string The platform through which authentication was processed. Possible values:

  • amex
  • axis_migs
  • cashfree
  • ccavenue
  • cybersource
  • first_data
  • fss
  • hdfc
  • mpgs
  • paysecure
  • paytm
  • payu
  • zakpay

provider_reference_id

string The unique payment identifier of the payment used to collect AFA on any PA/PG.

authentication_reference_number

conditional

string A unique reference number generated when authentication is initiated. The maximum length supported is 26 characters. This field is mandatory for RuPay cards only after June 30, 2022.

Watch Out!

For tokenising RuPay cards, you will need to provide the authRefNo provided by NPCI during the payment where AFA was collected from card_holder for tokenising the card. The validity of authRefNo is up to a few minutes.

Use this API to initiate payment on behalf of a sub-merchant.

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": 500000,
"currency": "INR",
"email": "gaurav.kumar@example.com",
"order_id": "order_Fg6IGePNMKDICF",
"contact": "9090909090",
"method": "card",
"token": "token_IJr7WSRFECVBSX",
"customer_id": "cust_K3ZhflPARDyCf3",
"card": {
"cvv": "123"
},
"ip": "192.168.0.103",
"user_agent": "Mozilla/5.0",
"description": "Test payment",
"notes": {
"note_key": "value1"
},
"account_id": "acc_Ef7ArAsdU5t0XM"
}'

key_id

mandatory

string API Key ID that must generated from Razorpay DashboardSettingsAPI Keys.

amount

mandatory

integer The amount to be paid by the customer in currency subunits. For example, if the amount is ₹100, enter 10000.

currency

mandatory

string The currency in which the payment should be made by the customer. See the list of

.

order_id

mandatory

string Order ID generated via

.

email

mandatory

string Email address of the customer.

contact

mandatory

string Phone number of the customer.

method

mandatory

string Name of the payment method. Possible values are:

card

The details of the card that should be entered while making the payment.

number

mandatory if method=card/emi

integer Unformatted card number.

name

mandatory if method=card/emi

string The name of the cardholder.

expiry_month

mandatory if method=card/emi

integer Expiry month for card in MM format.

expiry_year

mandatory if method=card/emi

integer Expiry year for card in YY format.

cvv

mandatory if method=card/emi

integer CVV printed on the back of the card.

Handy Tips

  • CVV is not required by default for Visa and Amex tokenised cards.
  • To enable CVV-less flow for Rupay and MasterCard, contact our .
  • CVV is mandatory for Diners tokenised cards.
  • CVV is an optional field. Skip passing the cvv parameter to Razorpay to implement this change.

emi_duration

mandatory if method=card/emi

integer Defines the number of months in the EMI plan.

bank

mandatory if method=netbanking

string Bank code. List of available banks enabled for your account can be fetched via

.

bank_account

mandatory if method=emandate

The details of the bank account that should be passed in the request. Required if the method is emandate.

account_number

mandatory if method=emandate

string Bank account number used to initiate the payment.

ifsc

mandatory if method=emandate

string IFSC of the bank used to initiate the payment.

name

mandatory if method=emandate

string Name associated with the bank account used to initiate the payment.

vpa

mandatory if method=upi

string UPI ID of the customer. Required if the method is upi.

wallet

mandatory if method=wallet

string Wallet code for the wallet used for the payment. Possible values:

provider

mandatory if method=cardless_emi

string Name of the cardless EMI provider partnered with Razorpay. Required if method is cardless_emi. Available options are:

  • barb
  • cshe
  • hdfc
  • icic
  • idfb
  • kkbk
  • krbe
  • zestmoney
  • earlysalary
  • tvsc
  • walnut369

notes

optional

object Set of key-value pairs that can be used to store additional information about the payment. It can hold a maximum of 15 key-value pairs, each 256 characters long (maximum).

callback_url

optional

string URL endpoint where Razorpay will submit the final payment status.

ip

optional

string Customer IP Address.

referrer

optional

string Customer referrer.

user_agent

optional

string Customer user-agent.

Use this API to delete a token.

POST
/tokens/delete
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X https://api.razorpay.com/v1/tokens/delete
-H "content-type: application/json"
-d '{
"id" : "token_4lsdksD31GaZ09"
}'

id

mandatory

string The unique identifier of the token to be deleted.

Watch Out!

Token deletion applies at a global level. That is, once you delete a token, you cannot use the token any longer under any of the MIDs.

Use this API to fetch the card properties of an existing token.

POST
/tokens/fetch
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X POST https://api.razorpay.com/v1/tokens/fetch
-H "content-type: application/json"
-d'{
"id": "token_4lsdksD31GaZ09"
}'

id

mandatory

string The unique identifier of the token whose details are to be fetched.

In this flow, you will be onboarded with card networks and Issuers as a merchant with Razorpay as the token requestor. You need not be PCI compliant for this solution.

You can create the token when your customer opts to save their card on your checkout during the first payment. As per RBI guidelines, you must collect customer consent to save their card.

Use the following API to save the customer card details and create a token.

  • Pass an additional field save=true to save and tokenise the card.
  • Pass the account_id of the sub-merchant in the payment request.
curl -u [CLIENT_ID]:[CLIENT_SECRET]
-X POST https://api.razorpay.com/v1/payments/create/json
-H "content-type: application/json"
-d '{
"amount": 500000,
"currency": "INR",
"order_id": "order_Fg6IGePNMKDICF",
"email": "gaurav.kumar@example.com",
"contact": "9090909090",
"method": "card",
"card": {
"number": "4854980604708430",
"cvv": "123",
"expiry_month": "12",
"expiry_year": "21",
"name": "Gaurav Kumar"
},
"save": true,
"ip": "192.168.0.103",
"user_agent": "Mozilla/5.0",
"description": "Test payment",
"notes": {
"note_key": "value1"
},
"account_id": "acc_Ef7ArAsdU5t0XM"
}'

Same as the request parameters for

.

Use this API to create a payment using an existing token.

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": 500000,
"currency": "INR",
"order_id": "order_Fg6IGePNMKDICF",
"email": "gaurav.kumar@example.com",
"contact": "9090909090",
"method": "card",
"token": "token_4lsdksD31GaZ09",
"customer_id": "cust_1Aa00000000001",
"card": {
"cvv": "123"
},
"ip": "192.168.0.103",
"user_agent": "Mozilla/5.0",
"description": "Test payment",
"notes": {
"note_key": "value1"
},
"account_id": "acc_Ef7ArAsdU5t0XM"
}'

token

mandatory

string Pass the unique token id created when the customer made the first payment.

account_id

mandatory

string Pass the sub-merchant's unique identifier.

Use this API to delete a token.

POST
/tokens/delete
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X https://api.razorpay.com/v1/tokens/delete
-H "content-type: application/json"
-d '{
"id" : "token_4lsdksD31GaZ09"
}'

token

mandatory

string Pass the unique identifier of the token to be deleted.

Use this API to fetch the card properties of an existing token.

POST
/tokens/fetch
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X POST https://api.razorpay.com/v1/tokens/fetch
-H "content-type: application/json"
-d'{
"id": "token_4lsdksD31GaZ09"
}'

token

mandatory

string Pass the unique identifier of the token whose details are to be fetched.

Use Razorpay Webhooks to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send an HTTP POST payload in JSON to the webhook's configured URL.

The table below lists the Webhook events available for tokens.

EventDescription
token.initiatedTriggered when the tokenisation request is initiated.
token.activatedTriggered when:
  • The token status is changed to active for the first time.
  • The token status for a previously suspended token is changed to active again.
token.suspendedTriggered when the issuing bank temporarily suspends a token.
token.deactivatedTriggered when the token is permanently deactivated.
token.expiry_updatedTriggered when the issuing bank updates the expiry date for a token.

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.initiated",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "initiated",
"notes": []
}
}
}
}

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.activated",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "active",
"notes": []
}
}
}
}

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.activated",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "active",
"notes": []
}
},
"payment": {
"entity": {
"id": "pay_FPoJKWQQ8lK13n",
"entity": "payment",
"amount": 500000,
"currency": "INR",
"base_amount": 500000,
"status": "captured",
"order_id": "order_FPoIeimWki9j8A",
"invoice_id": null,
"international": false,
"method": "netbanking",
"amount_refunded": 190000,
"amount_transferred": 0,
"refund_status": "partial",
"captured": true,
"description": null,
"card_id": null,
"bank": "HDFC",
"wallet": null,
"vpa": null,
"email": "gaurav.kumar@example.com",
"contact": "+919000090000",
"notes": [],
"fee": 11800,
"tax": 1800,
"error_code": null,
"error_description": null,
"error_source": null,
"error_step": null,
"error_reason": null,
"acquirer_data": {
"bank_transaction_id": "4827433"
},
"created_at": 1597226379
}
}
}
}

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.suspended",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "suspended",
"notes": []
}
}
}
}

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.deactivated",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "deactivated",
"notes": []
}
}
}
}

{
"entity": "event",
"account_id": "acc_BFQ7uQEaa7j2z7",
"event": "token.expiry_updated",
"contains": [
"token"
],
"payload": {
"token": {
"entity": {
"id": "token_4lsdksD31GaZ09",
"entity": "token",
"customer_id": "cust_1Aa00000000001",
"method": "card",
"card": {
"last4": "3335",
"network": "Visa",
"type": "debit",
"issuer": "HDFC",
"international": false,
"emi": true,
"sub_type": "consumer",
"token_iin": "453335"
},
"compliant_with_tokenisation_guidelines": true,
"expired_at": 1748716199,
"status": "active",
"notes": []
}
}
}
}

Not necessarily. If you wish to be the token requestor (to create and store tokens), then yes, you will require PCI compliance. If Razorpay is the token requestor, compliance is not required.

No, tokens cannot be shared within MIDs with another PA/PG as the token requestor.

No, token creation and payment initiation has to be with Razorpay.

No, this feature will be enabled only upon request and is subject to the following conditions:

  • You are a Razorpay partner under the Partner Auth model.
  • You are a single legal entity that operates with multiple sub-merchants with unique Razorapy MIDs.

Get in

to get this feature enabled on your account.

Yes, you can migrate to the partnership model without any integration effort. We would recommend that you get in touch with your sales POC to assist you with the token migration process.


Was this page helpful?