> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 3. Submit Information

> Send sub-merchant KYC details and documents using Razorpay Onboarding APIs.

Available in
🇮🇳 India

Send the sub-merchant's values with [Update an Account](https://razorpay.com/docs/api/partners/accounts/update.md), 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}`

```bash Business Type theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "business_profile": {
    "business_type": "individual"
  }
}'
```

```bash Owner PAN theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "business_profile": {
    "authorized_person": {
      "identity_numbers": {
        "individual_pan": {
          "value": "ABCPD1234A"
        }
      }
    }
  }
}'
```

```bash Bank Account theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "bank_accounts": {
    "settlements_primary": {
      "account_number": "001234567890",
      "routing_code": "ICIC0000009",
      "routing_code_type": "IFSC"
    }
  }
}'
```

```bash Category theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "business_profile": {
    "business_category": {
      "category": "ecommerce",
      "subcategory": "fashion_and_lifestyle",
      "business_description": "Clothing and accessories for men, women and children, sold online"
    }
  }
}'
```

The response below follows the PAN update. Razorpay verifies the PAN and finds a CKYC record, so `ckyc_fetch` is due:

```json Response theme={null}
{
  "id": "acc_TcdGEzmfKQzEl1",
  "country": "IN",
  "statement_descriptor": null,
  "is_mfa_enabled": false,
  "user": {
    "role": "owner",
    "email": "gaurav.kumar@example.com",
    "phone": "+919611752201",
    "name": "Gaurav Kumar",
    "is_email_verified": true,
    "is_phone_verified": true
  },
  "business_profile": {
    "business_type": "individual",
    "business_name": "GAURAV KUMAR",
    "date_of_establishment": null,
    "identity_numbers": {},
    "documents": {},
    "business_category": null,
    "authorized_person": {
      "name": "GAURAV KUMAR",
      "identity_numbers": {
        "individual_pan": {
          "type": "individual_pan",
          "value": "ABCPD1234A",
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433290,
            "metadata": {},
            "created_at": 1792433290
          },
          "metadata": {},
          "is_skipped": false,
          "created_at": 1792433280,
          "updated_at": 1792433290
        }
      },
      "documents": {},
      "address": null,
      "date_of_birth": null,
      "additional_data": {},
      "created_at": 1792433280,
      "updated_at": 1792433290
    },
    "stakeholders": {},
    "addresses": [],
    "metadata": {}
  },
  "bank_accounts": {},
  "products": {
    "payment_gateway": {
      "type": "payment_gateway",
      "status": "in_progress",
      "status_reason": null,
      "created_at": 1792433135,
      "updated_at": 1792433290,
      "requirements": [
        {
          "id": "req_hocykxcAkjCdtB",
          "requirement_code": "ckyc_fetch",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "The person's CKYC record, fetched with a code or skipped.",
          "fulfillment_criteria": "one_of",
          "sub_requirements": [
            {
              "id": "req_2KRiIGIhuAPNW6",
              "requirement_code": "skip_ckyc",
              "requirement_level": "conditional",
              "requirement_type": "input",
              "description": "Skip CKYC.",
              "field_path": "business_profile.authorized_person.identity_numbers.individual_ckyc.is_skipped",
              "value_type": "boolean",
              "status": "created"
            },
            {
              "id": "req_L3rskP8gX6YVHh",
              "requirement_code": "send_ckyc_otp",
              "requirement_level": "conditional",
              "requirement_type": "action",
              "description": "A Central KYC record was found for your PAN. Get a code on the mobile on your CKYC record to fetch it.",
              "status": "created"
            }
          ],
          "status": "created"
        },
        {
          "id": "req_yD8JfNtIoWXmu4",
          "requirement_code": "statement_descriptor",
          "requirement_level": "mandatory",
          "requirement_type": "input",
          "description": "The name shown on customers' receipts and statements.",
          "field_path": "statement_descriptor.value",
          "value_type": "text",
          "status": "created"
        },
        {
          "id": "req_VgRHb7QJNtMyj2",
          "requirement_code": "settlement_bank_account",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "The bank account that receives settlements, in the name on your PAN.",
          "fulfillment_criteria": "all_of",
          "sub_requirements": [
            {
              "id": "req_4rY5OIDnOHtA2z",
              "requirement_code": "bank_account_number",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "The account number.",
              "field_path": "bank_accounts.settlements_primary.account_number",
              "value_type": "text",
              "status": "created"
            },
            {
              "id": "req_mOTextgE1uJfFK",
              "requirement_code": "bank_routing_code",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "The bank's IFSC.",
              "field_path": "bank_accounts.settlements_primary.routing_code",
              "value_type": "text",
              "status": "created"
            },
            {
              "id": "req_GNDdQcckulAU4g",
              "requirement_code": "bank_routing_code_type",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "The kind of routing code.",
              "field_path": "bank_accounts.settlements_primary.routing_code_type",
              "value_type": "enum",
              "options": [
                {
                  "label": "IFSC",
                  "value": "IFSC"
                }
              ],
              "status": "created"
            }
          ],
          "status": "created"
        },
        {
          "id": "req_7zAE2YmS5MDUhG",
          "requirement_code": "business_category",
          "requirement_level": "mandatory",
          "requirement_type": "input",
          "description": "Select your business category, and send its subcategory with it.",
          "field_path": "business_profile.business_category.category",
          "value_type": "enum",
          "options": [
            {
              "label": "Ecommerce",
              "value": "ecommerce"
            },
            {
              "label": "Food and beverage",
              "value": "food"
            }
          ],
          "status": "created"
        },
        {
          "id": "req_0HAQYzBrDRNnEM",
          "requirement_code": "accept_terms_of_service",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "Show the sub-merchant Razorpay's terms of service and record their acceptance.",
          "fulfillment_criteria": "all_of",
          "sub_requirements": [
            {
              "id": "req_CTW6xxsQmygIDU",
              "requirement_code": "acceptance_ip",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "The IP address the terms were accepted from.",
              "field_path": "products.payment_gateway.terms_of_service_acceptance.ip",
              "value_type": "text",
              "status": "created"
            },
            {
              "id": "req_gXg6igx2STKrZA",
              "requirement_code": "acceptance_device_fingerprint_id",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "The device fingerprint of the device the terms were accepted on.",
              "field_path": "products.payment_gateway.terms_of_service_acceptance.device_fingerprint_id",
              "value_type": "text",
              "status": "created"
            }
          ],
          "status": "created"
        }
      ],
      "terms_of_service_acceptance": null,
      "payment_channels": {
        "website": {
          "primary": "https://www.example.com",
          "additional": [],
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433250,
            "metadata": {},
            "created_at": 1792433220
          }
        },
        "app_android": null,
        "app_ios": null
      },
      "clarification_responses": {}
    }
  },
  "notes": {
    "shop_id": "60291847"
  },
  "created_at": 1792433135,
  "updated_at": 1792433290
}
```

