Upload file

Description

This API is used to obtain file upload credentials. The upload process consists of two steps:

1. Get upload credentials: Call this API to obtain uploadUrl (upload address) and storageUri (file storage path)
2. Execute file upload: Use uploadUrl and form fields from formFields, upload the file via the method specified by httpMethod

Notes:

• The uploadUrl is valid for 10 minutes. After expiration, obtain a new one.
• The storageUri is the unique identifier of the file. After successful upload, it can be used for other APIs (e.g., the evidence URL in the dispute contest API).
• When executing the form upload, all fields in formFields must be included, and the file field must be placed at the end of the form, otherwise the upload will fail.

Request URL - Get Upload URL

https://{{gateway_domain}}/pg/v2/file/generateUploadUrl

Request Parameters

HTTP Method

POST

HTTP Header

Field	Data Type	Length Limit	Required	Description
Content-Type	String	N/A	YES	This field value only supports application/json.
Accept	String	N/A	YES	This field value only supports application/json.
Authorization	String		YES	Authorization: {type} {credentials}, refer to the Signature specification

HTTP Body

Field	Data Type	Length Limit	Required	Description
filename	String	32	YES	File name, must include extension
contentType	String	32	NO	File MIME type, common types
scene	String	50	YES	Business scene

Scene Description

Scene Value	Description	Supported File Types	File Size Limit
DISPUTE_EVIDENCE	Dispute evidence files	jpg, jpeg, png, pdf, xls, xlsx	2MB

• The scene parameter must be uppercase

Response Data

HTTP Header

Field	Data Type	Required	Description
Content-Type	String	YES	This field value only supports application/json.
Authorization	String	YES	Authorization: {type} {credentials}, refer to the Signature specification

HTTP Body

Field	Data Type	Required	Description
code	String	YES	Refer to the response codes
errorMessage	String	NO	Error message
data	JSON Object	NO

Description of data field

Field	Data Type	Required	Description
uploadUrl	String	YES	File upload URL
storageUri	String	YES	File storage URI
uploadNo	String	YES	Upload number
formFields	JSON Object	YES	Upload form fields
httpMethod	String	YES	HTTP method for upload URL

TIP

Note: The number and content of fields in formFields may change dynamically based on business needs. In production, it is recommended to use the actual content returned in each response. The examples may list fields explicitly for clarity.

Examples

Request

curl https://{{gateway_domain}}/pg/v2/file/generateUploadUrl \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=9e494e8a91bcdd08f18ad5b2cfdbfd5654f5c00c89f8216eebd7c1637b6ce01b,timestamp=1714128828114,nonce=C7CA27DC6D55DA935DFC8450C721CC99' \
  -d '{
    "filename": "test.jpg",
    "contentType": "image/jpeg",
    "scene": "DISPUTE_EVIDENCE"
}'

Response

HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=ac6ae72f8c46f5c2092c3dab9bb0e08b6cdb6d5e7ff8ad190499a8955d57f297,timestamp=1714128245401,nonce=28FA11BF8FD1309767551B4FD8A57BD5

