接口调用流程
根据您是否具有 PCI 资质及是否愿意完成卡信息收集事项,接口调用流程不同:
如果您具有 PCI 资质且能够自行完成卡信息收集,接口调用流程如下:
- 卡支付授权前:调用 decide 接口,可获取是否授权该交易以及是否对交易进行 3D 验证的建议。
- 获取授权结果后:调用 sendPaymentResult 接口同步卡支付授权结果以训练蚂蚁的风控模型。
- 退款发生后:调用 sendRefundResult 接口同步退款结果以训练蚂蚁的风控模型。
- 风险发生后:调用 reportRisk 接口向蚂蚁反馈风险事件以训练蚂蚁的风控模型。
下图分别展示两种情况下调用接口集成风控产品的交互流程:
【说明】蚂蚁风控服务可对任意支付服务提供方提供的收单服务进行风险把控,为提高风险交易识别的准确度,建议您在交易或退款达到终态后,始终通过调用 sendPaymentResult 接口或 sendRefundResult 接口向蚂蚁同步交易结果。
步骤一:请求风控决策
发送请求
在调用 decide 接口请求蚂蚁作出风控决策时,您需要通过 paymentDetails.paymentMethod 字段传入以下卡信息,该卡信息需要您向买家提供卡支付要素填写页自行收集:
子字段 | 说明 |
paymentMethodType | 需传入,值为 |
paymentMethodId | 无需填入 |
paymentMethodMetaData.cardNo | 需传入卡号 |
paymentMethodMetaData.cardBin | 需传入卡片银行识别号 |
paymentMethodMetaData.expiryYear | 需传入卡过期年份 |
paymentMethodMetaData.expiryMonth | 需传入卡过期月份 |
paymentMethodMetaData.cardholderName | 需传入持卡人姓名 |
paymentMethodMetaData.billingAddress | 需传入持卡人的账单地址,但仅针对新加坡及中国香港地区卡。 |
paymentMethodMetaData.cpf | 需传入巴西卡持有者的税号 ID,仅针对巴西卡。 |
paymentMethodMetaData.is3DSAuthentication | 作为商户,您是否倾向于使用 3D 验证进行支付。Alipay 会根据您的倾向,并结合风控策略、支付渠道对于 non-3D 或 3D 支付的支持情况,综合决策最终的验证方式。
|
表 1. paymentMethod 子字段传参说明
除卡信息外,您还需要传入如下表所示的支付信息字段:
字段名 | 注意点 |
referenceTransactionId | 在商家侧唯一。 |
authorizationPhase | 传 |
actualPaymentAmount.value | 下单金额 |
env.terminalType | 买家在商户 PC 端发起交易则为 |
referenceOrderId | referenceOrderId 一般指代订单单号,paymentRequestId 一般指代交易单号,支付宝允许“一对多”(一个订单号对应多个交易单号),但也可以简化订单模型为“一对一”(一个订单号对应一个交易单号)。 |
表 2. 支付接口关键字段列表
除上述列出的字段外,建议您在请求中提供尽可能多的交易环境、物流信息、商户信息、买家信息,这将有助于蚂蚁准确识别风险交易,提升您的交易成功率。完整请求字段请参见 decide 接口。
获取风控建议
在您调用 decide 接口后,若请求受理成功,蚂蚁会返回该请求的受理结果。响应中会包含以下字段,为您提供风控决策建议:
字段名 | 注意点 |
decision | 蚂蚁的风控建议。值为 |
authenticationDecision | 当蚂蚁建议您授权该笔交易时,蚂蚁推荐使用的验证方式。 |
表 3. decide 接口响应字段解释
步骤二:同步交易结果
在您根据步骤一获取到蚂蚁的风控建议后,您可根据自身需求选择是否对该笔交易进行授权。若您选择了蚂蚁的收单服务并对该交易授权,在您调用 支付 接口下单后,您可以通过三种方式获取卡支付授权结果:
- 同步回跳
- 异步通知
- 主动查询
同步回跳
在 支付 接口的同步回跳响应中,若 resultStatus 的值为 S 或 F,则授权成功或失败;若 resultStatus 的值为 U,则需等待异步通知或发起主动查询。
异步通知
您可以通过接收 Alipay 发送给您的异步通知(notifyPayment)获取授权结果。接收异步通知的前提是,在 支付 接口中通过参数 paymentNotifyUrl 设定接收异步通知的地址。当授权成功或失败后,Alipay 会利用 支付结果通知 接口通过该地址向您发送异步通知。未达终态,则不会发送异步通知。若 resultStatus 的值为 S 或 F,则授权成功或失败。收到异步通知后,请按 要求 进行回应。
主动查询
无论是同步回跳还是异步通知,均有无法触达或延迟的可能性,建议您在后端通过 查询支付结果 接口主动查询交易状态。在 查询支付结果 接口的返回中,若 paymentStatus 的值为 SUCCESS 或 FAIL,则授权成功或失败。
获取到授权结果后,您需要调用 sendPaymentResult 接口同步卡授权结果,在请求中传入以下关键字段:
字段名 | 注意点 |
referenceTransactionId | 在商家侧唯一。 |
paymentStatus | 传入您通过同步回跳、主动查询或异步通知获取到的支付终态结果,有效值为 |
cardVerificationResult.authenticationType | 若您接收了该笔交易,需要传入该笔交易的验证类型。 |
表 5. sendPaymentResult 接口传参说明
步骤三:发送退款结果
如果交易退款成功,您需要调用 sendRefundResult 同步退款结果,在请求中传入以下字段:
字段名 | 注意点 |
referenceTransactionId | 在商家侧唯一,用于标识一笔交易。 |
referenceRefundId | 在商家侧唯一,用于标识一笔退款。 |
actualRefundAmount | 该笔交易的总退款额。 |
refundRecords | 该笔交易中逐个商品的退款详情。 |
表 6. sendRefundResult 接口传参说明
步骤四:上报风险事件
如果交易疑似欺诈或发生盗卡、拒付,您需要调用 reportRisk 接口向蚂蚁反馈风险事件,在请求中传入以下字段:
字段名 | 注意点 |
referenceTransactionId | 在商家侧唯一,用于标识一笔交易。 |
reportReason | 风险事件上报的原因。 |
riskType | 风险事件类型,有效值为:
|
riskOccurrenceTime | 风险事件的发生时间。您可以通过以下方式获取到该字段的值:
|
表 7. reportRisk 接口传参说明