# 概述
## 目的
本文檔定義了如下接口：商戶網站與 ptpay 支付平臺間的支付接口、商戶網站與 ptpay 支付平臺間
的支付結果通知接口（包括：服務器后臺異步通知接口）、商戶網站與 ptpay 支付平臺間的單筆交易查
詢接口。
## 術語與縮略語
appId : 商戶在商戶平臺創建應用的唯一標識
appKey : 商戶在商戶平臺創建應用時自動生成的密鑰
BTC：數字貨幣比特幣
ETH：數字貨幣以太幣
LTC：數字貨幣萊特幣
BCH：數字貨幣比特幣現金
USDT：數字貨幣泰達幣
EOS：數字貨幣 EOS
TATO：數字貨幣 TATO
POC：數字貨幣POC
* 目前 appId 以及 appKey 由商戶申請，由商戶平臺生成并分發至商戶。
## 適用范圍
本文檔適用的支付幣種包括：BTC、EOS、ETH、LTC、BCH、USDT、TATO、POC
## 接口清單
| 序號 | 接口名稱 | 接口描述 |
| --- | --- | --- |
| 1 | 支付接口 | 定義商戶網站與 ptpay 支付平臺間支付交易接口。 |
| 2 | 支付結果通知接口 | 定義商戶網站與 ptpay 支付平臺間的支付結果通知接口，包括：服務器后臺異步通知接口. |
| 3 | 交易查詢接口 | 定義商戶網站與 ptpay 支付平臺間的單筆交易查詢接口。 |
## 報文格式
為保證安全，使用 https 協議傳輸，使用 post 提交數據，content-type 必須為 application/json，請求參數以 json 格式放置于 body 內傳輸。接口返回統一為 json:
{
code : int , //錯誤碼（0 為成功，其他為失敗）
message : string , //錯誤原因
data : object //請求成功的結果
}
## 簽名方式
### 簽名按如下步驟生成
1. 設所有發送的數據為集合 M , 將集合 M 內非空參數值的參數按照參數名 ASCII 碼從小到大排序
（字典序 , 使用 URL 鍵值對的格式（即 key1=value1&key2=value2…）拼接成字符串 stringA .
注意以下重要規則 ：
* 參數名 ASCII 碼從小到大排序（字典序）.
* 如果參數的值為空不參與簽名 .
* 參數名區分大小寫 .
* 驗證調用返回或主動通知簽名時 , 傳送的 sign 參數不參與簽名 , 將生成的簽名與該 sign 值作校驗 .
* 接口可能增加字段 , 驗證簽名時必須支持增加的擴展字段 .
2. 在 stringA 賦值得到 stringSignTemp 字符串 , 并對 stringSignTemp 進行 HMAC\_SHA256 算法運算，再將得到的字符串所有字符轉換為小寫，得到 sign 值 signValue.
示例:
假設傳送的參數如下 :
{
"appId":"pt2d485db1ee8a4beeab761c883faa73c2",
"title":" Texas Hold'em Diamond Purchase ",
"mchOrderId":"73649d7a8e4811e8a879001a7dda7111",
"currency":"BTC",
"amount":"0.00001",
"deviceIp":"10.10.10.10",
"notifyUrl": "[http://hello](http://hello/)",
"nonce": "73649d7b8e4811e89c11001a7dda7111",
"timestamp": 1562499372
}
第一步 、對參數按照 key=value 的格式 , 并按照參數名 ASCII 字典序排序如下 ：
stringA = `"amount=0.00001&appId=pt2d485db1ee8a4beeab761c883faa73c2¤cy=BTC&deviceIp=10.10.10.10&mchOrderId=73649d7a8e4811e8a879001a7dda7111&nonce=73649d7b8e4811e89c11001a7dda7111¬ifyUrl=http://hello×tamp=1532330245&title=Texas Hold'em Diamond Purchase "`
第二步、使用 HMAC\_SHA256 算法簽名 ：
stringSignTemp=stringA
sign=HMAC\_SHA256(stringSignTemp, key) //HMAC\_SHA256 算法簽名，key 為商戶應用密鑰
最終得到最終發送的數據 ：
{
"appId": "pt2d485db1ee8a4beeab761c883faa73c2",
"title": " Texas Hold'em Diamond Purchase ",
"mchOrderId": "73649d7a8e4811e8a879001a7dda7111",
"currency":"BTC",
"amount":"0.00001",
"deviceIp":"10.10.10.10",
"notifyUrl": "[http://hello](http://hello/)",
"nonce": "73649d7b8e4811e89c11001a7dda7111",
"timestamp": 1562499372,
"sign": "6e1b8019e0c132bb6b215c1c250b49a0a6f3fb6b17b0285b4ce385f0835a529b"
}
## 接口定義
### 支付交易接口
#### 描述
定義商戶網站與 ptpay 支付平臺間的支付交易接口 , 商戶網站按照接口規范定義將交易訂單數據提交到 ptpay api 支付網關 , 以 HTTPS POST 方式提交數據.
#### 接口參數定義
* 交易請求地址: https://waltapi.ptwlt.me/ptpay/order
請求參數中的參數編碼僅限于UTF-8 .
請求參數：
| 參數 | 參數名稱 | 類型(長度) | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| appId | 商戶應用 ID | string(34) | 是 | 商戶在商戶后臺創建應用的 appId . 例 : 1ce78f96ed4748eebd63d6cc97a74839 |
| nonce | 隨機字符串 | string(32) | 是 | 防止重復隨機字符串 . 例 ：73649d7b8e4811e89c11001a7dda7111 |
| timestamp | 時間戳 | int(64) | 是 | 服務器當前時間戳(單位秒) . 例:1532330245 |
| title | 商品描述 | string(64) | 是 | 用于 ptpay 支付界面顯示商品名稱 . 例 : 德州撲克鉆石購買 |
| mchOrderId | 商戶訂單 ID | string(32) | 是 | 要求 32 個字符內 , 只能是數字 、 大小寫字母且在同一個商戶號下唯一 . 例 ：73649d7a8e4811e8a879001a7dda7111 |
| openId | 授權ID | string(32) | 否 | 用戶授權成功后返回的openId . 例 ：SEC7syJ6TuG90Iawd9ea2A== |
| currency | 幣種 | string(8) | 是 | 渠道所支持的幣種 . 例 ：BTC |
| amount | 訂單金額 | string(32) | 是 | 訂單金額 , 數字貨幣個數為單位 . 例 ：0.0001 |
| deviceType | 設備類型 | string(32) | 否 | 用戶設備終端類型 . 例：IOS |
| deviceId | 設備 ID | string(32) | 否 | 用戶設備 ID . 例：device-01 |
| deviceIp | 設備 IP | string(64) | 是 | 用戶設備 IP , 例：10.10.10.10 |
| notifyUrl | 通知地址 | string(255) | 是 | 支付異步通知回調地址 , 通知地址必須為直接可訪問的地址 , 不能攜帶參數 . 例 :[http://hello.notify.com](http://hello.notify.com/) |
| redirectUrl | 支付成功后跳轉地址 | string(255) | 否 | 客戶支付成功后 , 頁面跳轉商戶地址 . 例（APP 端）: yyyyyy://paid yyyyy ：商戶自定義短域名然后會根據商戶提供進行拼接 , 返回三方APP yyyyyy://paid?order=xxxxxx&errno=norder 為訂單 ID , 從商戶下單接口返回參數中獲取 errno 為本次支付狀態 , 0 成功/1 用戶取消/2 其他錯誤 |
| sign | 簽名 | string(64) | 是 | 參數簽名 , 詳見章節 6 簽名算法 .例: 6e1b8019e0c132bb6b215c1c250b49a0a6f3fb6b17b0285b4ce385f0835a529b . |
響應參數：
| 參數 | 參數名稱 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| code | 返回狀態碼 | int | 是 | 返回狀態碼 ：0 為成功，其他非成功狀態 , 具體異常參見狀態碼說明 . |
| message | 返回信息描述 | string | 否 | 返回信息描述 , 非成功狀態不為空 . |
| data | 返回結果 | json | 否 | 返回結果 , 成功狀態不為空 . |
當交易處理成功時 , 返回 data 數據格式如下 ：
| 參數 | 參數名稱 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| url | 支付地址 | string | 是 | 商戶跳轉至 ptpay 的支付地址 . 例 ：pt://pay?order=xxxxxx
[BS：如果是小程序，請按照《小程序開發說明》拉起支付的方法](https://developer.potato.im/#/docs/applet#payment) |
| orderId | ptpay 訂單號 | string | 是 | ptpay 訂單號 |
### 商戶支付通知
#### 描述
支付完成后 , ptpay 會把相關支付結果和用戶信息發送給商戶 , 商戶需要接收處理 , 并返回應答.對后臺通知交互時 , 如果 ptpay 收到商戶的應答不是成功或超時 , ptpay 認為通知失敗 , ptpay 會通過一定的策略定期重新發起通知 , 盡可能提高通知的成功率 , 但 ptpay 不保證通知最終能成功 .
* 注意 ：同樣的通知可能會多次發送給商戶系統 . 商戶系統必須能夠正確處理重復的通知 .
推薦的做法是 , 當收到通知進行處理時 , 首先檢查對應業務數據的狀態 , 判斷該通知是否已經處理過 , 如果沒有處理過再進行處理 , 如果處理過直接返回結果成功 . 在對業務數據進參數簽名行狀態檢查和處理之前 , 要采用數據鎖進行并發控制 , 以避免函數重入造成的數據混亂 .
特別提醒 ：商戶系統對于支付結果通知的內容一定要做簽名驗證 , 并校驗返回的訂單金額是否與商戶側的訂單金額一致 , 防止數據泄漏導致出現 " 假通知 " , 造成資金損失 .
請求地址 ：該鏈接是通過下單接口中提交的參數 notifyUrl 設置 , 如果鏈接無法訪問 , 商戶將無法接收到通知.
#### 接口參數定義
通知參數 ：
| 參數 | 參數名稱 | 類型（長度） | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| appId | 商戶應用 ID | string(34) | 是 | 商戶在商戶后臺創建應用的 appId .例: 1ce78f96ed4748eebd63d6cc97a74839 |
| mchOrderId | 商戶訂單號 | string(32) | 是 | 要求 32 個字符內 , 只能是數字、大小寫字母且在同一個商戶號下唯一 . 例 ：73649d7a8e4811e8a879001a7dda7111 |
| currency | 幣種 | string(8) | 是 | 渠道所支持的幣種 . 例：BTC |
| amount | 訂單金額 | string(32) | 是 | 訂單金額 , 數字貨幣個數字符串 . 例：0.00001 |
| nonce | 隨機字符串 | string(32) | 是 | 防止重復隨機字符串 . 例 ：73649d7b8e4811e89c11001a7dda7111 |
| timestamp | 時間戳 | int(64) | 是 | 服務器當前時間戳(單位秒) . 例:1532330245 |
| orderId | ptpay 訂單號 | string(32) | Yes | ptpay 支付頁面顯示的訂單號 . 例 ：2019062910737174223 |
| time | 下單時間 | int(32) | 是 | 商戶下單時間（時間戳秒）. 例:1532330245 |
| finishTime | 支付完成時間 | int(32) | 是 | 支付完成時間 ( 時間戳秒 ) . 例：1562553723 |
| status | 訂單狀態 | int(8) | 是 | 訂單支付狀態 . 例：1 |
| sign | 簽名 | string(64) | Yes | 參數簽名，詳見章節 6 簽名算法 . 例 ：6e1b8019e0c132bb6b215c1c250b49a0a6f3fb6b17b0285b4ce385f0835a529b |
* 響應參數：
商戶成功處理后必須返回字符串 " success " , 否則 ptpay 認為通知失敗，根據重試的策略重新發送通知 .
## 商戶查單接口
### 描述
定義商戶網站與 ptpay 支付平臺間的單筆交易查詢接口 .
注意：該接口用于商戶的異常訂單對賬，有訪問頻次限制，請不要用于用戶交易時的訂單狀態輪詢 .
### 接口參數定義
* 交易請求地址 ：https://waltapi.ptwlt.me/ptpay/order/query
請求參數中的參數編碼僅限于 UTF-8 .
請求參數：
| 參數 | 參數名稱 | 類型（長度） | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| appId | 商戶應用 ID | string(34) | 是 | 商戶在商戶后臺創建應用的 appId . 例 ： 1ce78f96ed4748eebd63d6cc97a74839 |
| nonce | 隨機字符串 | string(32) | 是 | 防止重復隨機字符串 . 例 ：73649d7b8e4811e89c11001a7dda7111 |
| timestamp | 時間戳 | int(64) | 是 | 服務器當前時間戳 ( 單位秒 ) . 例 : 1532330245 |
| mchOrderId | 商戶訂單號 | string(32) | 是 | 要求 32 個字符內 , 只能是數字、大小寫字母且在同一個商戶號下唯一 . 例 ：73649d7a8e4811e8a879001a7dda7111 |
| sign | 簽名 | string(64) | 是 | 參數簽名 , 詳見章節 6 簽名算法 . 例： 6e1b8019e0c132bb6b215c11c250b49a0a6f3fb6b17b0285b4ce385f0835a529b |
響應參數 ：
| 參數 | 參數名稱 | 類型（長度） | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| code | 返回狀態碼 | int(32) | 是 | 返回狀態碼 ：0 為成功 , 其他非成功狀態 , 具體異常參見狀態碼說明 |
| message | 返回信息描述 | string | 否 | Return message , unsuccessful status is not empty. |
| data | 返回結果 | json | 否 | 返回結果 , 成功狀態不為空 . |
當交易處理成功時 , 返回 data 數據格式如下:
| 參數 | 參數名稱 | 類型（長度） | 必填 | 說明 |
| --- | --- | --- | --- | --- |
| appId | 商戶應用 ID | string(34) | 是 | 商戶在商戶后臺創建應用的 appId . 例: 1ce78f96ed4748eebd63d6cc97a74839 |
| mchOrderId | 商戶訂單號 | string(32) | 是 | 要求 32 個字符內 , 只能是數字、大小寫字母且在同一個商戶號下唯一 . 例 ：73649d7a8e4811e8a879001a7dda7111 |
| orderId | ptpay 訂單號 | string(32) | 是 | ptpay 支付頁面顯示的訂單號 . 例 ：2019062910737174223 |
| currency | 幣種 | string(8) | 是 | 渠道所支持的幣種 . 例：BTC |
| amount | 訂單金額 | string(32) | 是 | 訂單金額 , 數字貨幣個數字符串 . 例：0.00001 |
| time | 下單時間 | int(64) | 是 | 商戶下單時間（時間戳秒）. 例:1532330245 |
| finishTime | 支付完成時間 | int(64) | 否 | 支付完成時間（時間戳秒）. 例：1562553723 |
| status | 訂單狀態 | int(8) | 是 | 訂單狀態 ( 0 ： 待支付 、1 ：已支付、2：支付取消) 例：1 |
## 附錄
響應碼說明
| code | 含義 |
| --- | --- |
| 0 | 調用成功 |
| 1 | 未知錯誤 |
| 2 | 參數非法 |
| 3 | 服務器錯誤 |
| 4 | 請求頻繁 |
| 7 | 無效的 APPID |
| 8 | 支付功能未開通 |
| 9 | 無效的openId |
| 32 | 商戶該幣種暫不支持 |
| 33 | 簽名錯誤 |
| 34 | 商戶訂單已存在 |
| 35 | 商戶訂單不存在 |