API 開發指南 - 刷臉支付服務初始化

概述

本指南旨在幫助開發者理解如何使用刷臉支付服務的初始化接口。該接口用于獲取刷臉支付服務的初始化信息，以便進行后續的支付操作。

接口名稱

• zoloz.authentication.smilepay.initialize

請求說明

在調用刷臉支付初始化接口時，開發者需要構建請求并發送到支付寶的開放API網關。該請求包含必要的公共參數和業務參數。

請求參數

請求參數分為公共參數和業務請求參數。所有請求參數必須放在 biz_content 中傳遞。

公共參數

• app_id: 支付寶分配給開發者的應用ID。
• method: 接口名稱。
• format: 請求格式，支持JSON。
• charset: 請求使用的編碼格式（如utf-8）。
• sign_type: 簽名算法類型，推薦使用RSA2。
• sign: 請求參數的簽名串。
• timestamp: 發送請求的時間，格式為"yyyy-MM-dd HH:mm:ss"。
• version: 調用的接口版本，固定為：1.0。
• app_auth_token: 應用授權令牌（可選）。

業務請求參數

• apdid_token: 設備指紋，用于唯一標識設備（可選）。
• bio_meta_info: 生物識別元信息（可選）。
• app_name: 人臉識別應用名稱（可選）。
• app_version: 人臉識別應用版本號（可選）。
• remote_log_id: 業務ID（可選）。
• machine_info: 機具信息，包括機具編碼、型號等（可選）。
• merchant_info: 商戶信息，包括商戶ID、設備MAC地址等（可選）。
• ext_info: 擴展參數，包括業務類型（可選）。

響應說明

接口調用后，支付寶會返回響應數據。響應數據包括公共響應參數和業務響應參數。

公共響應參數

• code: 網關返回碼。
• msg: 網關返回碼描述。
• sub_code: 業務返回碼（可選）。
• sub_msg: 業務返回碼描述（可選）。
• sign: 響應數據的簽名。

業務響應參數

• ret_code_sub: 業務子返回碼（可選）。
• ret_message_sub: 業務子返回信息（可選）。
• zim_id: ZIM上下文ID（可選）。
• zim_init_client_data: 客戶端協議數據（可選）。

錯誤處理

在調用接口時可能會遇到錯誤，常見的錯誤碼包括：

• INVALID_PARAMETER: 參數有誤。
• SYSTEM_ERROR: 系統繁忙。
• BIZ_ERROR: 業務異常。

開發者應根據返回的錯誤碼進行相應的處理。

示例代碼

以下是一個Java示例代碼，演示如何調用刷臉支付初始化接口：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json", "GBK", "alipay_public_key", "RSA2");
ZolozAuthenticationSmilepayInitializeRequest request = new ZolozAuthenticationSmilepayInitializeRequest();
request.setBizContent("{...}"); // 填寫具體的業務參數
ZolozAuthenticationSmilepayInitializeResponse response = alipayClient.execute(request);
if(response.isSuccess()) {
    // 處理成功邏輯
} else {
    // 處理失敗邏輯
}

結論

通過本指南，開發者可以快速了解如何使用刷臉支付服務的初始化接口，構建請求并處理響應。建議開發者仔細閱讀相關文檔，以確保正確使用接口。