Skip to main content
PATCH
Available in🇮🇳 India
Use this endpoint to update an account with the information a requirement asks for.
Handy Tips
  • Authenticate with the key and secret of your test pair or live pair. In the API playground, enter the test key as the username and its secret as the password. Use the live pair in live mode.
  • Every top-level body field is optional in this call. Send what the product’s requirements list, and only what is changing. Keyed objects (identity_numbers, documents, stakeholders and bank_accounts) merge by key. addresses merges by type.
  • business_category merges by attribute. Its business_model_clarifications merge by question ID. Any other node, such as a bank account, is replaced whole.
  • The response is the account, as Fetch Accounts returns it, within 3 sec. Writes to one account run one at a time, in the order they arrive.
  • A saved value that fails verification still returns 200. Its verification shows rejected with an error_code. Its requirement is due again.
  • A wrong One-Time Password (OTP) also returns 200, with the code still due.
  • A check still running shows verification.status as in_progress. Fetch the account or wait for the account.requirements.updated webhook.
Watch Out!
  • Sending products.<product_type>.terms_of_service_acceptance submits the product. Most products come back activated in the same response.
  • A product moves to under_review when a check was deferred or a review starts. It moves to edd_pending when video KYC is needed.
  • From submission on, the KYC details are locked: the business profile, the authorised person, the stakeholders and the bank account. Changing one returns 409 with field_locked.
  • During needs_clarification, only the fields in requirements can change. After activation, a few details can change after a manual review by Razorpay. Know more about account management.

Path Parameters

string
required
The unique identifier of the account, acc_-prefixed. For example, acc_TcdGEzmfKQzEl1.

Request Parameters

Every top-level body field is optional in this call. A field that a requirement lists is due before submission. A nested field marked required applies only when you send its parent object.
string
required
A unique key you generate for each write, 16-64 printable ASCII characters long. A Universally Unique Identifier (UUID) works. A retry with the same key within 24 h returns the original response instead of acting twice. Know more about idempotency.
object
The brand name customers see on their bank statements and receipts.
string
required
The brand name customers see on their bank statements and receipts, so they recognise the charge. Maximum length: 255 characters.
object
Corrects the owner’s email or phone while it is unverified.
string
The corrected email. Maximum length: 255 characters.
string
The corrected phone: +91 followed by 10 digits. Pattern: ^\+91[0-9]{10}$.
string
The code from send_phone_otp, which verifies the phone. A wrong code returns 200, and phone_otp stays due. An expired code or 3 wrong tries bring send_phone_otp back. Pattern: ^[0-9]{6}$.
string
The code from send_email_otp, which verifies the email. A wrong code returns 200, and email_otp stays due. An expired code or 3 wrong tries bring send_email_otp back. Pattern: ^[0-9]{6}$.
object
The business’s KYC identity on this account.
string
The legal form of the business. It decides which requirements apply and cannot change after the PAN is verified. Possible values:
  • individual: An individual without a registered business.
  • proprietorship: A sole proprietorship.
  • private_limited: A private limited company.
  • public_limited: A public limited company.
  • section_8_company: A not-for-profit company under Section 8 of the Companies Act.
  • llp: A limited liability partnership.
  • partnership: A partnership firm.
  • trust: A trust.
  • society: A registered society.
  • huf: A Hindu undivided family.
  • government: A government body or undertaking.
  • judicial_person: An artificial judicial person, such as a university or a fund.
  • local_authority: A local authority, such as a municipal corporation.
