Upload Dispute File

About 449 wordsAbout 2 min

2025-04-23

After the file is uploaded successfully, the API only returns the file storage path. The file has not yet been submitted to a specific dispute case. Use the returned filePath later in Upload Defense Document or Submit Defense.

Request format

This API must be submitted as multipart/form-data. Pure JSON request bodies are not supported. file is a top-level multipart file field, and bizContent is a top-level multipart text field whose value is a JSON string.

Request Body Parameters

multipart/form-data

Common Request Parameters

bizContent

fileNameString(64)Required
File name. It must include a file extension and should match the original file name uploaded in the file field.
md5String(128)Optional
MD5 of the uploaded file content. If provided, it must exactly match the uploaded file content. A 32-character lowercase hexadecimal value is recommended. If omitted, MD5 is not verified.

Other Parameters

请求报文示例

{
  "clientId": "2023060217493010231",
  "accId": "2023060217493010231446",
  "version": "1.0",
  "signType": "SHA256",
  "bizContent": {
    "fileName": "chargeback_evidence.pdf",
    "md5": "d41d8cd98f00b204e9800998ecf8427e"
  },
  "sign": "{{Sign}}",
  "file": "@/path/to/chargeback_evidence.pdf"
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

filePathStringRequired
Uploaded file path. When submitting appeal materials later, use this value in defenseDocuments[].contentPath of the supplyDefenseDocument API to reference the file.

响应报文示例

{
  "clientId": "2023060217493010231",
  "accId": "2023060217493010231446",
  "code": "000000",
  "description": "Success",
  "bizContent": {
    "filePath": "/dispute/2026/08/27/abc123.pdf"
  },
  "signType": "SHA256",
  "sign": "{{Sign}}"
}

Signature

The binary content in the file field is not directly included in the V4 request signature. The top-level Form Data text fields are signed:

accId
bizContent
clientId
signType
version

Remove sign before generating the signature. If md5 is provided in bizContent, it is included as part of the bizContent string for signing, and the server also uses it to verify the uploaded file content.

Signature plain text example:

accId=2023060217493010231446&bizContent={"fileName":"chargeback_evidence.pdf","md5":"d41d8cd98f00b204e9800998ecf8427e"}&clientId=2023060217493010231&signType=SHA256&version=1.0

The bizContent string used for signing must exactly match the value sent in the request. Differences in spaces, escaping, field order, or md5 letter case may cause signature verification or MD5 verification to fail.

cURL Example

curl -X POST 'https://{baseUrl}/v4/dispute/disputeUploadFile' \
  -F 'clientId=2023060217493010231' \
  -F 'accId=2023060217493010231446' \
  -F 'version=1.0' \
  -F 'signType=SHA256' \
  -F 'bizContent={"fileName":"chargeback_evidence.pdf","md5":"d41d8cd98f00b204e9800998ecf8427e"}' \
  -F 'sign={requestSign}' \
  -F 'file=@/path/to/chargeback_evidence.pdf;type=application/pdf'

Notes

file must be a real file upload field named file.
bizContent is a string field, and its value is JSON.
md5 is the MD5 of the uploaded file content, not the file name, file path, or bizContent.
A single file can be up to 10 MB.
Use the response code to determine whether the API succeeded. HTTP 200 only means that the HTTP request was processed.