Skip to main content
Available in🇮🇳 India
Send the sub-merchant’s values with Update an Account, shaped like the account itself. A one-shot integration uses updates only for codes, unanswered business-model questions, clarifications and requirements that did not verify. A step-by-step integration sends every detail this way.

3.1 Update the Account

Send the business type first, because what is due next depends on it. Some values depend on others. For example, a bank account depends on the business type, and a Central KYC Records Registry (CKYC) code on a verified PAN. An update that sends a value before what it depends on returns 400 with reason: step_not_due. Send only what the requirements list to avoid this, because they list only what is due now. A one-shot Create instead applies its values in the order onboarding needs them. Send only what is changing. Each part of the account updates as follows:
  • Keyed objects: Razorpay merges identity_numbers, documents, stakeholders and bank_accounts by key.
  • addresses: Razorpay merges the list by type. Send only the address that changed, with its type.
  • A bank account: Send all 3 of its fields together.
  • business_category: Razorpay merges it by attribute, and its business_model_clarifications by question ID. Send the description or the business-model answers in separate updates if you prefer.
  • user: Send the owner’s email or phone again to correct it while it is unverified.
The examples below send the business type, the owner’s PAN, the bank account and the category, one update each: PATCH /v1/accounts/{account_id}
The response below follows the PAN update. Razorpay verifies the PAN and finds a CKYC record, so ckyc_fetch is due:
Response
Send only the fields that are changing. A nested field marked mandatory applies only when you send its parent object.business_profile.business_type optional : string The type of business. For example, individual, proprietorship or private_limited.business_profile.authorized_person.identity_numbers.individual_pan.value optional : string The authorised person’s PAN. For example, ABCPD1234A.business_profile.authorized_person.identity_numbers.individual_ckyc.otp optional : string The 6-digit code that send_ckyc_otp sent to the mobile on the CKYC record. Send it with request_id. Razorpay never returns it. Know more about fetching KYC from CKYC.business_profile.authorized_person.identity_numbers.individual_ckyc.request_id optional : string The request ID that send_ckyc_otp returned with the code. For example, CKYCREQ20261115000123. Razorpay never returns it.bank_accounts.settlements_primary.account_number mandatory : string The settlement account number, 5 to 35 digits. For example, 001234567890.bank_accounts.settlements_primary.routing_code mandatory : string The bank’s Indian Financial System Code (IFSC). For example, ICIC0000009.bank_accounts.settlements_primary.routing_code_type mandatory : string The kind of routing code. Possible value: IFSC.business_profile.business_category.category optional : string The business category. For example, ecommerce.business_profile.business_category.subcategory optional : string The subcategory, sent with its category. For example, fashion_and_lifestyle. Know more about business categories and subcategories.business_profile.business_category.business_description optional : string What the business sells and how.statement_descriptor optional : object The name customers see on their bank statements and receipts.statement_descriptor.value mandatory : string The brand name shown on customer statements. Up to 255 characters.
Refer to Update an Account for every request parameter and error.

3.2 Read the Verification Result

The response comes back within 3 sec. It is the account itself, as Fetch Accounts returns it. Each element shows its verification.status. The table below lists what each verification status means: account.requirements.updated fires when a running check settles, a website check included. Know more about failed-check codes. A wrong One-Time Password (OTP) returns 200 with the code still due. An expired code, or 3 wrong tries, brings the send action back.

3.2.1 Retry Safely

Writes to one account run one at a time, in the order they arrive. Every write (POST, PATCH and DELETE under /v1/accounts) needs an X-Idempotency-Key header. Generate a key of 16 to 64 printable ASCII characters for each operation. A Universally Unique Identifier (UUID) works.
  • Retry with the same key: A retry within 24 h returns the original response with an Idempotent-Replayed: true header instead of acting twice.
  • Repeat on purpose with a new key: Send a new key to repeat an operation, for example, to ask for a new OTP.
  • Same key, different body: Returns 400 idempotency_key_reused.
  • Same key while the first request runs: Returns 409 idempotency_in_progress with Retry-After.
Razorpay stores only finished requests. It does not store a 5xx or a 409 idempotency_in_progress, so a retry with the same key runs the request again. A write without the header returns 400 missing_header.

3.3 Locked Details

From submission on, including after activation, the KYC details are locked. This covers the business profile, the authorised person, the stakeholders and the bank account. Changing one returns 409 with reason: field_locked and error.field naming it. Use error.field to tell the sub-merchant what cannot change. After activation, a few details can change after a manual review: the brand name, the settlement bank account, the GSTIN, the operational address and the website and apps. Know more about account management. In needs_clarification, only the listed fields can change.

3.4 Send the Payment Channels

The channels the business accepts payments on are payment_channels on the payment_gateway product: website, app_android and app_ios. Send them in Create or in an update. The website is optional. A product can go through submission and activation without one. Until you send a channel, the payment_channels composite requirement is due as optional. Its one_of holds website_url, app_android_url and app_ios_url. Any one satisfies it. Send the others too if the business uses them. When you send a website, Razorpay checks it for liveness and content, and uses it to suggest the category. The check shows at products.payment_gateway.payment_channels.website.verification. It is null until the check starts, then in_progress, then verified or rejected with website_unreachable. PATCH /v1/accounts/{account_id}
Curl

3.5 Change the Bank Account

Once the payment_gateway product is activated, the sub-merchant can move settlements to another bank account of the business. Use the same update as during onboarding. You need no separate endpoint and no form for Razorpay.
  1. Send the new account at bank_accounts.settlements_primary.
  2. Razorpay verifies it as during onboarding, with a penny drop that matches the holder’s name against the business.
  3. Once its verification.status is verified, settlements switch to it. Until then, they keep going to the current account, so a failed check never stops payouts.
  4. If the check fails, its verification.error_code says why, and the bank_account composite requirement comes back. Answer it with a corrected account (settlement_bank_account) or a ₹1 UPI payment through create_upi_link. The UPI payment’s outcome arrives through account.requirements.updated.
PATCH /v1/accounts/{account_id}
Curl
The response returns the new account under settlements_primary with its verification.

3.6 Upload Documents

When a requirement’s value_type is document, send the file at the requirement’s field_path in one of 2 ways:
POST /v1/accounts/{account_id}/documents
Send the returned document id as { "id": "file_..." } in the matching documents key. Razorpay verifies the document when you attach it. PATCH /v1/accounts/{account_id}
Curl
Fetch One Document returns a file’s type and metadata, and a signed download link with include_signed_url=true. Fetch All Documents lists the files you uploaded and the CKYC Aadhaar. Delete a Document removes one. A document’s verification shows on the account once you attach it.
type mandatory : string The document type. For example, aadhaar_front.file mandatory : file The file: PDF, JPEG or PNG, up to 20 MB. Razorpay reads the format from the bytes, not from the file name or the part’s content type.

Next Step

Run Verification Actions
Last modified on November 18, 2026