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-datawithfileandtype. 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 itsid at the input’s field_path in an update. Razorpay checks an uploaded document only once it is attached.
Curl
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.
Upload Response: HTTP 201
Upload Response: HTTP 201
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:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Upload a document Live | PERSONALPANFRONT.jpg, type: individual_pan_document | Upload it, as in the sample request. Confirm a file_… id, url: null and metadata.source: upload. The upload has no verification. |
| 2 | Send the PAN card instead of the number Live | The id from #1, on an individual with no PAN sent yet | Send { "id" } at business_profile.authorized_person.documents.individual_pan_document. Confirm the card is verified and individual_pan cleared. |
| 3 | Send a document as a link Coming soon | A pre-signed https URL to PERSONALPANFRONT.jpg | Send { "url" } at the path. Confirm the same result as #2. |
| 4 | A card that does not verify Coming soon | PERSONALPANMISMATCHFRONT.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. |
| 5 | A card with another name Coming soon | PERSONALPANNAMEMISMATCHFRONT.jpg | Attach it as in #2. Confirm rejected with pan_card_name_mismatch. |
| 6 | Front, then back Live | AADHARFRONT_ZOYPQ7428D.jpg, then AADHARBACK_ZOYPQ7428D.jpg | 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. |
| 7 | List and fetch documents Live | ?type=individual_pan_document, and a file_ ID | 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. |
| 8 | Delete a document Live | A document you uploaded | Delete it. Confirm deleted: true. Confirm it no longer appears in the list. |
| 9 | Delete a deleted document Live | The document from #8 | Delete it again. Confirm 404 not_found with field: file_id. |
| 10 | File too large Live | A 21 MB PDF | Confirm 413 file_too_large with metadata.max_bytes. |
| 11 | Wrong file type Live | A .heic, or a .txt renamed to .pdf | Confirm 415 unsupported_media_type with metadata.detected_type and metadata.accept. |
| 12 | Password-protected or corrupt file Live | A locked PDF, or a truncated PDF | Confirm 400 password_protected_file for the locked file and 400 invalid_file for the truncated one. |
| 13 | File name not allowed Live | A name with /, or a name longer than 255 bytes | Confirm 400 invalid_file_name for the first and 400 file_name_too_long for the second. |
| 14 | Missing or unknown type Live | No type, or type: selfie | Confirm 400 invalid_request for the first and 400 invalid_option for the second. |
| 15 | A link Razorpay cannot fetch Coming soon | http://…, or https://10.0.0.1/a.pdf | Confirm 400 invalid_document_url. |
3.2 Scenario Details
The details below expand the scenarios that need more than one step:1. Upload a Document
1. Upload a Document
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.2. Send the PAN Card Instead of the Number
2. Send the PAN Card Instead of the Number
Before you begin: Create a new individual account with Expected result: HTTP 200 with the card attached and verified. It reads PAN
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: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.6. Front, Then Back
6. Front, Then Back
Before you begin: Use Individual D (PAN 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
ZOYPQ7428D, no Central KYC Records Registry record), after you send its PAN. proof_of_address_for_individual is due.How to test:- Upload
AADHARFRONT_ZOYPQ7428D.jpgwithtype: aadhaar_front. Attach itsidatbusiness_profile.authorized_person.documents.aadhaar_front. - Fetch the account. Then upload and attach
AADHARBACK_ZOYPQ7428D.jpgatbusiness_profile.authorized_person.documents.aadhaar_back.
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:all_of pair. Until the composite clears, keep offering what requirements lists.9. Delete a Deleted Document
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.10. File Too Large
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 onerror.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: