本指南僅適用於贊助模式客戶。
若要使用我們的 API 進行支付，贊助模式客戶在代表其客戶支付時，必須執行嚴格顧客驗證機制 (SCA)。如果您屬於適用範圍，本指南概述了您的支付工作流程所需的變更，以便進行額外的認證。
第 1 步：確保我們具有正確的電話號碼
當您代表客戶發起支付流程時，我們會透過 SMS 向您的客戶發送一個一次性密碼 (OTP)，您需要在後續的請求標頭中提供該密碼。因此，確保我們具有客戶的正確手機號碼至關重要。
使用查找聯絡人 (/v2/contacts/find) 端點以查看我們保留的手機號碼，必要時，使用更新聯絡人 (/v2/contacts/{id}) 端點以更新 mobile_phone_number 欄位。
第 2 步：驗證支付
在發起支付之前，需調用驗證支付 (/v2/payments/validate) 端點，傳遞支付詳情。若 Currencycloud 已通知您，您的服務模式屬於 API 支付的 SCA 適用範圍，則您需要將 Boolean 標頭 x-sca-opt-in 設定為 true。如果支付通過驗證，且您屬於 SCA 的適用範圍，則您的客戶將收到一個透過 SMS 發送到他們手機上的 OTP，該密碼在 10 分鐘內有效。回應對象將包含下列標頭：
| 標頭名稱 | 描述 |
|---|---|
x-sca-id |
SCA 請求的 UUID。在創建支付時需要發送該識別碼。 |
x-sca-type |
使用的雙重驗證 (2FA) 類型 - SMS 或 NONE。 |
x-sca-required |
表示支付是否需要進行 SCA - true 或 false。 |
後續調用驗證支付端點將發送一條新的 OTP SMS。
回應示例：
Content-Type: application/json
x-sca-id:123e4567-e89b-12d3-a456-426614174000
x-sca-type:SMS
x-sca-required: true
{
"validation_result": "success"
}
錯誤代碼 (sca_check_failed)
HTTP 400
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| invalid_beneficiary | 無法找到指定 id 的收款人。 | 未找到收款人。 |
| invalid_extra_x_sca_id | 驗證請求時不應在標頭中包含 x-sca-id。 |
在驗證過程中，請求中提供了 x-sca-id 標頭。 |
| missing_account | 無法找到指定 id 的賬戶。 | 無法找到賬戶資料。 |
| amount_type_is_wrong | 金額應為數字類型。 | 請求正文中的金額不是數字類型。 |
HTTP 401
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 使用提供的憑證進行身份驗證失敗 | 無法使用所提供的 x-auth-token 標頭進行身份驗證。 |
HTTP 422
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 聯絡人的手機號碼無效 | 聯絡人的手機號碼無效 |
| internal_server_error | 聯絡人沒有手機號碼 | 聯絡人沒有手機號碼 |
HTTP 429
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 2FA 核准狀態的請求過多。 | 針對同一支付資料發送的 SMS 通知過多。 |
HTTP 500
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 獲取收款人時出錯。 | 獲取收款人時發生錯誤。 |
| internal_server_error | 驗證 SCA 簽名時出錯。 | 無法為支付請求正文生成簽名。 |
| internal_server_error | 獲取賬戶時出錯。 | 嘗試獲取賬戶資料時出錯。 |
| internal_server_error | 發送 2FA 令牌請求時出錯。 | 無法發送 SMS。 |
第 3 步：提交支付
當您準備好進行支付時，請調用創建支付 (/v2/payments/create) 端點，並傳遞支付詳情和以下額外標頭參數：
| 標頭名稱 | 描述 |
|---|---|
x-sca-opt-in |
若 Currencycloud 已通知您，您的服務模式屬於 API 支付 SCA 的適用範圍，則您需要將此標頭設定為 true。 |
x-sca-id |
驗證支付請求（上文第 2 步）返回的 UUID。 |
x-sca-token |
驗證支付請求後收到的 OTP。 |
若 OTP 驗證成功，則會處理支付。
錯誤代碼 (sca_check_failed)
HTTP 400
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| invalid_beneficiary | 無法找到指定 id 的收款人。 | 未找到收款人。 |
| missing_x_sca_token | 需要執行 SCA，但請求中未包含令牌。 | 預期需要 x-sca-token 標頭，但未提供。 |
| invalid_request_body | 指定 x-sca-id 的請求正文無效。 |
請求正文與提供用於驗證請求的正文不符。 |
| invalid_x_sca_id |
x_sca_id 無效。 |
資料庫中未找到所提供的 x-sca-id。 |
| x-account-identifier | 無法找到指定 id 的賬戶。 | 無法找到賬戶資料。 |
| missing_beneficiary | 請求中未指定收款人。 | 請求正文中缺少收款人 id。 |
| missing_amount | 未指定金額。 | 請求正文中缺少金額。 |
| missing_currency | 未指定貨幣。 | 請求正文中缺少貨幣。 |
| amount_type_is_wrong | 金額應為數字類型。 | 請求正文中的金額不是數字類型。 |
HTTP 401
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| sca_required | 支付被拒絕。需要執行嚴格顧客驗證機制。 | 在需要 SCA 時，未提供 x-sca-id 標頭。 |
| x-sca-token | x-sca-token 無效。 | 這在以下情況下會發生： • SMS 令牌無效 • 2FA 驗證嘗試錯誤次數超過 5 次 • 已嘗試使用 SCA 來創建支付。 |
| internal_server_error |
x-sca-token 已過期。 |
當 2FA 嘗試過期時出現 - SMS 的有效期為 10 分鐘，推送通知的有效期為 5 分鐘。 |
| internal_server_error | 身份驗證失敗。 | 無法使用所提供的 x-auth-token 標頭進行身份驗證。 |
HTTP 429
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 2FA 核准狀態的請求過多。 | 嘗試驗證 SMS 令牌的次數過多。 |
HTTP 500
| 錯誤代碼 | 錯誤訊息 | 描述 |
|---|---|---|
| internal_server_error | 獲取收款人時出錯。 | 獲取收款人時發生錯誤。 |
| internal_server_error | 2FA 類型無效。 | 驗證過程中儲存資料時出錯。 |
| internal_server_error | 驗證 SCA 簽名時出錯。 | 為支付請求正文生成簽名時發生問題。 |
| internal_server_error | 獲取聯絡人時出錯。 | 使用所提供的 x-auth-token 獲取聯絡人資料時發生問題。 |
| internal_server_error | 獲取賬戶時出錯。 | 獲取賬戶資料時出錯。 |
| internal_server_error | 檢索 2FA 核准狀態時發生錯誤。 | 無法驗證 SMS 令牌。 |