Chingchingpay Payment Gateway
    • 支付網關
      • 查詢交易狀態
        POST
      • 發起支付交易
        POST
      • 發起退款交易
        POST
      • 創建PaymentLink H5 頁面
        POST
      • 查询Payment的交易明细
        GET
      • 發起Payment退款交易
        POST
      • 獲取Settlement列表
        GET
      • Merchant/下載Settlement文件
        GET

    支付網關API

    概述#

    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(自動扣款)#

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

    支付方式#

    授權流程#

    1.
    商戶通過 HK_ALIPAY_AUTODEBIT_PREPARE 發起授權請求,獲取授權URL
    2.
    用戶訪問授權URL並在支付寶APP中完成授權
    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):
    通過授權碼獲取的訪問令牌及其相關資訊必須由商戶自行保存
    請務必保存以下資訊:
    accessToken:用於發起自動扣款的令牌
    refreshToken:用於在訪問令牌過期後獲取新的訪問令牌
    expiresIn:訪問令牌的有效期
    tokenStatus:令牌狀態
    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商戶在授權請求中提供的協議IDstring是e8qdwl9casxor13
    authCode支付寶返回的一次性授權碼string是用於獲取訪問令牌28100413kpBklrvUk33YgGgC9yS2o679
    client_id授權商戶IDstring是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\"}"

    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\"}"
    
    //更多参数请参考https://pay.weixin.qq.com/doc/global/v3/zh/4014096395

    Channel:Wechat Pay CN#

    支持平臺:大陆微信支付
    通道配置:

    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:GKASH#

    支持平臺:Visa,MasterCard,QRCODE ,馬來西亞主流支付方式
    通道配置:

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

    GKASHPaymentOptions#

    //GKASH_EWALLET_MERCHANT_QR PaymentMethodOption
    "{\"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
    
    //GKASH_EWALLET_CUSTOMER_QR PaymentMethodOption
    "{\"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", // 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 算法生成,簽名的生成步驟如下:
    1.
    將請求數據按鍵名排序,並拼接成 key=value&key=value 的形式。
    2.
    使用商戶的 API 密鑰進行 HMAC-SHA256 加密。
    3.
    將生成的簽名放在請求頭的 x-signature 字段中。

    API 響應代碼參考#

    響應格式#

    成功響應#

    所有成功的 API 調用返回以下格式:
    {
      "code": 0,
      "message": "success",
      "data": {
        // 具體的響應數據
      }
    }
    字段說明:
    code: 0 表示成功
    message: "success"
    data: 包含具體的響應數據(根據不同 API 而異)
    HTTP 狀態碼: 200 OK

    錯誤響應#

    所有錯誤響應遵循以下格式:
    {
      "code": 10002,
      "message": "Required parameter missing"
    }
    字段說明:
    code: 應用級錯誤代碼(詳見下表)
    message: 錯誤描述信息
    HTTP 狀態碼: 根據錯誤類型返回相應的 HTTP 狀態碼(400、401、403、404、409、500、502)

    🔢 HTTP 狀態碼#

    HTTP 狀態碼說明使用場景
    200成功請求成功處理
    400請求錯誤參數格式錯誤、業務邏輯驗證失敗
    401未授權未提供認證信息或認證信息無效
    403禁止訪問已認證但無權訪問該資源
    404資源未找到請求的資源不存在
    409資源衝突資源已存在(如訂單號重複)
    500服務器錯誤服務器內部錯誤
    502網關錯誤支付通道服務或第三方支付商錯誤

    錯誤代碼#

    通用 HTTP 錯誤 (400-500)#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    400400Bad request, please check your input請求格式錯誤
    401401Unauthorized access未授權訪問
    404404The requested resource was not found資源未找到
    500500Internal server error服務器內部錯誤

    業務錯誤 (10001-10020)#

    認證與授權錯誤#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    10001401API key and signature requiredAPI密鑰和簽名必須提供
    10017401Unauthorized access未授權訪問(未提供認證或認證無效)
    10020403Access forbidden已認證但無權訪問該資源
    401 vs 403:
    401 (10017):未提供認證信息或認證信息無效(API Key錯誤、簽名錯誤、Token過期)
    403 (10020):已認證但無權限訪問該資源(商戶ID不匹配、設備ID不匹配)

    參數與驗證錯誤#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    10002400Required parameter missing缺少必需參數
    10008400Invalid transaction status交易狀態無效
    10009400Invalid refund amount退款金額無效
    10014400Payment not in created state支付不在已創建狀態
    10015400Payment merchant reference mismatch支付商戶訂單號不匹配
    10018400Refund error退款錯誤

    資源未找到錯誤#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    10003404Payment Channel not found找不到支付通道
    10005404Merchant not found找不到商戶
    10006404Transaction not found找不到交易記錄
    10010404Payment method not found找不到支付方式
    10013404Payment not found找不到支付記錄
    10019404Store not found找不到店鋪

    資源衝突錯誤#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    10011409Merchant reference already exists商戶訂單號已存在

    服務器錯誤#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    10004500Failed to create transaction創建交易失敗
    10007500Failed to update transaction更新交易失敗
    10012500Failed to create Payment創建支付失敗
    10016500Failed to update Payment更新支付失敗

    第三方支付通道錯誤 (20001-20099)#

    錯誤代碼HTTP 狀態碼錯誤信息說明
    20001502Payment service error, please try again later支付服務錯誤
    20002502Payment processing failed, please try again第三方支付商處理失敗
    注意事項:
    20xxx 系列錯誤來自支付通道服務或第三方支付商
    為了保護系統安全,這些錯誤不會透傳原始錯誤消息給客戶端
    如遇這一系列錯誤,請聯繫ChingchingPay開發人員確認
    Modified at 2025-11-06 09:28:12
    Next
    查詢交易狀態
    Built with