# Signature Generation and Verification

## Key Distribution

Before starting integration, you need to first generate an RSA key pair, securely store the private key, and provide the public key to the relevant PayKKa platform contact.

Production key distribution process: TBD

## Constructing the Signature String

The signature string consists of five lines, each line representing one parameter. Each line ends with `\n` (newline character, ASCII code 0x0A), excluding the last line.

`Note: Signature string structure rules: one element per line. If an element is not applicable, do not include it, but the newline character is still required to maintain the structure. Always follow one element per line. If there is no element, a newline is still required, except for the last element.`

```text
Request path\n
Request timestamp\n
Request random string (nonce)\n
Merchant ID\n
Request body
```

### Request or Response Without a Body

```text
Request path\n
Request timestamp\n
Request random string (nonce)\n
Merchant ID
```

### Request Not Involving a Merchant ID

The merchant ID can be omitted, but the newline character is still required

```text
Request path\n
Request timestamp\n
Request random string (nonce)\n
\n
Request body
```

### Signature for File Uploads

The signature method for file uploads differs from other text-based APIs. When calculating the signature, the body used is the meta JSON string.

```text
Request path\n
Request timestamp\n
Request random string (nonce)\n
Merchant ID\n
Request meta JSON string
```

## Calculating the Signature Value

Most programming languages provide signature functions that support signing data. It is strongly recommended to use such functions, using your private key to perform `SHA256withRSA` signing on the signature string, and then `Base64-encode` the signature result to obtain the signature value.

## Setting HTTP Headers

- For requests involving a merchant, the `X-Merch-Id` request header must be set, containing the **merchant ID** assigned by the **PayKKa Cross-border Collection Open Platform**
- The request passes the signature through the HTTP `Authorization` header, whose content is a `URL-encoded` `JSON` object containing the following fields:


| Key | Format | Description |
|  --- | --- | --- |
| sign_type | String | Signature method (SHA256_WITH_RSA) |
| timestamp | String | Millisecond timestamp value when the request was generated (Milliseconds since Unix Epoch) |
| nonce | String(6-32) | Random string generated when the request was created, used for request deduplication |
| key_id | String | Platform-assigned key ID, corresponding to the client |
| signature | String | Request signature |