Skip to main content
POST
Available in🇮🇳 India
Use this endpoint to store one KYC file for an account and get its file ID. Send that ID in the account’s documents with Update an Account to attach the file.
Handy Tips
  • Authenticate with the key and secret of your test pair or live pair. In the API playground, enter the test key as the username and its secret as the password. Use the live pair in live mode.
  • Send the request as multipart/form-data, with 1 file and its type. The endpoint takes a file only, never a link.
  • To share a document as a link instead, send its url in the account’s documents with Update an Account. Razorpay downloads it from there.
  • The upload alone does not attach the file. Razorpay verifies a document when you attach it to the account.
  • Razorpay keeps its own copy as the data fiduciary. Delete your copy once the upload succeeds, as your agreement with Razorpay requires.
  • Responses carry Cache-Control: private, no-store. Do not cache them.
Watch Out!A retry with the same X-Idempotency-Key, type and file returns the first response for up to 1 h, without storing a second file. The same key with a different type or file returns 400 with idempotency_key_reused. A refused or failed upload does not hold the key.

Path Parameters

string
required
The unique identifier of the account, acc_-prefixed. For example, acc_TcdGEzmfKQzEl1.

Request Parameters

Send file and type as multipart/form-data parts.
string
required
A unique key you generate for each upload, 16-64 printable ASCII characters long. A Universally Unique Identifier (UUID) works. Know more about idempotency.
file
required
The file, sent with its file name. Exactly 1 file of up to 20 MB:
  • Format: PDF, JPEG or PNG. Razorpay detects the format from the file content. cancelled_cheque_video takes a video instead: MP4, MOV, M4V, MKV, AVI, WMV, FLV or MPEG.
  • PDF: Up to 20 pages, without a password.
  • Image: Up to 50 megapixels.
  • File name: Up to 255 bytes, with no path separator or control character.
string
required
The document type of the file, sent once. The account’s requirements list the types each product needs. Know more about document types.

Response Parameters

string
Unique identifier for the file, file_ followed by 14 letters or digits.
string
Always document.
string
The document type of the file. Know more about the document types.
string
A signed link to download the file. Set only by Fetch One Document with include_signed_url=true. Otherwise null. It is also null when Razorpay could not create the link.
object
About the stored file.
string
Where the file came from. Possible values:
  • upload: You uploaded it.
  • ckyc: Razorpay downloaded it from the CKYC record.
string
The file name as you sent it.
string
The format Razorpay detected from the file content, such as image/jpeg. It can be null.
integer
File size in bytes. It can be null.

Errors

Code: 400Reason: missing_headerX-Idempotency-Key is missing.Solution: Send X-Idempotency-Key with 16-64 printable ASCII characters. error.field names the header.
Code: 400Reason: invalid_formatX-Idempotency-Key is not 16-64 printable ASCII characters.Solution: Send a key of 16-64 printable ASCII characters.
Code: 400Reason: invalid_requestThe body does not have exactly 1 file part and a type. error.field names the missing part.Solution: Send a multipart/form-data body with 1 file and its type.
Code: 400Reason: invalid_optiontype is not a supported document type.Solution: Send a supported document type. Know more about document types.
Code: 400Reason: invalid_fileThe file is empty or Razorpay cannot read it.Solution: Check that the file is complete and readable, then upload it again.
Code: 400Reason: invalid_file_nameThe file name has a path separator or a control character.Solution: Rename the file without path separators or control characters, then upload it again.
Code: 400Reason: file_name_too_longThe file name is longer than 255 bytes, including the extension.Solution: Shorten the file name, then upload it again. metadata.max_bytes is the limit.
Code: 400Reason: password_protected_fileThe PDF is password protected.Solution: Upload a copy without the password.
Code: 400Reason: idempotency_key_reusedYou already used this X-Idempotency-Key for a different upload. A key is bound to its type and the exact file.Solution: Send a new X-Idempotency-Key for a different upload. Reuse a key only to retry the same upload.
Code: 401Reason: invalid_credentialsThe Authorization header is missing or is not Basic. Other causes are a key that is not a partner key or a wrong secret. A secret also stops working when it is revoked or its rotation window ends.Solution: Send your partner key and secret as HTTP Basic credentials. Check that the secret is current for the key.
Code: 403Reason: onboarding_not_enabledYour app does not have access to the Onboarding APIs in this mode. Razorpay may also have turned off your app’s access.Solution: Contact Razorpay to get access to the Onboarding APIs for your app in this mode.
Code: 403Reason: ip_not_allowedThe request came from an IP address outside your app’s allowlist for its mode. Test mode checks the allowlist once it has an entry.Solution: Send requests from an IP range on your app’s allowlist for this mode. To use another range, add it to the allowlist on the Partner Dashboard.
Code: 403Reason: consent_withdrawnThrough Razorpay, the sub-merchant withdrew your permission to act on the account. Calls on this account never succeed again for your platform.Solution: Stop calling this account and update your records.
Code: 404Reason: not_foundNo account with this ID is mapped to your app in this mode. The account does not exist, belongs to another platform or belongs to a direct Razorpay merchant. It can also be a test account called in live mode.Solution: Check the ID in error.field. Use the ID of an account mapped to your app, in the same mode as your key.
Code: 409Reason: idempotency_in_progressAn upload with this X-Idempotency-Key is still running.Solution: Wait for the time in the Retry-After header, then retry with the same key.
Code: 413Reason: file_too_largeThe file is larger than 20 MB.Solution: Upload a file of 20 MB or less. metadata.max_bytes is the limit in bytes.
Code: 415Reason: unsupported_media_typeThe request has one of these problems:
  • The body is not multipart/form-data. error.field is Content-Type.
  • The file format is not accepted for this document type. error.field is file.
Solution: Send the body as multipart/form-data. For the file, use a format in metadata.accept. metadata.detected_type shows the format found.
Code: 429Reason: rate_limitedYour app sent more requests than its rate limit allows.Solution: Wait for the time in the Retry-After header, then retry.
Code: 500Reason: internal_errorSomething went wrong inside Razorpay.Solution: Retry the request.
Last modified on November 18, 2026