string
The legal name. For an individual, it comes from the verified PAN and cannot be set. A proprietorship sends the name it trades under.
string
The date the business was established. Format: YYYY-MM-DD.
object
Government identifiers keyed by type.
object
The PAN of the business.
string
The business PAN, 10 characters long: 5 letters, 4 digits and a letter.
object
The Goods and Services Tax Identification Number (GSTIN). One per account: the GSTIN this account trades under. A business registered for GST in several states sends the GSTIN for this account. It sends that registration’s address as operational_address.
string
The GSTIN of the business.
object
Udyam registration number.
string
The Udyam registration number of the business.
object
The Corporate Identification Number (CIN).
string
The CIN of the company.
object
The business’s KYC documents, keyed by document type. Attach each document by its id or url.
object
Business PAN.
object
Certificate of incorporation.
object
GST certificate.
object
Udyam registration certificate.
object
Shop and establishment certificate.
object
Any other document the business_documents requirement asks for, keyed by its type, such as fssai_certificate. Know more about document types.
string
The ID of a document uploaded with Upload a Document, once the account exists. Send either id or url.
string
A link Razorpay downloads the file from, in place of an upload. Send a pre-signed https link, valid for at least 15 min and never a public object. Razorpay downloads it once and keeps its own copy. Sending a link is coming soon. Until then, upload the file and send its id with Update an Account.
object
How the business is classified. Send the category and its subcategory together. Razorpay derives the Merchant Category Code (MCC) from the subcategory.
string
The business category, from the requirement’s options.
string
The subcategory of the category. Send it with category. Razorpay derives the mcc from it. Know more about business categories and subcategories.
string
The MCC. Razorpay derives it from the subcategory when you send the category and subcategory. Pattern: ^[0-9]{4}$.
string
What the business sells, such as Clothing and accessories for men, women and children, sold online. Maximum length: 100 characters.
object
Answers to the business-model questions, keyed by question ID. Know more about the business model questions.
object
One business-model question and its answer.
string
required
The question’s ID, the same as its key.
array
required
The answer. One value for single-select and text questions.
object
The person authorised to act for the business on this account. They need not hold a share of it. For an individual or a proprietor, this is the owner. Send the owner’s personal PAN at business_profile.authorized_person.identity_numbers.individual_pan. The business name comes from that PAN.
string
The person’s full name.
object
The person’s identifiers keyed by type.
object
The PAN of a person: the authorised person, a stakeholder, an individual or a proprietor.
string
The person’s PAN, 10 characters long: 5 letters, 4 digits and a letter.
object
The person’s Central KYC Records Registry (CKYC) record. Its value is null. Send the code from send_ckyc_otp in otp and its request ID in request_id.
boolean
Send true to skip the CKYC record. The proof of address is then due instead. Default: false.
string
The code that send_ckyc_otp sent to the mobile on the CKYC record. Send it with request_id. Responses do not return it. Pattern: ^[0-9]{6}$.
string
The request ID that came with the code, in the request_id output of send_ckyc_otp. Send it with otp. Responses do not return it.
object
The person’s KYC documents keyed by document type.
object
Personal PAN.
object
Aadhaar front.
object
Aadhaar back.
object
Passport front.
object
Passport back.
object
Voter ID front.
object
Voter ID back.
string
The ID of a document uploaded with Upload a Document, once the account exists. Send either id or url.
string
A link Razorpay downloads the file from, in place of an upload. Send a pre-signed https link, valid for at least 15 min and never a public object. Razorpay downloads it once and keeps its own copy. Sending a link is coming soon. Until then, upload the file and send its id with Update an Account.
object
The person’s own address.
string
required
First line of the address.
string
Second line of the address.
string
required
City or district.
string
required
State, as an ISO 3166-2 subdivision code such as KA.
string
required
The 6-digit PIN code. Pattern: ^[0-9]{6}$.
string
required
ISO 3166-1 alpha-2, for example IN.
string
The person’s date of birth. Format: YYYY-MM-DD.
object
Other attributes of the person, such as gender or title.
object
The business’s stakeholders, the people who hold a share of it, keyed by stakeholder ID. To add a stakeholder, use any new key.
object
A stakeholder: a person who holds a share of the business.
string
The person’s full name.
object
The person’s identifiers keyed by type.
object
The PAN of a person: the authorised person, a stakeholder, an individual or a proprietor.
string
The person’s PAN, 10 characters long: 5 letters, 4 digits and a letter.
object
The person’s KYC documents keyed by document type.
object
A KYC document of the stakeholder, keyed by its type, such as aadhaar_front.
string
The ID of a document uploaded with Upload a Document, once the account exists. Send either id or url.
string
A link Razorpay downloads the file from, in place of an upload. Send a pre-signed https link, valid for at least 15 min and never a public object. Razorpay downloads it once and keeps its own copy. Sending a link is coming soon. Until then, upload the file and send its id with Update an Account.
object
The person’s own address.
string
required
First line of the address.
string
Second line of the address.
string
required
City or district.
string
required
State, as an ISO 3166-2 subdivision code such as KA.
string
required
The 6-digit PIN code. Pattern: ^[0-9]{6}$.
string
required
ISO 3166-1 alpha-2, for example IN.
string
The person’s date of birth. Format: YYYY-MM-DD.
object
Other attributes of the person, such as gender or title.
number
required
Ownership as a decimal from 0 to 100. Send 25.5, not 25.5%.
array
The business’s addresses, one of each type. Razorpay merges the list by type, so an update sends only the address that changed, with its type.
string
required
Which address this is. Possible values:
  • registered_address: The registered business address. For an individual, Razorpay fills it from the CKYC record or the proof of address when you do not send it.
  • operational_address: Where the business operates for this account. One per account. With a GSTIN, it is the place of business on that GST registration.
