SDK 集成
本文为您介绍如何集成 SDK 以完成授权支付。此方案对于商户是否具有 PCI 资质无要求，适用于青睐轻量集成、对支付流程自定义程度无较高要求的商户。通过使用卡支付 SDK , 以最少的开发成本实现组件形式接入卡支付方式，并减少支付流程中的页面跳转、从而降低支付流程中的买家流失率，为买家提供更加优质的支付体验。
卡支付 SDK 提供的主要功能包括：
- 提供支付信息收集页，帮助您通过浮层交互收集卡支付要素、减少支付流程中的页面跳转、优化支付成功率。
- 帮助完成设备信息的收集，即 Device Data Collection（DDC）流程。
- 处理 3D 验证页面跳转
- 提供支付处理中的提示页面。
- 实现对应浏览器语言的支付页面，目前支持英语、葡萄牙语、韩语、西班牙语等四种语言。
部署流程
通过卡支付 SDK 接入卡支付方式的整体部署及交互流程如下：
图 1. SDK 卡支付交互流程
- 创建 SDK 实例：您的客户端创建支付方式选择页并实现监听支付按钮的点击事件后，需 AMSCheckout() 创建 SDK 实例 。
- 调用 支付会话创建 接口：买家选择卡发起支付后，您的服务端使用买家的下单信息向 Alipay 服务端发起 支付会话创建 请求。在此步骤中，您可根据业务需求选择是否使用以下增值功能，关于设置增值功能的详细内容，参考 增值功能 ：
- 设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行3D认证。
- 智能挽回交易：对于您指定的非 3D 认证的交易，当卡组要求该笔交易进行 3D 认证时，可自动发起 3D 认证，挽回失败交易。
- 增值风控服务：为您提供交易维度的升级风控服务，根据交易的风险等级智能决策风控策略。
- AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。
- 存储卡信息：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。
- MIT 交易：在用户未参与的情况下发起定期或非定期的交易，即 Merchant-initiated Transactions (MIT) 场景。
- 创建支付要素收集组件：使用 支付会话创建 请求的响应参数 paymentSessionData，通过 createComponent() 创建支付要素收集组件。
- 买家完成支付：买家在支付要素收集页面填写支付要素信息并完成支付。如支持分期，用户在此页面指定分期信息。
- 获取授权支付结果并呈现：您的服务端通过接收异步通知或主动调用 查询支付结果 接口获取支付结果，并在您的支付结果页面向用户呈现。
集成快速开始
更多关于 Web/Wap, Android, 或 iOS 终端类型的集成详情，参见以下相关内容：
获取授权支付结果
当买家在 SDK 提供的支付信息收集页浮层中完成卡信息输入、SDK 提交支付、完成3D验证等操作后，SDK 会在浏览器上展示授权支付结果页面（即 paymentRedirectUrl 参数对应的页面)。您需通过接收异步通知或发起主动查询获取授权支付结果并在授权支付结果页面向买家呈现该结果。
接收异步通知
通过接收 Alipay 发送给您的异步 支付结果通知（notifyPayment）获取授权支付结果时，需要提前配置异步通知的接收地址，当授权成功或失败后，Alipay 会利用 支付结果通知 向您发送异步通知。未达终态，则不会发送异步通知。收到异步通知后，请按 要求 进行回应，否则 Alipay 会重发异步通知。
主动查询授权支付结果
由于网络原因，异步通知有无法触达或延迟的可能性，因此建议您在后端通过 查询支付结果 接口（POST/v1/payments/inquiryPayment）主动查询交易状态，可以设置在以下时机时主动触发查询：
- 页面回跳时：发起支付后，在跳回时，触发查询支付结果接口同步交易状态，并引导至后续动作。
- 买家询问时：当买家在商家页面中点击 我已支付 或相关按钮后，通过查询支付结果接口核实交易状态。
- 交易到达预定超时时间后：在到达交易预定的超时时间后，通过查询支付结果接口确认订单支付状态。
异步通知及主动查询获得的响应中包含授权支付结果及其他下述关键信息：
方法 | 授权支付结果 | AVS 信息 | CVV 信息 | 3D 验证信息 |
异步通知 | resultStatus | avsResultRaw | cvvResultRaw | threeDSResult （仅 3D 验证的交易存在此参数） |
主动查询 | paymentStatus | avsResultRaw | cvvResultRaw | threeDSResult （仅 3D 验证的交易存在此参数） |
表 1. 异步通知和主动查询响应中的关键信息
下列代码示例展示了接受到的异步通知及查询响应：
{
"notifyType": "PAYMENT_RESULT",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentRequestId": "2020010123456789XXXX",
"paymentId": "2020010123456789XXXX",
"paymentAmount": {
"value": "8000",
"currency": "EUR"
},
"paymentCreateTime": "2020-01-01T12:01:00+08:30",
"paymentTime": "2020-01-01T12:01:01+08:30",
"paymentResultInfo": {
"avsResultRaw": "A",
"cvvResultRaw": "Y",
"networkTransactionId": "sampleNetworkTransactionId123456",
"threeDSResult": {
"eci": "02",
"threeDSVersion": "2.2.0",
"caav": "cavvSample",
"dsTransactionId": "sample_dsTranasctionId"
}
}
}SDK功能说明
- 在卡支付的场景中，一个完整的收单流程包括支付和请款两个阶段。卡支付SDK仅在支付阶段提供帮助，后续的请款流程，需通过商户服务端调用请款接口完成后续流程。详情请参考卡集成-请款步骤。
- 关于更多支付流程后续的其他相关操作，请参考 退款、对账 等集成文档。
- 在集成过程中，仍有少量集成工作需您自行进行代码开发。下表为您详细展示了整体集成过程中需要您自行编码完成的步骤及 SDK帮助实现的步骤：
您需自行编码的步骤 | SDK 功能详情 |
|
表 2. 自行编码步骤与 SDK 功能详情
用户体验
通过集成卡支付SDK，您将获得以下用户界面：
场景1：使用卡进行首次支付
值得注意的是，部分地区卡组发行的卡在该地区卡组交易网络下进行交易时，卡信息收集页需要收集的支付信息略有差异，这些地区包括：巴西及韩国。其卡信息收集页详情如下：
韩国：
巴西：
注意：
- 以上流程的各个页面提供方信息如下：
- 支付方式选择页：由商户客户端自行实现
- 支付要素收集前的等待页
- 支付要素收集页：由 SDK 提供
- 支付处理中的提示页面：由 SDK 提供
- 支付结果展示页：商户客户端自行实现
- 如果您在调用 支付会话创建 请求时传入了卡信息，则以上流程中的第二及第三个页面不会出现。
场景2：使用卡进行再次支付
场景3：支付异常
