Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

接口调用流程

根据您是否具有 PCI 资质及是否愿意完成卡信息收集事项，接口调用流程不同：

如果您具有 PCI 资质且能够自行完成卡信息收集，接口调用流程如下：

  1. 卡支付授权前：调用 decide 接口，可获取是否授权该交易以及是否对交易进行 3D 验证的建议。
  2. 获取授权结果后：调用 sendPaymentResult 接口同步卡支付授权结果以训练蚂蚁的风控模型。
  3. 退款发生后：调用 sendRefundResult 接口同步退款结果以训练蚂蚁的风控模型。
  4. 风险发生后：调用 reportRisk 接口向蚂蚁反馈风险事件以训练蚂蚁的风控模型。

下图分别展示两种情况下调用接口集成风控产品的交互流程：

接口调用流程

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

步骤一：请求风控决策

发送请求

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

子字段

说明

paymentMethodType

需传入，值为 CARD

paymentMethodId

无需填入

paymentMethodMetaData.cardNo

需传入卡号

paymentMethodMetaData.cardBin

需传入卡片银行识别号

paymentMethodMetaData.expiryYear

需传入卡过期年份

paymentMethodMetaData.expiryMonth

需传入卡过期月份

paymentMethodMetaData.cardholderName

需传入持卡人姓名

paymentMethodMetaData.billingAddress

需传入持卡人的账单地址，但仅针对新加坡及中国香港地区卡。

paymentMethodMetaData.cpf

需传入巴西卡持有者的税号 ID，仅针对巴西卡。

paymentMethodMetaData.is3DSAuthentication

作为商户，您是否倾向于使用 3D 验证进行支付。Alipay 会根据您的倾向，并结合风控策略、支付渠道对于 non-3D 或 3D 支付的支持情况，综合决策最终的验证方式。

  • is3DSAuthentication=true: 倾向于选择 3D 验证，但该笔交易最终是否选择 3D 支付通道还依赖于 Alipay 的风控策略。
  • is3DSAuthentication=false: 倾向于选择 non-3D 验证，但该笔交易最终是否选择 non-3D 支付通道还依赖于 Alipay 的风控策略。
  • is3DSAuthentication 为空：由收单机构决定交易的验证类型。

表 1. paymentMethod 子字段传参说明

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

字段名

注意点

referenceTransactionId

在商家侧唯一。

authorizationPhase

传 PRE_AUTHORIZATION，表明该请求发生在卡支付授权前。

actualPaymentAmount.value

下单金额

env.terminalType

买家在商户 PC 端发起交易则为 WEB，商户手机浏览器端发起则为 WAP，商户 APP 发起则为 APP。

referenceOrderId

referenceOrderId 一般指代订单单号，paymentRequestId 一般指代交易单号，支付宝允许“一对多”（一个订单号对应多个交易单号），但也可以简化订单模型为“一对一”（一个订单号对应一个交易单号）。

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

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

获取风控建议

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

字段名

注意点

decision

蚂蚁的风控建议。值为 ACCEPT 表示蚂蚁建议您对该交易进行授权，值为 REJECT 表示蚂蚁建议您不对该交易进行授权。

authenticationDecision

当蚂蚁建议您授权该笔交易时，蚂蚁推荐使用的验证方式。3D 表示蚂蚁建议您采用 3D 验证，NON_3D 表示蚂蚁建议您采用非 3D 验证。

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

步骤二：同步交易结果

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

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

同步回跳

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

异步通知

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

主动查询

无论是同步回跳还是异步通知，均有无法触达或延迟的可能性，建议您在后端通过 查询支付结果 接口主动查询交易状态。在 查询支付结果 接口的返回中，若 paymentStatus 的值为 SUCCESS 或 FAIL，则授权成功或失败。

获取到授权结果后，您需要调用 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 接口传参说明