集成指南

2023-07-18 17:25

针对卡交易，您可以使用以下风控服务相关接口来降低拒付及盗卡等风险事件，从而避免资金损失：

decide：用于向您提供针对交易的风控建议，获取蚂蚁风控建议后，您可选择是否接受交易以及是否对交易进行 3D 验证。
sendPaymentResult：向蚂蚁同步您的卡支付授权结果，以训练蚂蚁的风控模型，优化未来针对交易的风控建议。
sendRefundResult：向蚂蚁同步您的退款结果，以训练蚂蚁的风控模型，优化未来针对交易的风控建议。
reportRisk：向蚂蚁同步您的风险事件，以训练蚂蚁的风控模型，优化未来针对交易的风控建议。

集成前提

在正式开始集成之前，您需要完成以下准备工作：

注册支付宝开发者中心账号。
设置您的密钥。
若您集成的业务包含香港或新加坡地区的卡收单，请联系您对应的 SA 做内部系统的配置。
在沙箱中测试。

欲知更多详情，请参考支付宝的集成指南。

集成步骤

您需要在交易或风险发生的以下时机调用对应接口实现风控功能：

交易发生前：调用 decide 接口请求蚂蚁提供风控建议。您应在调用 pay 接口进行卡支付授权前调用此接口。
授权完成后：调用 sendPaymentResult 接口同步卡支付授权结果。若发生退款，调用 sendRefundResult 同步退款结果。您调用此接口后并不会获得进一步的风控建议，但蚂蚁收集交易结果数据作为未来风险评估的依据，用于提升风控效果，为您降低资金损失。
风险发生后：调用 reportRisk 接口向蚂蚁反馈风险事件。您调用此接口后并不会获得进一步的风控建议，但蚂蚁收集风险事件数据作为未来风险评估的依据，用于提升风控效果，为您降低资金损失。

【说明】蚂蚁风控服务可对任意支付服务提供方提供的收单服务进行风险把控，为提高风险交易识别的准确度，建议您在交易或退款达到终态后，始终通过调用 sendPaymentResult 接口或 sendRefundResult 接口向蚂蚁同步交易结果。

步骤一：请求风控决策

发送请求

在调用 decide 接口请求蚂蚁作出风控决策时，您需要通过 paymentDetails.paymentMethod 字段传入以下卡信息，该卡信息需要您向买家提供卡支付要素填写页自行收集：

子字段	说明
paymentMethodType	需传入，值为 `CARD`
paymentMethodId	无需填入
paymentMethodMetaData.cardNo	需传入卡号
paymentMethodMetaData.cvv	需传入卡片验证号
paymentMethodMetaData.expiryYear	需传入卡过期年份
paymentMethodMetaData.expiryMonth	需传入卡过期月份
paymentMethodMetaData.cardholderName	需传入持卡人姓名
paymentMethodMetaData.billingAddress	需传入持卡人的账单地址，但仅针对新加坡及中国香港地区卡。
paymentMethodMetaData.cpf	需传入巴西卡持有者的税号 ID，仅针对巴西卡。
paymentMethodMetaData.is3DSAuthentication	作为商户，您是否倾向于使用 3D 验证进行支付。Alipay 会根据您的倾向，并结合风控策略、支付渠道对于 2D 或 3D 支付的支持情况，综合决策最终的验证方式。 is3DSAuthentication=true: 倾向于选择 3D 验证，但该笔交易最终是否选择 3D 支付通道还依赖于 Alipay 的风控策略。 is3DSAuthentication=false: 倾向于选择 2D 验证，但该笔交易最终是否选择 2D 支付通道还依赖于 Alipay 的风控策略。 is3DSAuthentication 为空：由收单机构决定交易的验证类型。

表 1. paymentMethod 子字段传参说明

除卡信息外，您还需要传入如下表所示的支付信息字段：

字段名	注意点
referenceTransactionId	在商家侧唯一。
authorizationPhase	固定传 `PRE_AUTH`，表明该请求发生在卡支付授权前。
actualPaymentAmount.value	下单金额
env.terminalType	买家在商户 PC 端发起交易则为 `WEB`，商户手机浏览器端发起则为 `WAP`，商户 APP 发起则为 `APP`。
referenceOrderId	referenceOrderId 一般指代订单单号，paymentRequestId 一般指代交易单号，支付宝允许“一对多”（一个订单号对应多个交易单号），但也可以简化订单模型为“一对一”（一个订单号对应一个交易单号）。

表 2. 支付接口关键字段列表