string
required
First line of the address.
string
Second line of the address.
string
required
City or district.
string
required
State, as an ISO 3166-2 subdivision code such as KA.
string
required
The 6-digit PIN code. Pattern: ^[0-9]{6}$.
string
required
ISO 3166-1 alpha-2, for example IN.
object
Up to 15 key-value pairs for your own reference, such as your store ID, as in notes on other Razorpay entities. Razorpay does not read these.
string
The value under one key you choose. Maximum length: 256 characters.
object
The business’s bank accounts, keyed by purpose. settlements_primary receives settlements. A new account sent under the same key takes the old one’s place. Settlements move to it once it is verified.
object
The bank account that receives settlements.
string
required
The bank account number, 5 to 35 digits.
string
required
The bank’s routing code: the Indian Financial System Code (IFSC) in India, as in the Payouts APIs.
string
required
The kind of routing_code. Send it with every account number and routing code. Possible value: IFSC.
object
Optional. No requirement asks for it, since no document type is a bank proof.
string
The ID of a document uploaded with Upload a Document, once the account exists. Send either id or url.
string
A link Razorpay downloads the file from, in place of an upload. Send a pre-signed https link, valid for at least 15 min and never a public object. Razorpay downloads it once and keeps its own copy.
object
Changes to products, keyed by product type.
object
Changes to the payment_gateway product, which accepts payments on websites and apps.
object
The channels the business accepts payments on.
object
The business’s website.
string
The live website, on https. Razorpay checks liveness, content and MCC from it.
array
Other websites of the business.
object
The Android app.
string
The Play Store link.
object
The iOS app.
string
The App Store link.
object
The sub-merchant’s acceptance of Razorpay’s terms of service. Sending it submits the product. Show Razorpay’s terms of service to the sub-merchant and let the sub-merchant accept in your user interface. Then send the IP address and device fingerprint of that acceptance.
string
required
The IP address the sub-merchant accepted from.
string
required
The device fingerprint of the sub-merchant’s device.
object
The sub-merchant’s text replies to the points a reviewer flagged in needs_clarification. A point that takes a reply lists a clarify_… sub-requirement. Send each reply under the path of what it answers, which is that sub-requirement’s field_path without the products.payment_gateway.clarification_responses. prefix. For example, { "products": { "payment_gateway": { "clarification_responses": { "bank_accounts.settlements_primary": "…" } } } }. The account returns the replies in this field.
string
One reply, under the path of what it answers. Length: 50-300 characters.
boolean
Send true in a call of its own to return the product to review. Send it once every flagged point on this product is answered and submit_clarification is due.
object
Up to 15 key-value pairs for your own reference, such as your store ID, as in notes on other Razorpay entities. Razorpay does not read these.
string
The value of one note, under a key you choose. Maximum length: 256 characters.

