> For the complete documentation index, see [llms.txt](https://apidoc.tokenpay.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.tokenpay.me/ru-ru/opisanie/sozdanie-podpisi.md). # Создание подписи {% hint style="info" %} ПОДСКАЗКА (TIP) Продавцы могут выполнить следующие шаги для создания подписи запроса, и платформа проверит подпись после получения запроса. Если проверка подписи не пройдена, запрос отклоняется и возвращается соответствующий [код состояния](/ru-ru/kod-oshibki/kod-sostoyaniya.md) (status code). {% endhint %} ### Подготовка (Preparation) Продавцам необходимо зарегистрировать номер продавца и создать платежное приложение через панель управления продавца (бэкофис), чтобы получить `APP_ID` и `APP_SECRECT`. ### Условие (Condition) Все интерфейсы метода `POST` в этом документе требуют проверки подписи, остальные интерфейсы пока не требуют проверки. ### Создание (Generation) Строка подписи состоит из четырех строк, по одному параметру на строку. Строка заканчивается на `\n` (перенос строки, значение кодировки ASCII равно 0x0A), и не добавляйте `\n` в последнюю строку. Если сам параметр заканчивается на `\n`, вам также нужно добавить `\n`. ``` URL\n Request timestamp\n Request random string\n Request message body ``` Возьмем в качестве примера [запрос заказа](/ru-ru/zakaz/zapros-zakaza.md) (order inquiry). Первый шаг — получить абсолютный URL-адрес запроса и удалить часть доменного имени, чтобы получить участвующий подписанный URL. Если в запросе есть параметры запроса, к URL-адресу следует добавить '? ' и соответствующую строку запроса. ``` /v1/transaction/query ``` Второй шаг — получить текущую временную метку (в миллисекундах) системы при инициировании запроса. То есть общее количество секунд с 00:00:00 GMT 1 января 1970 года до настоящего времени в качестве временной метки запроса. Платформа откажется обрабатывать запросы, сделанные давно, пожалуйста, следите за точностью времени в собственной системе продавца. ``` 1554208460 ``` Третий шаг — сгенерировать 32-битную `случайную строку (random` ``` 593BEC0C930BF1AFEB40B4A08C8FB242 ``` Четвертый шаг — получить тело сообщения запроса в самом запросе (request body). ```json { "app_id": "8e4b8c2e7cxxxxxxxx1a1cbd3d59e0bd", "mch_id": "12345678", "transaction_id": "e98b30294xxxxxxxxxxxx97a9d9e09ce", "out_trade_no": "fb72xxxx-xxxx-xxxx-xxxx-xxxx8a7b52cb" } ``` Пятый шаг — составить строку подписи запроса в соответствии с предыдущими правилами следующим образом: ```html /v1/transaction/query\n 1554208460\n 593BEC0C930BF1AFEB40B4A08C8FB242\n {"app_id":"8e4b8c2e7cxxxxxxxx1a1cbd3d59e0bd","mch_id":"12345678","transaction_id":"e98b30294xxxxxxxxxxxx97a9d9e09ce","out_trade_no":"fb72xxxx-xxxx-xxxx-xxxx-xxxx8a7b52cb"} ``` ### Шифрование (Encryption) Возьмем в качестве примера процесс шифрования javascript: ```json let cryptoJs = require("crypto-js"); let key = CryptoJS.enc.Utf8.parse("9db664697xxxxxxxxxxxx2d27a3c925c") //the secret key of APP //AES encryption let ciphertext = cryptoJs.AES.encrypt(Signature string, key, { mode: CryptoJS.mode.ECB, padding: CryptoJS.pad.Pkcs7, }).toString(); ``` Пример после шифрования: ``` QCwHvoBM9TJ2wokF8hhaoS34P0nkJpYMisBUizpOj5q/77I6+KFPVvFUCaaUiu+KFctisJFU1DfJdCHrLpJIx9CirX5ku3L9TMGihFcEG8MGoh2dwDvunH8JgJOVV9ClSkpXqjad4flSuYMoxPOZqPHr+ktOLZ3pPzs12BMqmbZVNIe+oOezTZsQ8xxxxRgOJzwU/AbouZSl2xto7DcYCjvNSnw7BkuzBFgTfxVXB3+R7e+1SpdeJajuCKGKvYMVTe7slS5j/4LQ4vcr1QqOPhpoemsOV92tPhgQ0iGw3GKpLIEOoDAwy2+ojzP5XERh ``` ### Объединение (Concatenate) Формат объединения информации о подписи следующий: app\_id=`APP_ID`, mch\_id=`ID Продавца`, nonce\_str=`Случайная строка, созданная на шаге 3`, timestamp=`Временная метка, созданная на шаге 2`, signature=`Криптографическая строка подписи`. ### HTTP-заголовок (HTTP header) API документа передает подпись через HTTP-заголовок `Authorization`. `Authorization` состоит из двух частей: `типа аутентификации` и `информации о подписи`. В настоящее время `тип аутентификации` поддерживает только `TTPAY-AES-256-ECB`. ``` Authorization: authentication type signature information ``` Заголовок авторизации следующий: (Примечание: это пример, так как верстка может содержать переносы строк, фактические данные должны быть в одной строке) ``` Authorization: TTPAY-AES-256-ECB app_id=8e4b8c2e7cxxxxxxxx1a1cbd3d59e0bd,mch_id=12345678,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,timestamp=1554208460,signature=QCwHvoBM9TJ2wokF8hhaoS34P0nkJpYMisBUizpOj5q/77I6+KFPVvFUCaaUiu+KFctisJFU1DfJdCHrLpJIx9CirX5ku3L9TMGihFcEG8MGoh2dwDvunH8JgJOVV9ClSkpXqjad4flSuYMoxPOZqPHr+ktOLZ3pPzs12BMqmbZVNIe+oOezTZsQ8xxxxRgOJzwU/AbouZSl2xto7DcYCjvNSnw7BkuzBFgTfxVXB3+R7e+1SpdeJajuCKGKvYMVTe7slS5j/4LQ4vcr1QqOPhpoemsOV92tPhgQ0iGw3GKpLIEOoDAwy2+ojzP5XERh" ``` Наконец, мы можем создать HTTP-запрос, который содержит подпись. ```sh $ curl https://api.tokenpay.me/v1/transaction/query -H "Content-Type: application/json" -H 'Authorization: TTPAY-AES-256-ECB app_id=8e4b8c2e7cxxxxxxxx1a1cbd3d59e0bd,mch_id=12345678,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,timestamp=1554208460,signature=QCwHvoBM9TJ2wokF8hhaoS34P0nkJpYMisBUizpOj5q/77I6+KFPVvFUCaaUiu+KFctisJFU1DfJdCHrLpJIx9CirX5ku3L9TMGihFcEG8MGoh2dwDvunH8JgJOVV9ClSkpXqjad4flSuYMoxPOZqPHr+ktOLZ3pPzs12BMqmbZVNIe+oOezTZsQ8xxxxRgOJzwU/AbouZSl2xto7DcYCjvNSnw7BkuzBFgTfxVXB3+R7e+1SpdeJajuCKGKvYMVTe7slS5j/4LQ4vcr1QqOPhpoemsOV92tPhgQ0iGw3GKpLIEOoDAwy2+ojzP5XERh' -X POST -d '{"out_trade_no": "fb72xxxx-xxxx-xxxx-xxxx-xxxx8a7b52cb", "transaction_id":"e98b30294xxxxxxxxxxxx97a9d9e09ce", "app_id":"8e4b8c2e7cxxxxxxxx1a1cbd3d59e0bd", "mch_id":"12345678" }' ``` ### Демонстрационный код (Demo code) {% tabs %} {% tab title="Java" %} ```java package com.example.http; import com.alibaba.fastjson.JSONException; import com.alibaba.fastjson.JSONObject; import com.sun.istack.internal.NotNull; import okhttp3.*; import org.bouncycastle.jce.provider.BouncyCastleProvider; import javax.crypto.Cipher; import javax.crypto.spec.SecretKeySpec; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.security.Security; import java.util.Base64; public class HttpApplication { private static String SECRET = "AES"; private static String CIPHER_ALGORITHM = "AES/ECB/PKCS7Padding"; private static String schema = "TTPAY-AES-256-ECB "; public static void main(String[] args) throws Exception { String key = "xxxxxxxx"; // AppSecret String reqURL = "/v1/transaction/query"; // Request interface OkHttpClient client = new OkHttpClient(); JSONObject params = new JSONObject(); try { params.put("app_id", "xxxxxxxx"); // Application ID params.put("mch_id", "xxxxxxxx"); // Merchat ID params.put("transaction_id", "xxxxxxxx"); // Platform order number params.put("out_trade_no", "xxxxxxxx"); // Merchat order number } catch (JSONException e) { e.printStackTrace(); } Security.addProvider(new BouncyCastleProvider()); // Signature String auth = auth(reqURL, params, key); RequestBody body = RequestBody.create(MediaType.parse("application/json;charset=utf-8"), params.toString()); Request request = new Request.Builder() .header("Authorization", auth) .url(reqURL) .post(body) .build(); client.newCall(request).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { System.out.println("http request error"); } @Override public void onResponse(@NotNull Call call, @NotNull Response response) throws IOException { System.out.println(response.body().string()); } }); } /** * Signature * @param reqURL Request URL * @param raw Message body * @param key AppSecret * @return Signature information */ public static String auth(String reqURL, JSONObject raw, String key) throws Exception { HttpUrl parseReqURL = HttpUrl.parse(reqURL); String url = parseReqURL.encodedPath(); String appID = raw.getString("app_id"); String mchID = raw.getString("mch_id"); long currentTimeMillis = System.currentTimeMillis(); String timestamp = String.valueOf(currentTimeMillis); String nonceStr = randomString(32); String message = url + "\n" + timestamp + "\n" + nonceStr + "\n" + raw.toString(); String aes256ECBPkcs7PaddingEncrypt = aes256ECBPkcs7PaddingEncrypt(message, key); return schema + "app_id=" + appID + ",mch_id=" + mchID + ",nonce_str=" + nonceStr + ",timestamp=" + timestamp + ",signature=" + aes256ECBPkcs7PaddingEncrypt; } /** * Generate random string * @param len String length * @return Random string */ public static String randomString(Integer ...len) { int e = len.length <= 0 ? 32 : len[0]; String str = "ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678"; int strLen = str.length(); StringBuilder stringBuilder = new StringBuilder(); for (int i = 0; i < e; i++) { double random = Math.random(); int v = (int) Math.floor(random * strLen); char charAt = str.charAt(v); stringBuilder.append(charAt); } return stringBuilder.toString(); } /** * AES encryption * @param str String * @param key Secret key * @return Cryptographic string * @throws Exception Abnormal information */ public static String aes256ECBPkcs7PaddingEncrypt(String str, String key) throws Exception { Cipher cipher = Cipher.getInstance(CIPHER_ALGORITHM); byte[] keyBytes = key.getBytes(StandardCharsets.UTF_8); cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(keyBytes, SECRET)); byte[] doFinal = cipher.doFinal(str.getBytes(StandardCharsets.UTF_8)); return new String(Base64.getEncoder().encode(doFinal)); } /** * AES encryption * @param str String * @param key Secret key * @return Decryption string * @throws Exception Abnormal information */ public static String aes256ECBPkcs7PaddingDecrypt(String str, String key) throws Exception { Cipher cipher = Cipher.getInstance(CIPHER_ALGORITHM); byte[] keyBytes = key.getBytes(StandardCharsets.UTF_8); cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(keyBytes, SECRET)); byte[] doFinal = cipher.doFinal(Base64.getDecoder().decode(str)); return new String(doFinal); } } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "bytes" "encoding/base64" "encoding/json" "fmt" "io" "math/rand" "net/http" "time" "github.com/forgoer/openssl" ) const ( SignatureMessageFormat = "%s\n%d\n%s\n%s" // The original format of the digital signature HeaderAuthorizationFormat = "%s app_id=%s,mch_id=%s,nonce_str=%s,timestamp=%d,signature=%s" ) type QueryReq struct { AppID string `json:"app_id"` MchID string `json:"mch_id"` TransactionID string `json:"transaction_id,omitempty"` OutTradeNo string `json:"out_trade_no,omitempty"` } func main() { appSecret := "**********" // AppSecret reqPath := "/v1/transaction/query" // Request interface path queryReq := QueryReq{ AppID: "**********", // Application ID MchID: "**********", // Merchat ID TransactionID: "**********", // Platform order number OutTradeNo: "**********", // Merchat order number } b, _ := json.Marshal(queryReq) // Signature authorization, err := GenerateAuthorizationHeader(queryReq.AppID, queryReq.MchID, reqPath, string(b), appSecret) if err != nil { panic(err) } // Request interface url := "" + reqPath payload := bytes.NewBuffer(b) req, _ := http.NewRequest("POST", url, payload) req.Header.Set("Accept", "application/json") req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", authorization) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } // Signature func GenerateAuthorizationHeader(appID, mchID, reqURL, signBody, appSecret string) (string, error) { nonceStr := RandomString(32) timestamp := time.Now().Unix() message := fmt.Sprintf(SignatureMessageFormat, reqURL, timestamp, nonceStr, signBody) signatureResult, err := AesECBEncrypt(message, appSecret) if err != nil { return "", err } authorization := fmt.Sprintf( HeaderAuthorizationFormat, getAuthorizationType(), appID, mchID, nonceStr, timestamp, signatureResult, ) return authorization, nil } // AES encryption func AesECBEncrypt(orig, key string) (string, error) { dst, _ := openssl.AesECBEncrypt([]byte(orig), []byte(key), openssl.PKCS7_PADDING) return base64.StdEncoding.EncodeToString(dst), nil } // AES encryption func AesECBDecrypt(crypted, key string) (string, error) { x := len(crypted) * 3 % 4 switch { case x == 2: crypted += "==" case x == 1: crypted += "=" } crytedByte, err := base64.StdEncoding.DecodeString(crypted) if err != nil { return "", err } origData, err := openssl.AesECBDecrypt(crytedByte, []byte(key), openssl.PKCS7_PADDING) if err != nil { return "", err } return string(origData), err } // Generate random character func RandomString(length int) string { str := []byte("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") var result []byte rnd := rand.New(rand.NewSource(time.Now().UnixNano())) for i := 0; i < length; i++ { result = append(result, str[rnd.Intn(len(str))]) } return string(result) } func getAuthorizationType() string { return "TTPAY-AES-256-ECB" } ``` {% endtab %} {% tab title="PHP" %} ```php {% endtab %} {% tab title="JavaScript" %} ```javascript let cryptoJs = require("crypto-js"); let jsonObj = JSON.parse(pm.request.body.raw); //Convert the submitted body string into an object let jsonStr = JSON.stringify(jsonObj)//Turn the object back into a string to compress, avoiding line breaks in the body that affect signature compression. let appID = jsonObj.app_id; let mchID = jsonObj.mch_id; // Generate the current timestamp let timestamp = Math.round(new Date() / 1000).toString() //Define random string var nonceStr = randomString(); // Random string function randomString(e) { e = e || 32; var t = "ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678", a = t.length, n = ""; for (i = 0; i < e; i++) n += t.charAt(Math.floor(Math.random() * a)); return n } //Get the full path var reqURL = "/" + pm.request.url.path.join("/"); //Splice signature plaintext message = reqURL + "\n" + timestamp + "\n" + nonceStr + "\n" + jsonStr let key = CryptoJS.enc.Utf8.parse("********************************") // AppSecret //AES encryption let ciphertext = cryptoJs.AES.encrypt(message, key, { mode: CryptoJS.mode.ECB, padding: CryptoJS.pad.Pkcs7, }).toString(); //Splice on the authorization of Header, TTPAY-{EncryMode)},currently supports only AES-256-ECB let authorization = 'TTPAY-AES-256-ECB app_id=' + appID + ',mch_id=' + mchID + ',nonce_str=' + nonceStr + ',timestamp=' + timestamp + ',signature=' + ciphertext pm.request.headers.upsert({ key: "authorization", value: authorization }) ``` {% endtab %} {% endtabs %}