本指南仅适用于赞助模式的客户。
要使用我们的 API 进行付款，赞助模式的客户在代表其终端客户付款时，必须应用强客户身份验证 (SCA)。如果您属于适用范围，本指南将列明您的付款流程需要进行的更改，以适应额外的身份验证要求。
第 1 步：请确保向我们提供正确的电话号码
当您代表终端客户发起付款时，我们会通过短信向您的终端客户发送一次性密码 (OTP)，您需要在后续的请求标头中提供该密码。因此，请务必向我们提供您终端客户的正确手机号码。
使用 Find Contacts (/v2/contacts/find) 端点查看我们保存的手机号码，并使用 Update Contact (/v2/contacts/{id}) 端点更新 mobile_phone_number 字段（如有必要）。
第 2 步：验证付款
在发起付款之前，请调用 Validate Payment (/v2/payments/validate) 端点，并发送付款详情。如果 Currencycloud 已通知您的服务模式适用于 API 付款的 SCA，请将 x-sca-opt-in Boolean 标头设置为 true。如果通过付款验证，并且您符合 SCA 适用范围，则您的终端客户将收到一个有效期为 10 分钟的短信 OTP。响应对象将包含以下标头：
| 标头名称 | 描述 |
|---|---|
x-sca-id |
SCA 请求的 UUID。在创建付款时需要发送此信息。 |
x-sca-type |
使用的 2FA 类型 - SMS（短信）或 NONE（无）。 |
x-sca-required |
指示付款是否需要 SCA - true 或 false。 |
后续调用 Validate Payment 端点将发送新的 OTP 短信。
示例响应：
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 批准状态请求过多。 | 针对同一付款数据发送的短信通知过多。 |
HTTP 500
| 错误代码 | 错误消息 | 描述 |
|---|---|---|
| internal_server_error | 获取收款人时出错。 | 获取收款人时出错。 |
| internal_server_error | 验证 SCA 签名时出错。 | 无法为付款请求主体生成签名。 |
| internal_server_error | 获取账户时出错。 | 尝试获取账户数据时出错。 |
| internal_server_error | 发送 2FA 令牌请求时出错。 | 无法发送短信。 |
第 3 步：提交付款
当您准备好进行付款时，请调用 Create Payment (/v2/payments/create) 端点，并发送付款详情以及以下额外的标头参数：
| 标头名称 | 描述 |
|---|---|
x-sca-opt-in |
如果 Currencycloud 已通知您的服务模式适用于 API 付款的 SCA，请设置为 true。 |
x-sca-id |
由 Validate Payment 请求（第 2 步）返回的 UUID。 |
x-sca-token |
Validate Payment 请求后会收到的 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 | 未定义货币。 | 请求主体中缺少货币。 |
| mmount_type_is_wrong | 金额应为数值型。 | 请求主体中的金额不是数字类型。 |
HTTP 401
| 错误代码 | 错误消息 | 描述 |
|---|---|---|
| sca_required | 付款被拒绝。需要强客户身份验证。 | 需要 SCA 时未提供 x-sca-id 标头。 |
| x-sca-token | x-sca-token 无效。 | 出现此错误的情况包括： • 短信令牌无效 • 2FA 验证错误尝试超过 5 次 • SCA 尝试已用于创建付款。 |
| internal_server_error |
x-sca-token 已过期。 |
在 2FA 尝试过期时出现 - 短信为 10 分钟，推送通知为 5 分钟。 |
| internal_server_error | 验证失败。 | 无法使用提供的 x-auth-token 标头进行验证。 |
HTTP 429
| 错误代码 | 错误消息 | 描述 |
|---|---|---|
| internal_server_error | 2FA 批准状态请求过多。 | 验证短信令牌尝试次数过多。 |
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 批准状态时出错。 | 无法验证短信令牌。 |