Response Parameters

string
Unique identifier for the account, acc_-prefixed.
string
ISO 3166-1 alpha-2 country of the business, IN.
object
The brand name customers see on their bank statements and receipts, with its verification.
string
The brand name customers see on their bank statements and receipts, so they recognise the charge. Up to 255 characters.
object
The outcome of a verification check.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
Details of the statement descriptor. {} when it has none.
integer
Time at which the statement descriptor was added, as a Unix timestamp in seconds.
integer
Time at which the statement descriptor last changed, as a Unix timestamp in seconds.
boolean
Whether the owner must complete 2-factor authentication on the Razorpay Dashboard.
object
The user who creates and operates the account and signs in to the Razorpay Dashboard, returned with role as owner. This is the person behind the account, not the company’s owner. The email and phone belong to the user, not the account. One user can own several accounts.
string
The user’s role on the account. The user who creates the account is its owner. Do not send it in a request. Possible values:
  • owner
  • admin
string
The user’s email. Maximum length: 255 characters.
string
The user’s phone: +91 followed by 10 digits.
string
The name of the person completing the onboarding. Length: 2-127 characters.
boolean
Whether the user has verified the email with an OTP. Razorpay sends no OTP to a verified email.
boolean
Whether the user has verified the phone with an OTP. Razorpay sends no OTP to a verified phone.
object
The business’s KYC identity on this account.
string
The legal form of the business. It decides which requirements apply and cannot change after the PAN is verified. Possible values:
  • individual: An individual without a registered business.
  • proprietorship: A sole proprietorship.
  • private_limited: A private limited company.
  • public_limited: A public limited company.
  • section_8_company: A not-for-profit company under Section 8 of the Companies Act.
  • llp: A limited liability partnership.
  • partnership: A partnership firm.
  • trust: A trust.
  • society: A registered society.
  • huf: A Hindu undivided family.
  • government: A government body or undertaking.
  • judicial_person: An artificial judicial person, such as a university or a fund.
  • local_authority: A local authority, such as a municipal corporation.
string
The legal name. For an individual, it comes from the verified PAN and cannot be set. A proprietorship sends the name it trades under.
string
The date the business was established. Format: YYYY-MM-DD.
object
Government identifiers keyed by type.
object
One identifier and its verification, keyed by its type.
string
The kind of identifier, the same as its key. Possible values:
  • individual_pan: The PAN of a person: the authorised person, a stakeholder, an individual or a proprietor.
  • business_pan: The PAN of the business.
  • gstin: The GSTIN. One per account: the GSTIN this account trades under. A business registered for GST in several states sends the GSTIN for this account. It sends that registration’s address as operational_address.
  • udyam_registration: Udyam registration number.
  • cin: The CIN.
  • individual_ckyc: The person’s CKYC record. Its value is null. Send the code from send_ckyc_otp in otp and its request ID in request_id.
string
The identifier, as sent. null for individual_ckyc.
object
The outcome of a verification check.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
Details of the identifier. For individual_ckyc, it holds ckyc_mobile, the mobile on the CKYC record.
boolean
Whether the sub-merchant chose to skip this identifier, such as the CKYC record.
integer
Time at which the identifier was added, as a Unix timestamp in seconds.
integer
Time at which the identifier last changed, as a Unix timestamp in seconds.
object
The business’s KYC documents, keyed by document type. Attach each document by its id or url.
object
One KYC document, keyed by its type. Know more about the Document entity.
object
How the business is classified. Razorpay derives the MCC from the subcategory.
string
The business category, from the requirement’s options.
string
The subcategory of the category. Send it with category. Razorpay derives the mcc from it. Know more about business categories and subcategories.
string
The MCC. Razorpay derives it from the subcategory when you send the category and subcategory.
string
What the business sells, such as Clothing and accessories for men, women and children, sold online. Maximum length: 100 characters.
object
Answers to the business-model questions, keyed by question ID. Know more about the business model questions.
object
One business-model question and its answer.
string
The question’s ID, the same as its key.
string
The question text.
array
The allowed answers.
string
The text to show.
string
The value to send.
string
How the question is answered. Possible values:
  • single_select
  • multi_select
  • free_text