除上述列出的字段外，建议您在请求中提供尽可能多的交易环境、物流信息、商户信息、买家信息，这将有助于蚂蚁准确识别风险交易，提升您的交易成功率。完整请求字段请参见 decide 接口。

获取风控建议

在您调用 decide 接口后，若请求受理成功，蚂蚁会返回该请求的受理结果。响应中会包含以下字段，为您提供风控决策建议：

字段名	注意点
decision	蚂蚁的风控建议。值为 `ACCEPT` 表示蚂蚁建议您接受该笔交易，值为 `REJECT` 表示蚂蚁建议您拒绝该笔交易。
authenticationDecision	当蚂蚁建议您接收该笔交易时，蚂蚁推荐使用的验证方式。`3D` 表示蚂蚁建议您采用 3D 验证，`NOT_3D` 表示蚂蚁建议您采用非 3D 验证。

表 3. decide 接口响应字段解释

步骤二：同步授权结果

在您根据步骤一获取到蚂蚁的风控建议后，您可根据自身需求选择是否接受和拒绝该笔交易。若您选择了蚂蚁的收单服务并接受了该笔交易，在您调用支付接口下单后，您可以通过两种方式获取卡支付授权结果：

同步回跳
异步通知
主动查询

同步回跳

在支付接口的同步回跳响应中，若 resultStatus 的值为 S 或 F，则授权成功或失败；若 resultCode 的值为 U，则需等待异步通知或发起主动查询。

异步通知

您可以通过接收 Alipay 发送给您的异步通知（notifyPayment）获取授权结果。接收异步通知的前提是，在支付接口中通过参数 paymentNotifyUrl 设定接收异步通知的地址。当授权成功或失败后，Alipay 会利用 支付结果通知 接口通过该地址向您发送异步通知。未达终态，则不会发送异步通知。若 resultStatus 的值为 S 或 F，则授权成功或失败。收到异步通知后，请按要求进行回应。

主动查询

无论是同步回跳还是异步通知，均有无法触达或延迟的可能性，建议您在后端通过 查询支付结果 接口主动查询交易状态。

在 查询支付结果 接口的返回中，务必依赖 paymentStatus 作为交易状态，该字段取值详情如下所示：

paymentStatus	类型	描述
SUCCESS	交易终态	支付成功。
PROCESSING	交易中间态	交易尚在处理中。
FAIL	交易终态	买家未支付或支付失败。
CANCELLED	交易终态	交易被商家取消。

表 4. paymentStatus 字段取值详情

获取到支付结果后，您需要调用 sendPaymentResult 接口同步卡授权结果，在请求中传入以下关键字段：

字段名	注意点
referenceTransactionId	在商家侧唯一。
paymentStatus	传入您通过主动查询或异步通知获取到的支付终态结果，有效值为 `SUCCESS` 和 `FAIL`。
cardVerificationResult.authenticationType	若您接收了该笔交易，需要传入该笔交易的验证类型。`3D` 表示您采用了 3D 验证，`NON_3D` 表示您没有采用 3D 验证。

表 5. sendPaymentResult 接口传参说明

步骤三：发送退款结果

如果交易发生退款，您需要调用 sendRefundResult 同步退款结果，在请求中传入以下字段：

字段名	注意点
referenceTransactionId	在商家侧唯一，用于标识一笔交易。
referenceRefundId	在商家侧唯一，用于标识一笔退款。
actualRefundAmount	该笔交易的总退款额。
refundRecords	该笔交易中逐个商品的退款详情。

表 6. sendRefundResult 接口传参说明

步骤四：上报风险事件

如果交易疑似欺诈或发生盗卡、拒付，您需要调用 reportRisk 接口向蚂蚁反馈风险事件，在请求中传入以下字段：

字段名	注意点
referenceTransactionId	在商家侧唯一，用于标识一笔交易。
reportReason	风险事件上报的原因。
riskType	风险事件类型，有效值为： `SUSPICIOUS`：疑似风险交易，可能是因为买家命中了商家的黑名单。 `CHARGEBACK`: 表示买家发起了拒付。 `FRAUD`：表示发生盗卡。
riskOccurrenceTime	风险事件的发生时间。您可以通过以下方式获取到该字段的值：如果 riskType 的值为 `SUSPICIOUS`，此时间为您识别到风险交易的时间。如果 riskType 的值为 `CHARGEBACK`，此时间为支付方式通知您拒付发生的时间。如果 riskType 的值为 `FRAUD`，此时间为支付方式通知您盗卡发生的时间。

表 7. reportRisk 接口传参说明