> ## 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.

# Document Tests

> Test document uploads on Onboarding APIs in Test Mode, including attach, verification and file check scenarios.

Available in
🇮🇳 India

Upload and attach KYC documents on a test account and force each outcome with a test file name. Check every file rule before you go live.

Upload a file, then attach its `id` at the input's `field_path` in an update. Or send a pre-signed `https` `url` in the update instead. Razorpay keeps its own copy either way. Every document comes back with its `url`, the link to the stored file.

Start with the [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) for test credentials and headers.

## 1. Test Mode Coverage

### Test Mode Differences

The table below lists how documents behave in each mode:

| Behaviour | Live mode | Test mode |
| - | - | - |
| Document outcomes | Razorpay reads the document, checks it for authenticity and matches it to the details sent. | The content is not read. The file name decides the outcome. |
| Upload checks | Razorpay checks the size, the type from the bytes, any password and the name. | The same checks run for real. |
| Links | Razorpay downloads a link once and keeps its own copy. | The same as live mode. |
| The Aadhaar from DigiLocker | The sub-merchant shares it from DigiLocker. | The DigiLocker hosted test page returns it in `documents` with `metadata.source: digilocker`. See scenario 12 on [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md). |

### What You Can Test

The table below lists the areas to test on these endpoints:

| Area | What to test | In test mode |
| - | - | - |
| Upload, list, fetch and delete | Every endpoint and its errors | Available |
| Attach by `id` | Attaching an uploaded document by its `id` | Available |
| Attach by `url` | Attaching a link, and links that cannot be fetched | Coming soon |
| Document outcomes | Verified and rejected, by file name | Available |
| Upload checks | Size, type from the bytes, password and name | Available |
| Documents Razorpay fetches | The Aadhaar from DigiLocker | Available |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| [Upload a Document](https://razorpay.com/docs/api/partners/accounts/upload-document.md) | `POST /v1/accounts/{account_id}/documents` | Available |
| [Fetch All Documents](https://razorpay.com/docs/api/partners/accounts/fetch-all-documents.md) | `GET /v1/accounts/{account_id}/documents` | Available |
| [Fetch One Document](https://razorpay.com/docs/api/partners/accounts/fetch-document.md) | `GET /v1/accounts/{account_id}/documents/{file_id}` | Available |
| [Delete a Document](https://razorpay.com/docs/api/partners/accounts/delete-document.md) | `DELETE /v1/accounts/{account_id}/documents/{file_id}` | Available |
| [Update an Account](https://razorpay.com/docs/api/partners/accounts/update.md) | `PATCH /v1/accounts/{account_id}`, to attach a document | Available |

## 2. Before You Begin

Prepare the following before you run the scenarios:

* Get an account with a document due, such as the PAN card after scenario 9 on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).
* Use any small, valid PDF, JPEG or PNG, renamed to a test file name below.
* Send the file as `multipart/form-data` with `file` and `type`. The file can be up to 20 MB. Razorpay reads the format from the bytes, not from the file name or the part's content type.

### Test Files

The file name is case-sensitive, and the extension is ignored.

The table below lists the test file names and the outcome each forces:

| File name | Use it for | Outcome |
| - | - | - |
| `PERSONALPANFRONT.jpg` | PAN card | Reads PAN `ABCPD1234A`, name `Rzp Test QA Merchant`. Verified when that is the PAN sent. |
| `PERSONALPANNAMEMISMATCHFRONT.jpg` | PAN card | Reads PAN `ABCPD1234A` with another name. Rejected with `pan_card_name_mismatch`. |
| `PERSONALPANMISMATCHFRONT.jpg` | PAN card | Reads PAN `ABCPD1234Z`. Rejected with `pan_card_mismatch`. |
| `PERSONALPANUNREADABLEFRONT.jpg` | PAN card | No name or number can be read. Rejected with `pan_card_name_unreadable`. |
| `WRONGFRONT.jpg` | PAN card | Not a PAN card. Rejected with `not_a_pan_card`. |
| `AADHAARCKYCCOMPLETE.jpg` | Proof of address | A complete Aadhaar, front and back, for `Rzp Test QA Merchant` |
| `AADHARMISMATCHFRONT.jpg` | Proof of address | An Aadhaar in another name. Rejected with `poa_name_mismatch`. |
| `AADHAARUNREADABLEFRONT.jpg` | Proof of address | An Aadhaar that cannot be read. Rejected with `poa_unreadable`. |
| `AADHARFRONT_<PAN>.jpg`, `AADHARBACK_<PAN>.jpg` | Proof of address for a test business | The holder's Aadhaar, front and back |
| `BUSINESS_PAN_` plus the business PAN | Business PAN card | The company's PAN card, such as `BUSINESS_PAN_MERCM3412F.pdf` |
| `COI_` plus the business PAN | Certificate of incorporation | In place of the Corporate Identification Number (CIN), such as `COI_MERCM3412F.pdf` |
| `GST_`, `REG_` or `SHOP_` plus the PAN | Proof of business for a proprietorship | Goods and Services Tax (GST) certificate, Udyam certificate or shop establishment certificate |

### Sample Request

The request below uploads a PAN card. Attach its `id` at the input's `field_path` in an update. Razorpay checks an uploaded document only once it is attached.

```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=individual_pan_document" \
-F "file=@PERSONALPANFRONT.jpg"
```

Know more about the [request parameters](https://razorpay.com/docs/api/partners/accounts/upload-document.md).

### Sample Response

`GET /v1/accounts/{account_id}/documents` lists documents as a collection of the same object. `GET /v1/accounts/{account_id}/documents/{file_id}` fetches one.

> [accordion] Upload Response: HTTP 201
>
> ```json Response theme={null}
> {
>   "id": "file_N0c5yTe67Jk3Wb",
>   "entity": "document",
>   "type": "individual_pan_document",
>   "url": null,
>   "metadata": {
>     "source": "upload",
>     "file_name": "PERSONALPANFRONT.jpg",
>     "mime_type": "image/jpeg",
>     "size_bytes": 48211
>   }
> }
> ```

### Delete a Document

`DELETE` removes a file you uploaded, or the CKYC Aadhaar. It takes no idempotency key.

```bash Curl theme={null}
curl -X DELETE https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1/documents/file_N0c5yTe67Jk3Wb \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

```json Response theme={null}
{
  "id": "file_N0c5yTe67Jk3Wb",
  "entity": "document",
  "deleted": true
}
```

## 3. Test Scenarios

Work through these scenarios in order. Each row gives the trigger to send and what to confirm in the response.

### 3.1 Scenarios

**Live** scenarios work in test mode today. **Coming soon** scenarios are not available in test mode yet.

The table below lists 15 scenarios. 11 are live and 4 are coming soon:

<table>
  <colgroup>
    <col width="6%" />

    <col width="22%" />

    <col width="24%" />

    <col width="48%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger</th><th>What to confirm</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Upload a document Live</td><td>`PERSONALPANFRONT.jpg`, `type: individual_pan_document`</td><td>Upload it, as in the [sample request](#sample-request). Confirm a `file_…` `id`, `url: null` and `metadata.source: upload`. The upload has no verification.</td></tr>
    <tr><td>2</td><td>Send the PAN card instead of the number Live</td><td>The `id` from #1, on an individual with no PAN sent yet</td><td>Send `{ "id" }` at `business_profile.authorized_person.documents.individual_pan_document`. Confirm the card is verified and `individual_pan` cleared.</td></tr>
    <tr><td>3</td><td>Send a document as a link Coming soon</td><td>A pre-signed `https` URL to `PERSONALPANFRONT.jpg`</td><td>Send `{ "url" }` at the path. Confirm the same result as #2.</td></tr>
    <tr><td>4</td><td>A card that does not verify Coming soon</td><td>`PERSONALPANMISMATCHFRONT.jpg` (reads `ABCPD1234Z`)</td><td>Attach it as in #2. Confirm the card's `verification` is `rejected` with `error_code: pan_card_mismatch`. Confirm `business_profile.authorized_person.documents.individual_pan_document` is due again.</td></tr>
    <tr><td>5</td><td>A card with another name Coming soon</td><td>`PERSONALPANNAMEMISMATCHFRONT.jpg`</td><td>Attach it as in #2. Confirm `rejected` with `pan_card_name_mismatch`.</td></tr>
    <tr><td>6</td><td>Front, then back Live</td><td>`AADHARFRONT_ZOYPQ7428D.jpg`, then `AADHARBACK_ZOYPQ7428D.jpg`</td><td>On Individual D, after you send its PAN, attach the front at `business_profile.authorized_person.documents.aadhaar_front`. Confirm `proof_of_address_for_individual` stays due, with only the back left of `poa_via_aadhaar_documents`, the `all_of` pair. Attach the back at `business_profile.authorized_person.documents.aadhaar_back`. Confirm `proof_of_address_for_individual` clears. Or send both in 1 update.</td></tr>
    <tr><td>7</td><td>List and fetch documents Live</td><td>`?type=individual_pan_document`, and a `file_` ID</td><td>Confirm `url` is `null` in the list. Fetch one with `include_signed_url=true` and confirm a signed `url`. A type with no documents returns `count: 0`.</td></tr>
    <tr><td>8</td><td>Delete a document Live</td><td>A document you uploaded</td><td>Delete it. Confirm `deleted: true`. Confirm it no longer appears in the list.</td></tr>
    <tr><td>9</td><td>Delete a deleted document Live</td><td>The document from #8</td><td>Delete it again. Confirm `404 not_found` with `field: file_id`.</td></tr>
    <tr><td>10</td><td>File too large Live</td><td>A 21 MB PDF</td><td>Confirm `413 file_too_large` with `metadata.max_bytes`.</td></tr>
    <tr><td>11</td><td>Wrong file type Live</td><td>A `.heic`, or a `.txt` renamed to `.pdf`</td><td>Confirm `415 unsupported_media_type` with `metadata.detected_type` and `metadata.accept`.</td></tr>
    <tr><td>12</td><td>Password-protected or corrupt file Live</td><td>A locked PDF, or a truncated PDF</td><td>Confirm `400 password_protected_file` for the locked file and `400 invalid_file` for the truncated one.</td></tr>
    <tr><td>13</td><td>File name not allowed Live</td><td>A name with `/`, or a name longer than 255 bytes</td><td>Confirm `400 invalid_file_name` for the first and `400 file_name_too_long` for the second.</td></tr>
    <tr><td>14</td><td>Missing or unknown type Live</td><td>No `type`, or `type: selfie`</td><td>Confirm `400 invalid_request` for the first and `400 invalid_option` for the second.</td></tr>
    <tr><td>15</td><td>A link Razorpay cannot fetch Coming soon</td><td>`http://…`, or `https://10.0.0.1/a.pdf`</td><td>Confirm `400 invalid_document_url`.</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

The details below expand the scenarios that need more than one step:

> [accordion] 1. Upload a Document
>
> **Before you begin:** Rename any small JPEG to `PERSONALPANFRONT.jpg`.
>
> **How to test:** Send the [sample request](#sample-request).
>
> **Expected result:** HTTP 201 with the document object: its `id`, `entity`, `type`, `url: null` and `metadata`.
>
> **Your integration should:** Upload, then attach. Razorpay checks an uploaded document only once it is attached.

> [accordion] 2. Send the PAN Card Instead of the Number
>
> **Before you begin:** Create a new individual account with `business_type` sent and no PAN yet. `individual_pan` offers the number or the card, as a `one_of`.
>
> **How to test:** Send this update:
>
> ```json theme={null}
> {
>   "business_profile": {
>     "authorized_person": {
>       "documents": {
>         "individual_pan_document": {
>           "id": "file_N0c5yTe67Jk3Wb"
>         }
>       }
>     }
>   }
> }
> ```
>
> **Expected result:** HTTP 200 with the card attached and verified. It reads PAN `ABCPD1234A` and name `Rzp Test QA Merchant`. `individual_pan` clears, and `ckyc_fetch` follows from the PAN read. A card that reads another PAN, or another name, is rejected (#4, #5).
>
> **Your integration should:** Attach at the input's `field_path` exactly. A document of one type under another type's key returns `400 invalid_option`.

> [accordion] 6. Front, Then Back
>
> **Before you begin:** Use Individual D (PAN `ZOYPQ7428D`, no Central KYC Records Registry record), after you send its PAN. `proof_of_address_for_individual` is due.
>
> **How to test:**
>
> 1. Upload `AADHARFRONT_ZOYPQ7428D.jpg` with `type: aadhaar_front`. Attach its `id` at `business_profile.authorized_person.documents.aadhaar_front`.
> 2. Fetch the account. Then upload and attach `AADHARBACK_ZOYPQ7428D.jpg` at `business_profile.authorized_person.documents.aadhaar_back`.
>
> **Expected result:** After the front, `proof_of_address_for_individual` is still due. The front has dropped out of `poa_via_aadhaar_documents`. An `all_of` left with 1 sub-requirement is shown as that sub-requirement, so the Aadhaar choice is `poa_aadhaar_back` alone. The passport, the voter ID and DigiLocker are still offered:
>
> ```json theme={null}
> [
>   {
>     "id": "req_63ayeHknvAqF3b",
>     "requirement_code": "proof_of_address_for_individual",
>     "requirement_level": "mandatory",
>     "requirement_type": "composite",
>     "description": "Verify the proof of address for an individual. It can be done through one of the multiple ways.",
>     "fulfillment_criteria": "one_of",
>     "sub_requirements": [
>       {
>         "id": "req_8Z7cOzH9RmInpe",
>         "requirement_code": "create_aadhaar_digilocker_link",
>         "requirement_level": "conditional",
>         "requirement_type": "action",
>         "description": "Share your Aadhaar from DigiLocker to verify your address.",
>         "status": "created"
>       },
>       {
>         "id": "req_ZldFJm6xUdiytV",
>         "requirement_code": "poa_via_document_upload",
>         "requirement_level": "conditional",
>         "requirement_type": "composite",
>         "description": "Upload both sides of the proof of address document.",
>         "fulfillment_criteria": "one_of",
>         "sub_requirements": [
>           {
>             "id": "req_h0bDEfO2nsiz11",
>             "requirement_code": "poa_aadhaar_back",
>             "requirement_level": "conditional",
>             "requirement_type": "input",
>             "description": "Back side of Aadhaar.",
>             "field_path": "business_profile.authorized_person.documents.aadhaar_back",
>             "value_type": "document",
>             "status": "created"
>           },
>           {
>             "id": "req_NLtTxBNkCbhnO5",
>             "requirement_code": "poa_via_passport_documents",
>             "requirement_level": "conditional",
>             "requirement_type": "composite",
>             "description": "Passport: front and back.",
>             "fulfillment_criteria": "all_of",
>             "sub_requirements": [
>               {
>                 "id": "req_fNrgaH4kj0U0xo",
>                 "requirement_code": "poa_passport_front",
>                 "requirement_level": "mandatory",
>                 "requirement_type": "input",
>                 "description": "Front side of the passport.",
>                 "field_path": "business_profile.authorized_person.documents.passport_front",
>                 "value_type": "document",
>                 "status": "created"
>               },
>               {
>                 "id": "req_wa2RY80UNI5xz8",
>                 "requirement_code": "poa_passport_back",
>                 "requirement_level": "mandatory",
>                 "requirement_type": "input",
>                 "description": "Back side of the passport.",
>                 "field_path": "business_profile.authorized_person.documents.passport_back",
>                 "value_type": "document",
>                 "status": "created"
>               }
>             ],
>             "status": "created"
>           },
>           {
>             "id": "req_LbhXMBnfvBDfU5",
>             "requirement_code": "poa_via_voter_id_documents",
>             "requirement_level": "conditional",
>             "requirement_type": "composite",
>             "description": "Voter ID: front and back.",
>             "fulfillment_criteria": "all_of",
>             "sub_requirements": [
>               {
>                 "id": "req_hQpfCIgX1EPiJV",
>                 "requirement_code": "poa_voter_id_front",
>                 "requirement_level": "mandatory",
>                 "requirement_type": "input",
>                 "description": "Front side of the voter ID.",
>                 "field_path": "business_profile.authorized_person.documents.voter_id_front",
>                 "value_type": "document",
>                 "status": "created"
>               },
>               {
>                 "id": "req_6bWvV57FbjHh6b",
>                 "requirement_code": "poa_voter_id_back",
>                 "requirement_level": "mandatory",
>                 "requirement_type": "input",
>                 "description": "Back side of the voter ID.",
>                 "field_path": "business_profile.authorized_person.documents.voter_id_back",
>                 "value_type": "document",
>                 "status": "created"
>               }
>             ],
>             "status": "created"
>           }
>         ],
>         "status": "created"
>       }
>     ],
>     "status": "created"
>   }
> ]
> ```
>
> Once the back is attached, the whole composite clears.
>
> **Your integration should:** Ask for both sides of a document together, because each 2-sided document is an `all_of` pair. Until the composite clears, keep offering what `requirements` lists.

> [accordion] 9. Delete a Deleted Document
>
> **How to test:** Delete the document from #8 again.
>
> **Expected result:** HTTP 404 with `reason: not_found` and `field: file_id`.
>
> **Your integration should:** Treat a `404` on delete as already deleted. To replace an attached document, upload the new file and attach its `id`. Razorpay does not check whether the account uses a file before deleting it.

> [accordion] 10. File Too Large
>
> **How to test:** Upload a 21 MB PDF.
>
> **Expected result:** HTTP 413 with `reason: file_too_large` and `field: file`.
>
> **Your integration should:** Check the size before uploading: 20 MB at most.

### 3.3 Errors to Handle

Every error returns the same object. Branch on `error.reason` and `error.field`, because the description can change. The [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) lists the errors every operation shares.

The table below lists the errors these endpoints return:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| No `file` or `type`, not multipart or 2 files | 400 | `invalid_request` | `file` |
| `type: selfie` | 400 | `invalid_option` | `type` |
| A malformed `file_id`, or `include_signed_url` not `true` or `false` | 400 | `invalid_format` | The parameter |
| A truncated PDF | 400 | `invalid_file` | `file` |
| A name with `/` or a control character | 400 | `invalid_file_name` | `file` |
| A name over 255 bytes | 400 | `file_name_too_long` | `file` |
| A password-protected PDF | 400 | `password_protected_file` | `file` |
| Over 20 MB | 413 | `file_too_large` | `file` |
| Not multipart | 415 | `unsupported_media_type` | `Content-Type` |
| A format not accepted for the document type | 415 | `unsupported_media_type` | `file` |
| Fetch or delete an unknown `file_` ID | 404 | `not_found` | `file_id` |

## 4. Common Integration Gaps

These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. The **Test with** column points to the scenario that proves you have handled each one.

**Files**

The table below lists the gaps in handling files:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Trusting the extension | A HEIC photo renamed `.jpg` is rejected. | Convert to JPEG, PNG or PDF before upload. Razorpay reads the type from the bytes. | #11 |
| Uploading without attaching | The document never reaches the requirement. | Attach the `id` in an update. | #2 |
| Asking for one side only | The sub-merchant uploads a front, and the back is never asked for. | Ask for the front and the back together, because a 2-sided document is an `all_of` pair. | #6 |

## 5. Best Integration Practices

These practices apply to every onboarding integration. The **On this page** column says what each one means here.

The table below lists the practices for documents:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Links or uploads | Both work. A link must be `https` and pre-signed, valid for at least 15 min and never a public object. Razorpay copies the file. | Use links if your files already sit in storage. | #3, #15 | Not applicable |
| Limits | PDF, JPEG or PNG, up to 20 MB, with no password and a name of up to 255 characters. | Check the file before you upload. | #10 to #13 | Not applicable |

### Related Information

* [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration)
* [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)
* [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md)
* [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)
* [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md)
* [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
* [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md)
* [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md)
* [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md)
* [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md)