array
The answer. One value for single-select and text questions.
object
The person authorised to act for the business on this account. They need not hold a share of it. For an individual or a proprietor, this is the owner. Send the owner’s personal PAN at business_profile.authorized_person.identity_numbers.individual_pan. The business name comes from that PAN.
string
The person’s full name.
object
The person’s identifiers keyed by type.
object
One identifier and its verification, keyed by its type.
string
The kind of identifier, the same as its key. Possible values:
  • individual_pan: The PAN of a person: the authorised person, a stakeholder, an individual or a proprietor.
  • business_pan: The PAN of the business.
  • gstin: The GSTIN. One per account: the GSTIN this account trades under. A business registered for GST in several states sends the GSTIN for this account. It sends that registration’s address as operational_address.
  • udyam_registration: Udyam registration number.
  • cin: The CIN.
  • individual_ckyc: The person’s CKYC record. Its value is null. Send the code from send_ckyc_otp in otp and its request ID in request_id.
string
The identifier, as sent. null for individual_ckyc.
object
The outcome of a verification check.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
Details of the identifier. For individual_ckyc, it holds ckyc_mobile, the mobile on the CKYC record.
boolean
Whether the sub-merchant chose to skip this identifier, such as the CKYC record.
integer
Time at which the identifier was added, as a Unix timestamp in seconds.
integer
Time at which the identifier last changed, as a Unix timestamp in seconds.
object
The person’s KYC documents keyed by document type.
object
One KYC document, keyed by its type. Know more about the Document entity.
object
The person’s own address. It is null unless you sent it.
string
Which address this is, the same as its key. Possible values:
  • registered_address: The registered business address. For an individual, Razorpay fills it from the CKYC record or the proof of address when you do not send it.
  • operational_address: Where the business operates for this account. One per account. With a GSTIN, it is the place of business on that GST registration.
string
First line of the address.
string
Second line of the address.
string
City or district.
string
State, as an ISO 3166-2 subdivision code such as KA.
string
The 6-digit PIN code.
string
ISO 3166-1 alpha-2, for example IN.
string
The person’s date of birth. It is null unless you sent it. Format: YYYY-MM-DD.
object
Other attributes of the person, such as gender or title. {} when the person has none.
integer
Time at which the person was added, as a Unix timestamp in seconds.
integer
Time at which the person last changed, as a Unix timestamp in seconds.
object
The business’s stakeholders, the people who hold a share of it, keyed by stakeholder ID. To add a stakeholder, use any new key.
object
A stakeholder: a person who holds a share of the business.
string
The person’s full name.
object
The person’s identifiers keyed by type.
object
One identifier and its verification, keyed by its type.
string
The kind of identifier, the same as its key. Possible values:
  • individual_pan: The PAN of a person: the authorised person, a stakeholder, an individual or a proprietor.
  • business_pan: The PAN of the business.
  • gstin: The GSTIN. One per account: the GSTIN this account trades under. A business registered for GST in several states sends the GSTIN for this account. It sends that registration’s address as operational_address.
  • udyam_registration: Udyam registration number.
  • cin: The CIN.
  • individual_ckyc: The person’s CKYC record. Its value is null. Send the code from send_ckyc_otp in otp and its request ID in request_id.