{
    "code": "OK",
    "errorMessage": null,
    "data": {
      "uploadUrl": "https://example.com/uploadUrl",
      "storageUri": "s3://private/sssss/5fd6eeb2e00044e99f4a61eb0def66bf.jpg",
      "uploadNo": "260114201050-b9219808",
      "formFields": {
          "bucket": "private-assets",
          "key": "private/sssss/5fd6eeb2e00044e99f4a61eb0def66bf.jpg",
          "x-amz-algorithm": "AWS4-HMAC-SHA256",
          "x-amz-credential": "AKIA6GBMHJHZDEV2WLO7/20260114/ap-south-1/s3/aws4_request",
          "x-amz-date": "20260114T144050Z",
          "Content-Type": "image/jpeg",
          "tagging": "<Tagging><TagSet><Tag><Key>upload-no</Key><Value>260114201050-b9219808</Value></Tag></TagSet></Tagging>",
          "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wMS0xNFQxNDo1MDo1MC4zMjYzNjQ2MTRaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoicHJpdmF0ZS1hc3NldHMucm9tYXBheS5pbiJ9LHsia2V5IjoibS84MC9vcGVuL2Rpc3B1dGUtZXZpZGVuY2UvOGRlNjBmOGM4YmEyNGY4Yzk3NTM0ODBjMTAwYjZmN2MucGRmIn0seyJ4LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQTZHQk1ISkhaREVWMldMTzcvMjAyNjAxMTQvYXAtc291dGgtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDI2MDExNFQxNDQwNTBaIn0seyJDb250ZW50LVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYifSx7InRhZ2dpbmciOiI8VGFnZ2luZz48VGFnU2V0PjxUYWc+PEtleT51cGxvYWQtbm88L0tleT48VmFsdWU+MjYwMTE0MjAxMDUwLWI5MjE5ODA4PC9WYWx1ZT48L1RhZz48L1RhZ1NldD48L1RhZ2dpbmc+In0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyXV19",
          "x-amz-signature": "479f776b70fd8b427309283fb089679492f9d19fb86fdbfeb833f4a19393d46e"
      },
      "httpMethod": "POST"
    }
}

Execute Upload

After obtaining the upload credentials, upload the file using the uploadUrl, formFields, and httpMethod from the response in multipart/form-data format.

Important Note

The curl command below is just a demonstration example to illustrate the format and parameters of the upload request. In actual development, you should implement the upload logic using your project's programming language (e.g., Java, Python, Node.js, etc.).

curl Example (For Reference Only)

# This is a curl example demonstrating how to construct a multipart/form-data upload request
# In your actual project, implement the same logic using your programming language

curl "https://example.com/uploadUrl" \
  -X POST \
  -F "bucket=private-assets" \
  -F "key=private/sssss/5fd6eeb2e00044e99f4a61eb0def66bf.jpg" \
  -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
  -F "x-amz-credential=AKIA6GBMHJHZDEV2WLO7/20260114/ap-south-1/s3/aws4_request" \
  -F "x-amz-date=20260114T144050Z" \
  -F "Content-Type=image/jpeg" \
  -F "tagging=<Tagging><TagSet><Tag><Key>upload-no</Key><Value>260114201050-b9219808</Value></Tag></TagSet></Tagging>" \
  -F "policy=eyJleHBpcmF0aW9uIjoiMjAyNi0wMS0xNFQxNDo1MDo1MC4zMjYzNjQ2MTRaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoicHJpdmF0ZS1hc3NldHMucm9tYXBheS5pbiJ9LHsia2V5IjoibS84MC9vcGVuL2Rpc3B1dGUtZXZpZGVuY2UvOGRlNjBmOGM4YmEyNGY4Yzk3NTM0ODBjMTAwYjZmN2MucGRmIn0seyJ4LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQTZHQk1ISkhaREVWMldMTzcvMjAyNjAxMTQvYXAtc291dGgtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDI2MDExNFQxNDQwNTBaIn0seyJDb250ZW50LVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYifSx7InRhZ2dpbmciOiI8VGFnZ2luZz48VGFnU2V0PjxUYWc+PEtleT51cGxvYWQtbm88L0tleT48VmFsdWU+MjYwMTE0MjAxMDUwLWI5MjE5ODA4PC9WYWx1ZT48L1RhZz48L1RhZ1NldD48L1RhZ2dpbmc+In0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyXV19" \
  -F "x-amz-signature=479f776b70fd8b427309283fb089679492f9d19fb86fdbfeb833f4a19393d46e" \
  -F "file=@/path/to/your/test.jpg"
#         ↑ The @ symbol is curl-specific syntax, indicating the following is a local file path
#         /path/to/your/test.jpg should be replaced with the actual file path on your computer
#         Example for Windows: C:\Users\neo\Desktop\evidence.jpg
#         Example for macOS/Linux: /home/neo/documents/evidence.jpg