> [accordion] 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](https://razorpay.com/docs/partners/aggregators/onboarding-api/verification-actions.md#4-5-fetch-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](https://razorpay.com/docs/api/partners/accounts/business-categories.md).
>
> `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](https://razorpay.com/docs/api/partners/accounts/update.md) 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](https://razorpay.com/docs/api/partners/accounts/fetch.md) returns it. Each element shows its `verification.status`.

The table below lists what each verification status means:

| `verification.status` | What It Means | What Happens to the Requirement |
| - | - | - |
| `verified` | The check passed. | It clears. |
| `rejected` | The check failed. Razorpay still saves the value, with the reason in `error_code`, for example `bank_name_mismatch`. | It stays due. Show the element's `verification.error_description` to the sub-merchant. |
| `deferred` | The check could not conclude. A reviewer decides after submission. `error_code` is `null`. | It clears. |
| `in_progress` | The check is still running when the response returns. | Fetch the account for the outcome, or wait for `account.requirements.updated`. |

`account.requirements.updated` fires when a running check settles, a website check included. Know more about [failed-check codes](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md#2-3-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](https://razorpay.com/docs/partners/aggregators/onboarding-api/account-management.md). 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}`

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "products": {
    "payment_gateway": {
      "payment_channels": {
        "website": {
          "primary": "https://www.example.com"
        }
      }
    }
  }
}'
```

## 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](https://razorpay.com/docs/api/partners/accounts/update.md) 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`](https://razorpay.com/docs/partners/aggregators/onboarding-api/verification-actions#4-2-mint-a-link). The UPI payment's outcome arrives through `account.requirements.updated`.

`PATCH /v1/accounts/{account_id}`

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "bank_accounts": {
    "settlements_primary": {
      "account_number": "50100234567890",
      "routing_code": "HDFC0001234",
      "routing_code_type": "IFSC"
    }
  }
}'
```

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:

> [tab] As a Link
>
> Sending a link is coming soon. Until then, [upload the file](https://razorpay.com/docs/api/partners/accounts/upload-document.md) and send its `id` with [Update an Account](https://razorpay.com/docs/api/partners/accounts/update.md).
>
> 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.

> [tab] As an Upload
>
> [Upload the file](https://razorpay.com/docs/api/partners/accounts/upload-document.md), one file per request with its document type. Then send `{ "id": "file_..." }` in an update. The upload endpoint takes a file only. To share a link, use the other tab.
>
> * Files are PDF, JPEG or PNG, up to 20 MB. Razorpay reads the format from the file's bytes.
> * The document `type` is one of the [document types](https://razorpay.com/docs/api/partners/accounts/document-entity.md).
> * Upload only after the account exists.

`POST /v1/accounts/{account_id}/documents`

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1/documents \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-F type=aadhaar_front \
-F file=@aadhaar-front.jpg
```

```json Response theme={null}
{
  "id": "file_N0c5yTe67Jk3Wb",
  "entity": "document",
  "type": "aadhaar_front",
  "url": null,
  "metadata": {
    "source": "upload",
    "file_name": "aadhaar-front.jpg",
    "mime_type": "image/jpeg",
    "size_bytes": 1048576
  }
}
```

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}`

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "business_profile": {
    "authorized_person": {
      "documents": {
        "aadhaar_front": {
          "id": "file_N0c5yTe67Jk3Wb"
        }
      }
    }
  }
}'
```

[Fetch One Document](https://razorpay.com/docs/api/partners/accounts/fetch-document.md) returns a file's type and metadata, and a signed download link with `include_signed_url=true`. [Fetch All Documents](https://razorpay.com/docs/api/partners/accounts/fetch-all-documents.md) lists the files you uploaded and the CKYC Aadhaar. [Delete a Document](https://razorpay.com/docs/api/partners/accounts/delete-document.md) removes one. A document's verification shows on the account once you attach it.

> [accordion] 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.

## Next Step

[Run Verification Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/verification-actions.md)