string
The identifier, as sent. null for individual_ckyc.
object
The outcome of a verification check.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
Details of the identifier. For individual_ckyc, it holds ckyc_mobile, the mobile on the CKYC record.
boolean
Whether the sub-merchant chose to skip this identifier, such as the CKYC record.
integer
Time at which the identifier was added, as a Unix timestamp in seconds.
integer
Time at which the identifier last changed, as a Unix timestamp in seconds.
object
The person’s KYC documents keyed by document type.
object
One KYC document, keyed by its type. Know more about the Document entity.
object
The person’s own address. It is null unless you sent it.
string
Which address this is, the same as its key. Possible values:
  • registered_address: The registered business address. For an individual, Razorpay fills it from the CKYC record or the proof of address when you do not send it.
  • operational_address: Where the business operates for this account. One per account. With a GSTIN, it is the place of business on that GST registration.
string
First line of the address.
string
Second line of the address.
string
City or district.
string
State, as an ISO 3166-2 subdivision code such as KA.
string
The 6-digit PIN code.
string
ISO 3166-1 alpha-2, for example IN.
string
The person’s date of birth. It is null unless you sent it. Format: YYYY-MM-DD.
object
Other attributes of the person, such as gender or title. {} when the person has none.
integer
Time at which the person was added, as a Unix timestamp in seconds.
integer
Time at which the person last changed, as a Unix timestamp in seconds.
number
Ownership as a decimal from 0 to 100. Send 25.5, not 25.5%.
array
The business’s addresses, one of each type. Razorpay merges the list by type, so an update sends only the address that changed, with its type.
string
Which address this is. Possible values:
  • registered_address: The registered business address. For an individual, Razorpay fills it from the CKYC record or the proof of address when you do not send it.
  • operational_address: Where the business operates for this account. One per account. With a GSTIN, it is the place of business on that GST registration.
string
First line of the address.
string
Second line of the address.
string
City or district.
string
State, as an ISO 3166-2 subdivision code such as KA.
string
The 6-digit PIN code.
string
ISO 3166-1 alpha-2, for example IN.
object
Up to 15 key-value pairs for your own reference, such as your store ID, as in notes on other Razorpay entities. Razorpay does not read these.
string
The value under one key you chose. Maximum length: 256 characters.
object
The account’s bank accounts, keyed by purpose. settlements_primary receives settlements.
object
One bank account and its verification, keyed by its purpose. The only key is settlements_primary.
string
The purpose of the bank account, the same as its key. Possible value: settlements_primary.
string
The bank account number, 5 to 35 digits.
string
The bank’s routing code: the IFSC in India, as in the Payouts APIs.
string
The kind of routing_code. Send it with every account number and routing code. Possible value: IFSC.
object
Optional. It is null unless a document is attached. No requirement asks for it, since no document type is a bank proof. Know more about the Document entity.
object
The outcome of a verification check.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
The products the account holds, keyed by product type, such as payment_gateway.
object
One product, keyed by its type, with its status and the requirements still due.
string
A Razorpay product, the same as its key. payment_gateway accepts payments on websites and apps. Possible values:
  • payment_gateway
  • pos
  • billing
  • business_banking
  • payroll
  • agent_studio
  • optimizer
string
Where the product is in onboarding. Activation needs the business’s KYC verified and the product’s own checks passed, such as the subcategory and any website sent. Razorpay checks the website again every year. Possible values:
  • created: The product is on the account. Nothing is submitted yet.
  • in_progress: Information is being collected.
  • under_review: Submitted. Razorpay is reviewing it. The KYC details are locked.
  • needs_clarification: A reviewer asked for clarification. Only the requirements listed can change.
  • edd_pending: Submitted. Razorpay needs enhanced due diligence first, usually a video KYC call because no CKYC record exists. The requirements hold create_video_kyc_link. The KYC details are locked.
  • activated: The product is live. Live payments API keys are available.
  • rejected: Razorpay rejected the application. status_reason says why. Razorpay accepts no further changes.
  • suspended: Suspended after activation, for example when the yearly website check fails and is not resolved. status_reason says why. requirements lists what would resolve it.
