概述

ChingchingPay 支付網關提供了一組 RESTful API，供商戶進行支付、退款、查詢等操作。本文檔旨在幫助開發者了解如何對接支付網關 API，包括接口對接方式、加密方式、鑑權方式，以及支持的交易通道和交易方式等。

如有技術問題請聯繫 dev@chingchingpay.com

接口對接方式

所有的 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\"}"
//如果用户是ALIPAYHK錢包，需要传递trade_information，具體值參考支付寶文檔https://global.alipay.com/docs/ac/hkapi/securitypay_pay，

//payment_inst值香港钱包为 ALIPAYHK, 如果是大陸錢包傳 "ALIPAYCN"

//refer_url：商户网站首页的URL。如果商户没有网站，则该字段可以使用商户APP下载地址。

AuthCodePaymentOptions 示例

{\"auth_code\":\"288747107207804180\"}"

Alipay Hong Kong AutoDebit（自動扣款）

支付寶香港自動扣款服務允許商戶在獲得用戶授權後，可以定期從用戶的支付寶賬戶中自動扣款，適用於訂閱服務、會員費、周期性付款等場景。

支付方式

授權流程

商戶通過 HK_ALIPAY_AUTODEBIT_PREPARE 發起授權請求，獲取授權URL

用戶訪問授權URL並在支付寶APP中完成授權

支付寶將用戶重定向到商戶的回調URL (/autodebit/auth_redirect)，並附帶授權碼(authCode)

商戶使用授權碼通過 HK_ALIPAY_AUTODEBIT_TOKEN 獲取訪問令牌

商戶使用訪問令牌通過 HK_ALIPAY_AUTODEBIT_PAY 發起自動扣款

如需取消授權，商戶可以通過 HK_ALIPAY_AUTODEBIT_CANCELAUTH 取消自動扣款授權

商戶須知事項

由於支付網關不會保存商戶的協議ID及訪問令牌等敏感資訊，商戶需要自行妥善保存以下關鍵資料：

商戶協議ID (merchantAgreementId)：

由商戶在發起授權請求時自行生成和提供

必須確保在商戶系統內唯一，建議與用戶帳號或訂閱關係關聯

需要在商戶系統中長期保存，用於後續的查詢授權狀態、發起扣款和取消授權等操作

訪問令牌 (accessToken) 及刷新令牌 (refreshToken)：

通過授權碼獲取的訪問令牌及其相關資訊必須由商戶自行保存

請務必保存以下資訊：

accessToken：用於發起自動扣款的令牌

refreshToken：用於在訪問令牌過期後獲取新的訪問令牌

expiresIn：訪問令牌的有效期

tokenStatus：令牌狀態

授權回調頁面：

商戶必須自行實現授權回調頁面 (即 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\"}"
//redirect_url 重定向地址，用于获取AUTH CODE，需要做urlencode

WechatJsapiPaymentOptions 示例

"{\"openid\":\"xxxxxx\"}" 或者 "{\"sub_openid\":\"xxxxxx\",\"sub_appid":\"xxxx\"}"

//openid 使用Gateway方式獲取到的openid
//sub_openid 使用自有公眾號方式獲取到的openid
//sub_appid自有公眾號appid

WechatInAppPaymentOptions 示例

"{\"appid\": \"appid-123456\"}"

Channel：QFPAY

支持平臺：Visa，MasterCard，銀聯雲閃付，Payme，FPS
通道配置：

Channel：Winning Pay

~~支持平臺：微信，支付寶~~

~~通道配置：~~

升级，使用Channel 5 ALIPAY 和 Channel 6 WECHAT 代替

交易回調

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", // ChingchingPay 支付ID
  "transaction_id": "string",          // ChingchingPay 交易 ID
  "transaction_type": "string",        // 交易類型: sale, refund
  "amount": 12345,                     // 交易金額
  "currency": "string",                // 交易貨幣
  "merchant_reference": "string",      // 商家訂單編號
  "payment_reference": "string",       // 支付服務商交易號碼
  "result": "string",                  // 交易結果
  "payer_id": "string",                // 付款人 ID (可選)
  "payed_time": 1234567890,            // 交易時間 (Unix 時間戳)
  "timestamp": 1234567890,             // 回調時間 (Unix 時間戳)
  "message": "string",                 // 交易結果消息 (可選)
  "extra": "string"                    // 附加信息 (可選)
}

回調簽名：

為了確保回調數據的完整性和來源，每個回調請求都會附帶一個簽名。簽名使用 HMAC-SHA256 算法生成，簽名的生成步驟如下：

將請求數據按鍵名排序，並拼接成 key=value&key=value 的形式。

使用商戶的 API 密鑰進行 HMAC-SHA256 加密。

將生成的簽名放在請求頭的 x-signature 字段中。

支付網關API

概述#

接口對接方式#

API 請求規範：#

鑑權方式#

簽名加密方式#

支持的支付通道#

Channel：ALIPAY#

PaymentMethodOption不同類型支付參數定義#

AlipayMobileSecurityPayPaymentOptions 示例#

AuthCodePaymentOptions 示例#

Alipay Hong Kong AutoDebit（自動扣款）#

支付方式#

授權流程#

商戶須知事項#

接口說明#

1. 授權準備請求 (HK_ALIPAY_AUTODEBIT_PREPARE)#

2. 授權回調 (商戶自行實現的回調頁面)#

3. 獲取訪問令牌 (HK_ALIPAY_AUTODEBIT_TOKEN)#

4. 發起自動扣款 (HK_ALIPAY_AUTODEBIT_PAY)#

5. 取消授權 (HK_ALIPAY_AUTODEBIT_CANCELAUTH)#

6. 查詢授權狀態 (HK_ALIPAY_AUTODEBIT_QUERYAUTH)#

Channel：Wechat Pay#

PaymentMethodOption不同類型支付參數定義#

AuthCodePaymentOptions 示例#

MiniProgramPaymentOptions 示例#

WechatAuthCodePaymentOptions 示例#

WechatJsapiPaymentOptions 示例#

WechatInAppPaymentOptions 示例#

Channel：QFPAY#

Channel：Winning Pay#

交易回調#

回調請求#

概述

接口對接方式

API 請求規範：

鑑權方式

簽名加密方式

支持的支付通道

Channel：ALIPAY

PaymentMethodOption不同類型支付參數定義

AlipayMobileSecurityPayPaymentOptions 示例

AuthCodePaymentOptions 示例

Alipay Hong Kong AutoDebit（自動扣款）

支付方式

授權流程

商戶須知事項

接口說明

1. 授權準備請求 (HK_ALIPAY_AUTODEBIT_PREPARE)

2. 授權回調 (商戶自行實現的回調頁面)

3. 獲取訪問令牌 (HK_ALIPAY_AUTODEBIT_TOKEN)

4. 發起自動扣款 (HK_ALIPAY_AUTODEBIT_PAY)

5. 取消授權 (HK_ALIPAY_AUTODEBIT_CANCELAUTH)

6. 查詢授權狀態 (HK_ALIPAY_AUTODEBIT_QUERYAUTH)

Channel：Wechat Pay

PaymentMethodOption不同類型支付參數定義

AuthCodePaymentOptions 示例

MiniProgramPaymentOptions 示例

WechatAuthCodePaymentOptions 示例

WechatJsapiPaymentOptions 示例

WechatInAppPaymentOptions 示例

Channel：QFPAY

Channel：Winning Pay

交易回調

回調請求