> ## Documentation Index
> Fetch the complete documentation index at: https://doc2.payloco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Upload Signing

> How to sign file upload requests using RSA

# File Upload Signing

## Overview

Payloco's open platform uses a public/private key mechanism. Merchants can configure their application's **public key** or **public key certificate** in the open platform under **Key Management** to prevent data tampering and ensure secure communication between the merchant application and Payloco.

## Terminology

1. **Public Key** — The application public key (`public_key`), generated by the developer using a key generation tool.
2. **Private Key** — The application private key (`private_key`), generated by the developer using a key generation tool.
3. **Payloco Platform Public Key** — Generated by Payloco after the developer uploads their application public key. Developers use this key to verify the signatures on asynchronous messages received from Payloco.

## Signing Algorithm

| Signing Method | Standard Algorithm | Description                                |
| :------------- | :----------------- | :----------------------------------------- |
| RSA            | SHA256WithRSA      | RSA key length must be at least 2048 bits. |

## Functional Overview

* If you are unfamiliar with the API calling conventions, please review the interface documentation first.

* Every API request must include a valid signature. The server validates the signature against the request parameters and rejects any request with an invalid signature. The purpose of signing is to:

  * Verify the integrity of request parameters on both the merchant and platform sides.
  * Verify the identity of the requester on both the merchant and platform sides.

## Signature Calculation

Signature calculation can be implemented using the code in the **Request Example** below. Payloco currently provides a Java reference implementation. If you are using a different language, implement the same logic accordingly.

## Signing Rules

1. **Fields included in the signature:** All parameters with non-empty values (value is not `null` and is not an empty string after trimming) are included. The `sign` field itself is excluded.
2. **Signature string assembly:** Sort parameter names alphabetically (dictionary order). Concatenate each key-value pair as `key=value` (using the trimmed value), and join multiple pairs with `&`. Example: `key1=val1&key2=val2&key3=val3`. The signature value is case-sensitive; MD5 produces a 32-character lowercase hex string.
3. **Signing algorithm:** MD5 or SHA256WithRSA.
4. **Signature placement:** The signature value must be placed in the request `Header`.

## Notes

* If request parameters contain non-ASCII characters (e.g., Chinese), the characters must be URL-encoded in the request, but should **not** be URL-encoded when computing the signature.
* When computing the SHA256WithRSA signature, the byte stream must be encoded in UTF-8. Failure to do so may result in incorrect signatures for parameters containing non-ASCII characters.

## Request Example

```
POST https://gate.uat.payloco.com/gateway/v1/merchant/open/api/file/upload
Host: gate.uat.payloco.com
Content-Type: multipart/form-data;charset=utf-8

charset=utf-8
&merchantId=202200000001
&requestTime=20220607125959
&signType=RSA
&signature=QxW4Q7LB+pxxIJEaTrgImZ+e6yPf4QVFVAYNXSxP2h9R0BrugR1FOIy3tUxAyCCH/rqD2vqvMC33oNaS6Zp+R06JidcegtR5gq/ZM/XSgD6PTFC05AO0BKLfmo56ypIAEh8n9EIH/XrzbwMlXD2qVkuEn+9k6GPGdWJa7IPzAmw=
&transType=UPLOAD
&version=2.0.0
```