object
Why the product is rejected or suspended. It is null in every other status. Branch on code and show description.
string
A stable code for the reason. Possible values:
  • category_not_allowed: Rejected: what the business sells is on Razorpay’s restricted list.
  • clarification_not_answered: Rejected: a reviewer’s clarification was not answered in time.
  • identity_not_verified: Rejected: the owner or signatory could not be verified, for example after failed video KYC calls.
  • risk_review_failed: Rejected or suspended after Razorpay’s risk review. It never says which check failed, because Razorpay does not disclose screening outcomes.
  • website_review_failed: Suspended: the yearly website check failed and was not resolved.
string
A sentence to show the sub-merchant. The wording can change.
integer
Time at which the product was requested, as a Unix timestamp in seconds.
integer
Time at which the product last changed, as a Unix timestamp in seconds.
array
The information still due for this product, in any status, computed on every request. [] when nothing is due. Know more about the Requirement entity.
object
The sub-merchant’s acceptance of Razorpay’s terms of service, as Razorpay recorded it. Razorpay keeps the full record for at least 5 years after the account closes. Razorpay returns only these fields.
string
The IP address the sub-merchant accepted from.
string
The device fingerprint of the sub-merchant’s device.
object
Details of the acceptance. {} when the acceptance has none.
integer
Time at which the sub-merchant accepted, as a Unix timestamp in seconds.
object
For payment_gateway: the channels the business accepts payments on.
object
The business’s website.
string
The live website, on https. Razorpay checks liveness, content and MCC from it.
array
Other websites of the business.
object
The website check. It is null until the check starts, then in_progress. It ends as verified or as rejected with website_unreachable.
string
Where the check is. Possible values:
  • in_progress: The check is running.
  • deferred: The check could not conclude, so a reviewer decides after the product is submitted. The requirement clears and error_code is null.
  • verified: The check passed.
  • rejected: The check failed. error_code says why.
  • collected: Razorpay has received the value and has not checked it yet.
string
A stable code for the failure, such as bank_name_mismatch, pan_not_found or otp_invalid. Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match. Know more about failed-check codes.
string
A sentence to show the sub-merchant. The wording can change. It never repeats the value sent.
integer
Time at which the check passed, as a Unix timestamp in seconds.
object
Details of the check, where it has any. {} when the check has none.
integer
Time at which the check started, as a Unix timestamp in seconds.
object
The Android app.
string
The Play Store link.
object
The iOS app.
string
The App Store link.
object
The sub-merchant’s text replies to the points a reviewer flagged in needs_clarification. Each reply is keyed by the path of what it answers, such as bank_accounts.settlements_primary.
string
One reply, under the path of what it answers.
object
Up to 15 key-value pairs for your own reference, such as your store ID, as in notes on other Razorpay entities. Razorpay does not read these.
string
The value of one note, under a key you chose. Maximum length: 256 characters.
integer
Time at which the account was created, as a Unix timestamp in seconds.
integer
Time at which the account last changed, as a Unix timestamp in seconds.

Errors

Code: 400Reason: missing_headerX-Idempotency-Key is missing or is not 16-64 printable ASCII characters.Solution: Send X-Idempotency-Key with 16-64 printable ASCII characters. metadata.header names the header.
Code: 400Reason: invalid_requestThe request has one of these problems:
  • The body is empty or is not JSON.
  • A key is not one that this endpoint takes, such as a misspelled field or a read-only one like verification.
  • terms_of_service_acceptance lacks ip or device_fingerprint_id.
  • terms_of_service_acceptance has a key other than ip and device_fingerprint_id.
  • business_name is sent for an individual, whose name comes from the PAN.
Solution: Send valid JSON with only the keys this endpoint takes. Send ip and device_fingerprint_id in terms_of_service_acceptance. Do not send business_name for an individual.
Code: 400Reason: invalid_formatA value does not match its format. The value is one of these:
  • An identifier, account number, IFSC, PIN code or date
  • An OTP that is not 6 digits
  • A clarification_responses reply under 50 or over 300 characters
  • A percentage_ownership outside 0-100
