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 returns400 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,stakeholdersandbank_accountsby key. addresses: Razorpay merges the list bytype. Send only the address that changed, with itstype.- A bank account: Send all 3 of its fields together.
business_category: Razorpay merges it by attribute, and itsbusiness_model_clarificationsby 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.
PATCH /v1/accounts/{account_id}
ckyc_fetch is due:
Response
Request Parameters
Request Parameters
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.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 itsverification.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: trueheader 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_progresswithRetry-After.
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 returns409 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 arepayment_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 thepayment_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.
- Send the new account at
bank_accounts.settlements_primary. - Razorpay verifies it as during onboarding, with a penny drop that matches the holder’s name against the business.
- Once its
verification.statusisverified, settlements switch to it. Until then, they keep going to the current account, so a failed check never stops payouts. - If the check fails, its
verification.error_codesays why, and thebank_accountcomposite requirement comes back. Answer it with a corrected account (settlement_bank_account) or a ₹1 UPI payment throughcreate_upi_link. The UPI payment’s outcome arrives throughaccount.requirements.updated.
PATCH /v1/accounts/{account_id}
Curl
settlements_primary with its verification.
3.6 Upload Documents
When a requirement’svalue_type is document, send the file at the requirement’s field_path in one of 2 ways:
- As a Link
- As an Upload
Sending a link is coming soon. Until then, upload the file and send its
id with Update an Account.Send { "url": "https://..." }, a pre-signed https link, such as an S3 pre-signed URL, valid for at least 15 min.- Razorpay downloads it once, runs the same checks as an upload and stores it under a new file ID. Razorpay does not keep your link.
- Use a pre-signed link, never a public object.
- Links to private or internal addresses, or links that redirect to one, return
400 invalid_document_url. - This is the only way to send a document in Create.
POST /v1/accounts/{account_id}/documents
id as { "id": "file_..." } in the matching documents key. Razorpay verifies the document when you attach it.
PATCH /v1/accounts/{account_id}
Curl
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.
Request Parameters
Request Parameters
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.