Skip to main content
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 for test credentials and headers.

1. Test Mode Coverage

Test Mode Differences

The table below lists how documents behave in each mode:

What You Can Test

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

Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

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.
  • 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:

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.
Curl
Know more about the request parameters.

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

Delete a Document

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

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:
#ScenarioTriggerWhat to confirm
1Upload a document LivePERSONALPANFRONT.jpg, type: individual_pan_documentUpload it, as in the sample request. Confirm a file_… id, url: null and metadata.source: upload. The upload has no verification.
2Send the PAN card instead of the number LiveThe id from #1, on an individual with no PAN sent yetSend { "id" } at business_profile.authorized_person.documents.individual_pan_document. Confirm the card is verified and individual_pan cleared.
3Send a document as a link Coming soonA pre-signed https URL to PERSONALPANFRONT.jpgSend { "url" } at the path. Confirm the same result as #2.
4A card that does not verify Coming soonPERSONALPANMISMATCHFRONT.jpg (reads ABCPD1234Z)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.
5A card with another name Coming soonPERSONALPANNAMEMISMATCHFRONT.jpgAttach it as in #2. Confirm rejected with pan_card_name_mismatch.
6Front, then back LiveAADHARFRONT_ZOYPQ7428D.jpg, then AADHARBACK_ZOYPQ7428D.jpgOn 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.
7List and fetch documents Live?type=individual_pan_document, and a file_ IDConfirm 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.
8Delete a document LiveA document you uploadedDelete it. Confirm deleted: true. Confirm it no longer appears in the list.
9Delete a deleted document LiveThe document from #8Delete it again. Confirm 404 not_found with field: file_id.
10File too large LiveA 21 MB PDFConfirm 413 file_too_large with metadata.max_bytes.
11Wrong file type LiveA .heic, or a .txt renamed to .pdfConfirm 415 unsupported_media_type with metadata.detected_type and metadata.accept.
12Password-protected or corrupt file LiveA locked PDF, or a truncated PDFConfirm 400 password_protected_file for the locked file and 400 invalid_file for the truncated one.
13File name not allowed LiveA name with /, or a name longer than 255 bytesConfirm 400 invalid_file_name for the first and 400 file_name_too_long for the second.
14Missing or unknown type LiveNo type, or type: selfieConfirm 400 invalid_request for the first and 400 invalid_option for the second.
15A link Razorpay cannot fetch Coming soonhttp://…, or https://10.0.0.1/a.pdfConfirm 400 invalid_document_url.

3.2 Scenario Details

The details below expand the scenarios that need more than one step:
Before you begin: Rename any small JPEG to PERSONALPANFRONT.jpg.How to test: Send the 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.
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:
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.
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:
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.
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.
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 lists the errors every operation shares. The table below lists the errors these endpoints return:

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:

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:
Last modified on November 18, 2026