A well-formed code that is wrong or expired is not an error. It returns 200. A wrong code stays due. An expired code brings its send action back.Solution: Correct the value named in error.field and send it again. metadata.pattern shows the expected format. metadata.minimum and metadata.maximum show the range.
Code: 400Reason: invalid_optionA value is not one of its options. The value is one of these:
  • business_type, routing_code_type or a business-model answer
  • A document key that is not a document type
  • A key under products for a product the account does not hold
  • An uploaded document attached under a key of another type, named in metadata.expected_type
Solution: Send one of the allowed values. metadata.allowed_values lists them when the list is short.
Code: 400Reason: step_not_dueThe value is not due yet or is not due at all. The value is one of these:
  • A bank account sent before the business type
  • A value that depends on one not verified yet
  • phone_otp or email_otp for a contact that is verified
  • A reply in clarification_responses to a point that does not offer one
  • submit_clarification while points are still open
Razorpay applies values in order, so it saves the earlier ones in the body. metadata.due lists what is due.Solution: Send only what the requirements list. metadata.due lists what is due now.
Code: 400Reason: idempotency_key_reusedYou used this X-Idempotency-Key in the last 24 h with a different body or file.Solution: Send a new X-Idempotency-Key for a different request. Reuse a key only to retry the same request.
Code: 401Reason: invalid_credentialsThe Authorization header is missing or is not Basic. Other causes are a key that is not a partner key or a wrong secret. A secret also stops working when it is revoked or its rotation window ends.Solution: Send your partner key and secret as HTTP Basic credentials. Check that the secret is current for the key.
Code: 403Reason: onboarding_not_enabledYour app does not have access to the Onboarding APIs in this mode. Razorpay may also have turned off your app’s access.Solution: Contact Razorpay to get access to the Onboarding APIs for your app in this mode.
Code: 403Reason: ip_not_allowedThe request came from an IP address outside your app’s allowlist for its mode. Test mode checks the allowlist once it has an entry.Solution: Send requests from an IP range on your app’s allowlist for this mode. To use another range, add it to the allowlist on the Partner Dashboard.
Code: 403Reason: consent_withdrawnThrough Razorpay, the sub-merchant withdrew your permission to act on the account. Calls on this account never succeed again for your platform.Solution: Stop calling this account and update your records.
Code: 404Reason: not_foundNo account with this ID is mapped to your app in this mode. The account does not exist, belongs to another platform or belongs to a direct Razorpay merchant. It can also be a test account called in live mode.Solution: Check the ID in error.field. Use the ID of an account mapped to your app, in the same mode as your key.
Code: 404Reason: not_foundA document id is not a document of this account or was deleted.Solution: Check the ID in error.field. Use the ID of a document on this account that is not deleted.
Code: 409Reason: idempotency_in_progressA request with this X-Idempotency-Key is still running. Razorpay stores its result only when it finishes.Solution: Wait for the time in the Retry-After header, then retry with the same key.
Code: 409Reason: field_lockedThe value cannot change at this stage. The value is one of these:
  • The KYC details while a product is in review (under_review or edd_pending) or activated
  • Anything not listed in requirements during needs_clarification
  • business_type once the PAN is verified
  • The owner’s email or phone once verified
  • Anything on a rejected product
The KYC details are the business profile, the authorised person, the stakeholders and the bank account. After activation, a few details can change after a manual review. Know more about account management.Solution: Tell the sub-merchant that this detail cannot change now. metadata.status names the status that locks it.
Code: 429Reason: rate_limitedYour app sent more requests than its rate limit allows.Solution: Wait for the time in the Retry-After header, then retry.
Code: 500Reason: internal_errorSomething went wrong inside Razorpay.Solution: Retry the request. A write retried with the same X-Idempotency-Key does not act twice.
Last modified on November 18, 2026