ChingchingPay 支付網關提供了一組 RESTful API,供商戶進行支付、退款、查詢等操作。本文檔旨在幫助開發者了解如何對接支付網關 API,包括接口對接方式、加密方式、鑑權方式,以及支持的交易通道和交易方式等。接口對接方式#
所有的 API 請求均為 HTTPS 請求,使用 JSON 格式的數據進行交互。
每個 API 請求都需要包含必要的鑑權信息和數據簽名,以保證數據的安全性和完整性。API 請求規範:#
鑑權方式#
每個 API 請求都需要進行鑑權,鑑權信息包含在 HTTP Request Header 中。Request Header 需包含以下字段:簽名加密方式#
API 請求的數據簽名使用 HMAC-SHA256 算法。簽名的生成需要用到商戶的 API 密鑰。具體步驟如下:支持的支付通道#
Channel:ALIPAY#
支持平臺:Alipay AlipayHK
通道配置:PaymentMethodOption不同類型支付參數定義#
AlipayMobileSecurityPayPaymentOptions 示例#
"{\"trade_information\":{\"business_type\":\"5\",\"other_business_type\":\"Bus Ticket\"},\"payment_inst\":\"AILPAYHK\",\"refer_url\":\"https:\/\/www.chingchingpay.com\"}"
AuthCodePaymentOptions 示例#
{\"auth_code\":\"288747107207804180\"}"
Alipay Hong Kong AutoDebit(自動扣款)#
支付寶香港自動扣款服務允許商戶在獲得用戶授權後,可以定期從用戶的支付寶賬戶中自動扣款,適用於訂閱服務、會員費、周期性付款等場景。支付方式#
授權流程#
1.
商戶通過 HK_ALIPAY_AUTODEBIT_PREPARE 發起授權請求,獲取授權URL
3.
支付寶將用戶重定向到商戶的回調URL (/autodebit/auth_redirect),並附帶授權碼(authCode)
4.
商戶使用授權碼通過 HK_ALIPAY_AUTODEBIT_TOKEN 獲取訪問令牌
5.
商戶使用訪問令牌通過 HK_ALIPAY_AUTODEBIT_PAY 發起自動扣款
6.
如需取消授權,商戶可以通過 HK_ALIPAY_AUTODEBIT_CANCELAUTH 取消自動扣款授權
商戶須知事項#
由於支付網關不會保存商戶的協議ID及訪問令牌等敏感資訊,商戶需要自行妥善保存以下關鍵資料:1.
商戶協議ID (merchantAgreementId):必須確保在商戶系統內唯一,建議與用戶帳號或訂閱關係關聯
需要在商戶系統中長期保存,用於後續的查詢授權狀態、發起扣款和取消授權等操作
2.
訪問令牌 (accessToken) 及刷新令牌 (refreshToken):通過授權碼獲取的訪問令牌及其相關資訊必須由商戶自行保存
refreshToken:用於在訪問令牌過期後獲取新的訪問令牌
3.
商戶必須自行實現授權回調頁面 (即 redirectUrl 所指向的頁面)
該頁面需要能夠接收並處理支付寶重定向帶回的參數 (state, authCode, merchantAgreementId 等)
商戶應在收到授權碼後立即調用獲取訪問令牌的接口,並將令牌安全地保存在商戶系統中
建議在成功獲取訪問令牌後,向用戶展示授權成功的提示訊息
接口說明#
1. 授權準備請求 (HK_ALIPAY_AUTODEBIT_PREPARE)#
{
"transaction_type": "command",
"payment_method": "HK_ALIPAY_AUTODEBIT_PREPARE",
"payment_method_options": "{\"state\":\"unique_state_for_verification\",\"merchant_agreement_id\":\"agreement_id_for_this_authorization\",\"redirect_url\":\"https://your-redirect-url.com/auth_callback\"}"
}
回應中會返回一個授權URL,商戶需要將用戶引導至該URL進行授權。2. 授權回調 (商戶自行實現的回調頁面)#
當用戶在支付寶APP中完成授權後,支付寶會將用戶重定向到商戶在請求中提供的redirect_url(即由商戶自行實現的回調頁面),並附帶以下參數:| 參數名 | 描述 | 類型 | 必須 | 備註 | 範例 |
|---|
| state | 商戶在授權請求中提供的狀態值 | string | 是 | 用於防止CSRF攻擊 | 4657DDUER323DK |
| auth_site | 授權用戶的站點 | string | 是 | 固定值 | ALIPAY_HK |
| merchantAgreementId | 商戶在授權請求中提供的協議ID | string | 是 | | e8qdwl9casxor13 |
| authCode | 支付寶返回的一次性授權碼 | string | 是 | 用於獲取訪問令牌 | 28100413kpBklrvUk33YgGgC9yS2o679 |
| client_id | 授權商戶ID | string | 是 | | 2160400000002012 |
3. 獲取訪問令牌 (HK_ALIPAY_AUTODEBIT_TOKEN)#
{
"transaction_type": "command",
"payment_method": "HK_ALIPAY_AUTODEBIT_TOKEN",
"payment_method_options": "{\"auth_code\":\"authorization_code_from_redirect\"}"
}
回應中會包含訪問令牌(accessToken)、刷新令牌(refreshToken)、過期時間等信息。{
"code": 0,
"message": "success",
"data": {
"payment_id": "",
"transaction_id": "",
"transaction_type": "command",
"merchant_reference": "",
"payment_reference": "",
"result": "completed",
"message": "Access token obtained successfully",
"next_action": {
"type": "alipay_auto_debit",
"alipay_auto_debit": {
"access_token": "access_token",
"expires_in": "2037-12-31T16:00:48-08:00",
"refresh_token": "refresh_token",
"re_expires_in": "2037-12-31T16:00:48-08:00",
"token_status": "ACTIVE",
"auth_site_user_id": "auth_site_user_id"
}
}
}
}
4. 發起自動扣款 (HK_ALIPAY_AUTODEBIT_PAY)#
{
"transaction_type": "command",
"payment_method": "HK_ALIPAY_AUTODEBIT_PAY",
"payment_method_options": "{\"access_token\":\"access_token_from_previous_step\"}"
}
5. 取消授權 (HK_ALIPAY_AUTODEBIT_CANCELAUTH)#
{
"transaction_type": "command",
"payment_method": "HK_ALIPAY_AUTODEBIT_CANCELAUTH",
"payment_method_options": "{\"merchant_agreement_id\":\"agreement_id_to_cancel\"}"
}
如需接收取消授權通知,需提供回調URL,會POST請求以下參數:{
"merchant_agreement_id": "12345456",
"cancel_time": "2025-03-26 06:22:41"
}
6. 查詢授權狀態 (HK_ALIPAY_AUTODEBIT_QUERYAUTH)#
{
"transaction_type": "command",
"payment_method": "HK_ALIPAY_AUTODEBIT_QUERYAUTH",
"payment_method_options": "{\"merchant_agreement_id\":\"agreement_id_to_query\"}"
}
Channel:Wechat Pay#
PaymentMethodOption不同類型支付參數定義#
AuthCodePaymentOptions 示例#
{\"auth_code\":\"288747107207804180\"}"
MiniProgramPaymentOptions 示例#
"{\"openid\": \"openid-123456\", \"appid\": \"appid-123456\"}"
WechatAuthCodePaymentOptions 示例#
"{\"redirect_url\":\"https://www.xxxxx.xxx\"}"
WechatJsapiPaymentOptions 示例#
"{\"openid\":\"xxxxxx\"}" 或者 "{\"sub_openid\":\"xxxxxx\",\"sub_appid":\"xxxx\"}"
WechatInAppPaymentOptions 示例#
"{\"appid\": \"appid-123456\"}"
WeChatPayScorePaymentOptions 示例#
"{\"service_id\":\"0000200000000017551621615xxxxxxx\",\"risk_fund\":{\"name\":\"DEPOSIT\",\"amount\":200,\"description\":\"服務押金\"},\"sub_appid\":\"wxxxxxxxxxxxxx\",”\"openid\":\"openidxxxxxxxxx\",\"need_user_confirm\":true}"
"{\"service_id\":\"0000200000000017551621615xxxxxxx\",\"sub_appid\":\"wxxxxxxxxxxxxx\",\"post_payments\":[{\"name\":\"充電寶租金\",\"amount\":50,\"description\":\"30分鐘5角\",\"count\":1}],\"total_amount\":50}"
"{\"service_id\":\"0000200000000017551621615xxxxxxx\",\"sub_appid\":\"wxxxxxxxxxxxxx\"}"
Channel:Wechat Pay CN#
PaymentMethodOption不同類型支付參數定義#
AuthCodePaymentOptions 示例#
{\"auth_code\":\"288747107207804180\"}"
MiniProgramPaymentOptions 示例#
"{\"openid\": \"openid-123456\", \"appid\": \"appid-123456\"}"
WechatAuthCodePaymentOptions 示例#
"{\"redirect_url\":\"https://www.xxxxx.xxx\"}"
WechatJsapiPaymentOptions 示例#
"{\"openid\":\"xxxxxx\"}" 或者 "{\"sub_openid\":\"xxxxxx\",\"sub_appid":\"xxxx\"}"
WechatInAppPaymentOptions 示例#
"{\"appid\": \"appid-123456\"}"
Channel:QFPAY#
支持平臺:Visa,MasterCard,銀聯雲閃付,Payme,FPS
通道配置:Channel:GKASH#
支持平臺:Visa,MasterCard,QRCODE ,馬來西亞主流支付方式
通道配置:PaymentMethodOption不同類型支付參數定義#
GKASHPaymentOptions#
"{\"terminal_id\":\"M161-TD-xxxxx\",\"payment_id\":\"95\",\"openid\":\"類型為微信小程序時需要\"}"
payment_id 參數:
95 - TNG QR DISPLAY
72 - GRABPAY QR DISPLAY
69 - BOOST QR DISPLAY
86 - MAYBANK QR DISPLAY
46148 - WECHAT QR DISPLAY
84 - ALIPAY QR DISPLAY
98 - GKASH QR DISPLAY
46118 - SHOPEEPAY QR DISPLAY
46119 - DUITNOW QR DISPLAY
46124 - FINEXUS DUITNOW QR DISPLAY
46113 - ATOME QR DISPLAY
46122 - MCASH QR DISPLAY
46143 - SARAWAKPAY QR DISPLAY
46171 - WECHAT PAY MINI PROGRAM
"{\"terminal_id\":\"M161-TD-xxxxx\",\"qr_code\":\"95\"}"
交易回調#
ChingchingPay 在處理支付或退款交易後,會通過回調通知商戶交易結果。商戶需要提供一個回調地址(callback_url),ChingchingPay 會在交易完成後調用該地址並傳遞交易結果。商家回調接口需返回 Http Code 200 且body 返回 字符串 SUCCESS,表示 callback 处理成功;其他情况ChingchingPay任務不成功,並會依照一定的策略重新傳送,以最大限度地提高成功率,但不保證通知成功。通知頻率:15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h -總計24h4m回調請求#
ChingchingPay 會向商戶提供的回調地址發送一個 HTTP POST 請求,包含交易結果的 JSON 數據,並附帶簽名以驗證數據的完整性和來源。{
"payment_id": "string",
"transaction_id": "string",
"transaction_type": "string",
"amount": 12345,
"currency": "string",
"merchant_reference": "string",
"payment_reference": "string",
"result": "string",
"payer_id": "string",
"payed_time": 1234567890,
"timestamp": 1234567890,
"message": "string",
"extra": "string"
}
為了確保回調數據的完整性和來源,每個回調請求都會附帶一個簽名。簽名使用 HMAC-SHA256 算法生成,簽名的生成步驟如下:1.
將請求數據按鍵名排序,並拼接成 key=value&key=value 的形式。
2.
使用商戶的 API 密鑰進行 HMAC-SHA256 加密。
3.
將生成的簽名放在請求頭的 x-signature 字段中。
API 響應代碼參考#
響應格式#
成功響應#
{
"code": 0,
"message": "success",
"data": {
}
}
data: 包含具體的響應數據(根據不同 API 而異)
錯誤響應#
{
"code": 10002,
"message": "Required parameter missing"
}
HTTP 狀態碼: 根據錯誤類型返回相應的 HTTP 狀態碼(400、401、403、404、409、500、502)
🔢 HTTP 狀態碼#
| HTTP 狀態碼 | 說明 | 使用場景 |
|---|
| 200 | 成功 | 請求成功處理 |
| 400 | 請求錯誤 | 參數格式錯誤、業務邏輯驗證失敗 |
| 401 | 未授權 | 未提供認證信息或認證信息無效 |
| 403 | 禁止訪問 | 已認證但無權訪問該資源 |
| 404 | 資源未找到 | 請求的資源不存在 |
| 409 | 資源衝突 | 資源已存在(如訂單號重複) |
| 500 | 服務器錯誤 | 服務器內部錯誤 |
| 502 | 網關錯誤 | 支付通道服務或第三方支付商錯誤 |
錯誤代碼#
通用 HTTP 錯誤 (400-500)#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 400 | 400 | Bad request, please check your input | 請求格式錯誤 |
| 401 | 401 | Unauthorized access | 未授權訪問 |
| 404 | 404 | The requested resource was not found | 資源未找到 |
| 500 | 500 | Internal server error | 服務器內部錯誤 |
業務錯誤 (10001-10020)#
認證與授權錯誤#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 10001 | 401 | API key and signature required | API密鑰和簽名必須提供 |
| 10017 | 401 | Unauthorized access | 未授權訪問(未提供認證或認證無效) |
| 10020 | 403 | Access forbidden | 已認證但無權訪問該資源 |
401 (10017):未提供認證信息或認證信息無效(API Key錯誤、簽名錯誤、Token過期)
403 (10020):已認證但無權限訪問該資源(商戶ID不匹配、設備ID不匹配)
參數與驗證錯誤#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 10002 | 400 | Required parameter missing | 缺少必需參數 |
| 10008 | 400 | Invalid transaction status | 交易狀態無效 |
| 10009 | 400 | Invalid refund amount | 退款金額無效 |
| 10014 | 400 | Payment not in created state | 支付不在已創建狀態 |
| 10015 | 400 | Payment merchant reference mismatch | 支付商戶訂單號不匹配 |
| 10018 | 400 | Refund error | 退款錯誤 |
資源未找到錯誤#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 10003 | 404 | Payment Channel not found | 找不到支付通道 |
| 10005 | 404 | Merchant not found | 找不到商戶 |
| 10006 | 404 | Transaction not found | 找不到交易記錄 |
| 10010 | 404 | Payment method not found | 找不到支付方式 |
| 10013 | 404 | Payment not found | 找不到支付記錄 |
| 10019 | 404 | Store not found | 找不到店鋪 |
資源衝突錯誤#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 10011 | 409 | Merchant reference already exists | 商戶訂單號已存在 |
服務器錯誤#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 10004 | 500 | Failed to create transaction | 創建交易失敗 |
| 10007 | 500 | Failed to update transaction | 更新交易失敗 |
| 10012 | 500 | Failed to create Payment | 創建支付失敗 |
| 10016 | 500 | Failed to update Payment | 更新支付失敗 |
第三方支付通道錯誤 (20001-20099)#
| 錯誤代碼 | HTTP 狀態碼 | 錯誤信息 | 說明 |
|---|
| 20001 | 502 | Payment service error, please try again later | 支付服務錯誤 |
| 20002 | 502 | Payment processing failed, please try again | 第三方支付商處理失敗 |
20xxx 系列錯誤來自支付通道服務或第三方支付商
為了保護系統安全,這些錯誤不會透傳原始錯誤消息給客戶端
如遇這一系列錯誤,請聯繫ChingchingPay開發人員確認
Modified at 2025-11-06 09:28:12