SDK 集成

2024-09-03 09:35

本文为您介绍如何集成 SDK 以完成授权支付。此方案对于商户是否具有 PCI 资质无要求，适用于青睐轻量集成、对支付流程自定义程度无较高要求的商户。通过使用卡支付 SDK , 以最少的开发成本实现组件形式接入卡支付方式，并减少支付流程中的页面跳转、从而降低支付流程中的买家流失率，为买家提供更加优质的支付体验。

卡支付 SDK 提供的主要功能包括：

提供支付信息收集页，帮助您通过浮层交互收集卡支付要素、减少支付流程中的页面跳转、优化支付成功率。
帮助完成设备信息的收集，即 Device Data Collection（DDC）流程。
处理 3D 验证页面跳转
提供支付处理中的提示页面。
支持英语、葡萄牙语、韩语、西班牙语、法语、德语、意大利语和荷兰语八种浏览器语言。

部署流程

通过卡支付 SDK 接入卡支付方式的整体部署及交互流程如下：

Group 18.png

图 1. SDK 卡支付交互流程

创建 SDK 实例：您的客户端创建支付方式选择页并实现监听支付按钮的点击事件后，需通过 AMSCashierPayment 创建 SDK 实例。
调用 支付会话创建 接口：您的服务端使用买家的下单信息向 APO 服务端发起 支付会话创建 请求。在此步骤中:

您可以指定后续请款模式为自动请款还是手动请款。默认模式为自动请款。

自动请款：在如下任意情况下，APO 会在授权完成后自动发起请款：

您指定 支付会话创建 接口的 paymentFactor.captureMode 字段的值为 AUTOMATIC。
支付会话创建 接口的 paymentFactor.captureMode 字段为空或不传。

手动请款：授权成功后您手动调用请款接口。您需指定 支付会话创建 接口的 paymentFactor.captureMode 字段值为 MANUAL。

您可根据业务需求选择是否使用以下更多功能，关于设置更多功能的详细内容，参考更多功能：

设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行3D认证。
AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。
存储卡信息：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。
MPI 能力：商家在交易发起前优先让买家完成第三方核身校验，在支付请求中传入核身结果信息并指定走非 3D 验证；若商家不采集卡信息，则此功能不可用。

创建支付要素收集组件：使用 支付会话创建 请求的响应参数 paymentSessionData 创建支付要素收集组件。在已预先绑卡模式下，可能会出现支付要素补充收集页面，或不再需要支付要素收集页，只有支付等待页面。
买家完成支付：买家在支付要素收集页面填写支付要素信息并完成支付。如支持分期，用户在此页面指定分期信息。
获取授权支付结果并呈现：您的服务端通过接收异步通知或主动调用 支付结果查询 接口获取支付结果，并在您的支付结果页面向用户呈现。

集成快速开始

您可以通过 SDK 集成浮层或嵌入式支付体验：

浮层式支付体验：是指在您的收银台页面悬浮支付要素收集页面。关于 Web/WAP, Android, 或 iOS 终端类型的浮层支付体验集成详情，参见以下内容：

嵌入式支付体验：是指直接将支付要素收集界面嵌入到您的收银台页面中。关于 Web/WAP 终端的嵌入式支付体验集成详情，参见以下内容：

获取授权支付结果

当买家在 SDK 提供的支付信息收集页浮层中完成卡信息输入、SDK 提交支付、完成3D验证等操作后，SDK 会在浏览器上展示授权支付结果页面（即 paymentRedirectUrl 参数对应的页面)。您需通过接收异步通知或发起主动查询获取授权支付结果并在授权支付结果页面向买家呈现该结果。

接收异步通知

通过接收 APO 发送给您的异步 支付通知 获取授权支付结果时，需要提前配置异步通知的接收地址，当授权成功或失败后，APO 会利用 支付通知 向您发送异步通知。未达终态，则不会发送异步通知。收到异步通知后，请按接口响应要求进行回应，否则 APO 会重发异步通知。

主动查询授权支付结果

由于网络原因，异步通知有无法触达或延迟的可能性，因此建议您在后端通过 支付结果查询 接口（POST/v1/payments/inquiryPayment）主动查询交易状态，可以设置在以下时机时主动触发查询：

页面回跳时：发起支付后，在跳回时，触发查询支付结果接口同步交易状态，并引导至后续动作。
买家询问时：当买家在商家页面中点击 我已支付 或相关按钮后，通过查询支付结果接口核实交易状态。
交易到达预定超时时间后：在到达交易预定的超时时间后，通过 支付结果查询 接口确认订单支付状态。

异步通知及主动查询获得的响应中包含授权支付结果及其他下述关键信息：

方法	授权支付结果	AVS 信息	CVV 信息	3D 验证信息
异步通知	resultStatus	avsResultRaw	cvvResultRaw	threeDSResult （仅 3D 验证的交易存在此参数）
主动查询	paymentStatus	avsResultRaw	cvvResultRaw	threeDSResult （仅 3D 验证的交易存在此参数）

表 1. 异步通知和主动查询响应中的关键信息

下列代码示例展示了接受到的异步通知及查询响应：

notifyPayment (3D)

notifyPayment (非3D)

inquiryPayment (3D)

inquriyPayment (非3D)

copy
{
    "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 功能详情

开发并渲染支付方式选择页。
监听支付按钮的点击或卡支付方式点击事件。
引入 SDK 包，并创建 SDK 实例。
通过您的服务端调用 支付会话创建 接口，并获取响应数据中的 paymentSessionData。
调用 createComponent() 创建支付要素收集组件。
通过异步通知或 支付结果查询 接口获取支付结果并向用户展示。

支持英语、葡萄牙语、韩语、西班牙语、法语、德语、意大利语和荷兰语八种浏览器语言。
展示支付要素收集前的等待页。
获取到 paymentSessionData 后，展示支付要素收集页面。
用户完成支付要素信息填写后：

展示支付处理中的提示页面。
实现设备信息的收集，完成DDC流程。
完成DDC流程后，根据交易的情况，按照不同场景进行处理：

交易需要触发 3D 验证：实现自动跳转至 3D 验证页面，并在用户完成 3D 验证后，将用户跳转至您提供的支付结果展示页，此时页面展示支付处理中的状态。
交易无需触发 3D 验证: 将用户跳转至商户提供的支付结果展示页，此时页面展示支付处理中的状态。
遇到支付异常情况：

浮层式支付体验：在当前页面通过浮层展示支付异常信息，并在用户点击关闭浮层按钮后，将用户跳转至商户提供的支付结果展示页，此时页面展示支付处理中的状态。
嵌入式支付体验：将用户跳转至商户提供的支付结果展示页。

表 2. 自行编码步骤与 SDK 功能详情

用户体验

通过集成卡支付SDK，以下流程的各个页面提供方信息如下：

支付方式选择页：由商户客户端自行实现
支付要素收集前的等待页：由 SDK 提供
支付要素收集页：由 SDK 提供
支付处理中的提示页面：由 SDK 提供
支付结果展示页：商户客户端自行实现