Create a Document

Create a Document using Razorpays API.

POST /v1/documents

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST 'https://api.razorpay.com/v1/documents' \
-H "Content-Type: multipart/form-data" \
-F 'purpose=dispute_evidence' \
-F 'file=@/Users/your_name/sample_uploaded.jpeg'

Success

{
  "id": "doc_EsyWjHrfzb59Re",
  "entity": "document",
  "purpose": "dispute_evidence",
  "name": "doc_19_12_2020.jpg",
  "mime_type": "image/png",
  "size": 2863,
  "created_at": 1590604200
}

Use this endpoint to upload a document onto the Razorpay ecosystem. After a document is successfully uploaded, the corresponding document id (present in response) can be provided in cases such as dispute evidence submission.

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST 'https://api.razorpay.com/v1/documents' \
-H "Content-Type: multipart/form-data" \
-F 'purpose=dispute_evidence' \
-F 'file=@/Users/your_name/sample_uploaded.jpeg'

Success

{
  "id": "doc_EsyWjHrfzb59Re",
  "entity": "document",
  "purpose": "dispute_evidence",
  "name": "doc_19_12_2020.jpg",
  "mime_type": "image/png",
  "size": 2863,
  "created_at": 1590604200
}

Response Parameters

id · string

The unique identifier of the document uploaded.

entity · string

Indicates the type of entity. In this case, it is document.

purpose · string

The reason you are uploading this document. Here, it is dispute_evidence.

size · integer

Indicates the size of the document in bytes.

mime_type · string

Indicates the nature and format in which the document is uploaded. Possible values include:

• image/jpg
• image/jpeg
• image/png
• application/pdf

created_at · integer

Unix timestamp at which the document was uploaded.

Errors

The API `<key/secret> ` provided is invalid.

Code: 401

The API credentials passed in the API call differ from the ones generated on the Dashboard.

• Different keys for test mode and live modes.
• Expired API key.

Solution: The API keys must be active and entered correctly with no whitespace before or after the keys.

The file field is required.

Code: 400

The request did not include a file field. This endpoint expects a multipart/form-data upload with both file and purpose parts.

Solution: Submit the request as multipart/form-data with the file attached under the file part.

The purpose field is required.

Code: 400

The request did not include a purpose field, or the request body was empty.

Solution: Include purpose as a form field in the multipart/form-data request body. Use a supported purpose value (for example, dispute_evidence).

invalid document upload purpose.

Code: 400

The value passed for purpose is not one of the supported document-upload purposes. The API echoes the rejected value, for example invalid document upload purpose:completely_invalid_purpose.

Solution: Use a supported purpose value (for example, dispute_evidence).

Document upload already in progress.

Code: 400

Another document-upload request from the same merchant is already in progress. Razorpay holds a short-lived lock per merchant to prevent concurrent uploads from clashing.

Solution: Wait a few seconds and retry the upload.

The file may not be greater than 50000 kilobytes.

Code: 400

The uploaded file exceeds the 50 MB (50,000 KB) size limit.

Solution: Compress the file or split the content so each upload stays under 50 MB.

The file must be a file of type: {allowed types}.

Code: 400

The uploaded file’s MIME type does not match the allowed types for the supplied purpose. The list of allowed types varies per purpose. For example, kyc_proof accepts pdf, jpeg, jpg, png, jfif, while opgsp_awb accepts only pdf. The error message lists the allowed types for the requested purpose.

Solution: Re-upload the document in one of the allowed file types for the requested purpose.