Programming Language Implementation Reference

Below are implementation guidelines for popular programming languages. Adjust according to your project's specific requirements:

Java

// Using Apache HttpClient

// 1. Create MultipartEntityBuilder
MultipartEntityBuilder builder = MultipartEntityBuilder.create();

// 2. Iterate through formFields and add all fields to the form
for (Map.Entry<String, String> entry : formFields.entrySet()) {
    builder.addTextBody(entry.getKey(), entry.getValue());
}

// 3. Add the file field last (must be the last field)
File file = new File("/Users/neo/Desktop/evidence.jpg"); // ← Your local file path
builder.addBinaryBody("file", file, ContentType.parse(contentType), file.getName());

// 4. Send POST request to uploadUrl
HttpPost request = new HttpPost(uploadUrl);
request.setEntity(builder.build());
HttpResponse response = httpClient.execute(request);

PHP

<?php
// Using cURL extension

// 1. Prepare local file (replace with your actual file path)
$filePath = '/Users/neo/Desktop/evidence.jpg';

// 2. Construct form data (all formFields + file field last)
$postFields = [
    'bucket' => $formFields['bucket'],
    'key' => $formFields['key'],
    // ... all other fields from formFields
    'file' => new CURLFile($filePath, $contentType, basename($filePath))
];

// 3. Initialize cURL and send request
$ch = curl_init($uploadUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Node.js

const FormData = require('form-data');
const fs = require('fs');
const path = require('path');
const axios = require('axios');

(async () => {
    // 1. Create FormData object
    const formData = new FormData();

    // 2. Add all fields from formFields
    Object.entries(formFields).forEach(([key, value]) => {
        formData.append(key, value);
    });

    // 3. Add file field last (replace with your actual file path)
    const filePath = '/Users/neo/Desktop/evidence.jpg';
    formData.append('file', fs.createReadStream(filePath), {
        filename: path.basename(filePath),
        contentType,
    });

    // 4. Send POST request
    const response = await axios.post(uploadUrl, formData, {
        headers: formData.getHeaders(),
        maxBodyLength: Infinity,
        maxContentLength: Infinity,
    });
})();

Go

package main

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

// 1. Create multipart writer
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)

// 2. Add all fields from formFields
for key, value := range formFields {
    _ = writer.WriteField(key, value)
}

// 3. Add file field last (replace with your actual file path)
filePath := "/Users/neo/Desktop/evidence.jpg"
file, _ := os.Open(filePath)
defer file.Close()
part, _ := writer.CreateFormFile("file", filepath.Base(filePath))
io.Copy(part, file)
writer.Close()

// 4. Send POST request
req, _ := http.NewRequest("POST", uploadUrl, body)
req.Header.Set("Content-Type", writer.FormDataContentType())
client := &http.Client{}
resp, _ := client.Do(req)

C#

using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;

// 1. Create MultipartFormDataContent
using var formData = new MultipartFormDataContent();

// 2. Add all fields from formFields
foreach (var field in formFields)
{
    formData.Add(new StringContent(field.Value), field.Key);
}

// 3. Add file field last (replace with your actual file path)
var filePath = "/Users/neo/Desktop/evidence.jpg";
using var fileStream = File.OpenRead(filePath);
var fileContent = new StreamContent(fileStream);
fileContent.Headers.ContentType = new MediaTypeHeaderValue(contentType);
formData.Add(fileContent, "file", Path.GetFileName(filePath));

// 4. Send POST request
using var client = new HttpClient();
var response = await client.PostAsync(uploadUrl, formData);

Key Points

1. The file field must be placed at the end of the form, otherwise the upload will fail
2. All fields in formFields must be passed as-is, do not modify or omit any fields
3. The request Content-Type must be multipart/form-data (most HTTP libraries set this automatically)
4. On successful upload, the response HTTP status code is 204 No Content with no response body