API 集成

花匠小妙招
2024-12-07 18:50

本文为您介绍如何通过 API 方式发起授权支付，此方案适合对支付流程的自定义程度有较高要求的商户。

发起授权支付

在买家点击 确认支付 后，您需调用支付接口（POST/v1/payments/pay）发起授权支付。在此过程中，需要注意以下事项：

在买家点击 确认支付 后，商家买家端收到结果并处理之前，请将支付按钮禁用，以免买家多次点击多次触发操作。发起授权支付的过程中，您可以通过以下两种模式之一采集卡信息并发起授权支付：服务器对服务器模式: 此模式需要您具有 PCI 资质。托管表单模式：此模式不需要您具有 PCI 资质。发起授权支付时，可以根据业务需求，进行增值功能的设定。

服务器对服务器模式

服务器到服务器模式允许您通过直接从您的服务器向Alipay服务器发送请求来处理交易。通过此集成模式，您需要提供所有用户信息，包括卡支付信息。

集成前提

使用此集成模式要求您必须具备 PCI 资质，请根据业务需求提供以下材料以完成核验要求：

如果您的年交易次数预计将超过 600 万卡交易次数，请提供 PCI Attestation of Compliance (AoC) 文件完成核验。如果您的年交易次数预计将不超过 600 万卡交易次数，请完成并提交 PCI DSS Self-Assessment Questionnaires (SAQs) 问卷。

更多关于 PCI DSS 合规要求的信息，请参考 PCI DSS standard 。

交互流程

此模式下，请按照以下步骤发起并完成授权支付：

在买家选择支付方式后，为买家展示卡信息收集页面（此页面由您自行开发）。此过程中您需要采集并存储用户的卡信息、环境信息、及订单信息。调用支付接口，提交授权支付请求。接收请求的响应，响应中可能包含授权支付的结果。更多关于响应的信息及处理方式，参见获取授权支付结果。为买家展示授权支付结果。

图 1. 授权支付交互流程（服务器对服务器模式）

用户体验：

接口调用

发送支付请求（POST/v1/payments/pay）时，您需传入以下信息：

表 1. 需采集的传参信息

发送支付请求（POST/v1/payments/pay）时，您可以根据自身业务需求选择是否使用以下增值功能，关于如何在集成中使用以上功能，参考增值功能：

设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行 3D 认证。智能挽回交易：对于您指定的非 3D 认证的交易，当卡组要求该笔交易进行 3D 认证时，可自动发起 3D 认证，挽回失败交易。增值风控服务：为您提供交易维度的升级风控服务，根据交易的风险等级智能决策风控策略。AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。存储卡信息：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。MIT 交易：在用户未参与的情况下发起定期或非定期的交易，即 Merchant-initiated Transactions (MIT) 场景。指定卡品牌：当买家选择双标卡支付时，您可以指定授权支付使用的卡品牌或卡所属区域。

调用支付请求的示例：

{ "env": { "browserInfo": { "acceptHeader": "*/*", "javaEnabled": true, "javaScriptEnabled": true, "language": "zh_CN", "userAgent": "Chrome/100" }, "terminalType": "APP", "clientIp": "112.80.248.78", "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe", "osType": "IOS", "deviceLanguage": "zh_CN", "colorDepth": 48, "screenHeight": 768, "screenWidth": 1024, "timeZoneOffset": 1 }, "order": { "orderAmount": { "currency": "EUR", "value": "30000" }, "orderDescription": "Cappuccino #grande (Mika's coffee shop)", "referenceOrderId": "ORDER_20221114141714891", "goods": [ { "referenceGoodsId": "383382011_SGAMZ-904520356", "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto", "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3", "goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages", "goodsUnitAmount": { "currency": "EUR", "value": "30000" }, "goodsQuantity": "10" } ], "shipping": { "shippingName": { "firstName": "Dehua", "lastName": "Liu", "fullName": "Dehua Skr Liu", "middleName": "Skr" }, "shippingAddress": { "zipCode": "310000", "address2": "Xihu", "city": "Hangzhou", "address1": "Wuchang road", "state": "Zhejiang", "region": "CN" }, "shippingCarrier": "FedEx", "shippingPhoneNo": "12345678912", "shipToEmail": "test@gmail.com" }, "buyer": { "referenceBuyerId": "test12345678", "buyerPhoneNo": "12345678912", "buyerEmail": "alipay@alipay.com", "buyerName": { "firstName": "Dehua", "lastName": "Liu", "fullName": "Dehua Skr Liu", "middleName": "Skr" } } }, "paymentAmount": { "currency": "EUR", "value": "30000" }, "paymentMethod": { "paymentMethodType": "CARD", "paymentMethodMetaData": { "isCardOnFile": false, "enableAuthenticationUpgrade": true, "is3DSAuthentication": false, "cvv": "850", "cardholderName": { "firstName": "Tom", "lastName": "Jay" }, "expiryMonth": "12", "billingAddress": { "zipCode": "310000", "address2": "Xihu", "city": "Hangzhou", "address1": "Wuchang road", "state": "Zhejiang", "region": "CN" }, "expiryYear": "29", "cardNo": "4117347806156383" } }, "settlementStrategy": { "settlementCurrency": "EUR" }, "paymentNotifyUrl": "https://www.alipay.com/notify", "paymentRedirectUrl": "https://www.alipay.com", "paymentRequestId": "PAY_20221114141714891", "productCode": "CASHIER_PAYMENT", "paymentFactor": { "isAuthorization": true } }

托管表单模式

托管表单模式可以防止您受到 PCI-DSS 限制的影响，因为敏感数据（卡号、加密码）不会通过您的服务器传递，对于您是否具备 PCI 资质无要求。此模式下，Alipay 提供支付信息收集页面、采集支付信息后将支付信息存储为卡令牌（cardToken）用于后续流程。

交互流程

此模式下，请按照以下步骤发起并完成授权支付：

买家选择支付方式并点击支付按钮。调用支付接口，提交授权支付请求。在接口请求中不包含卡信息。Alipay 收到接口调用请求后，返回卡信息收集页，用于买家输入卡信息。在前端页面打开中间页，为买家展示卡信息收集页面。买家填写完整的支付要素信息后，Alipay 对支付要素进行验证，当验证通过后，Alipay 推进接口调用流程并将支付要素信息存储为令牌（cardToken）并向卡组提交授权支付请求。Alipay 为您返回请求的响应，响应中可能包含授权支付的结果。更多关于响应的信息及处理方式，参见获取授权支付结果。展示授权支付的结果。

图 2. 授权支付交互流程（托管表单模式）

用户体验：

接口调用

调用支付接口（POST/v1/payments/pay）时，您需传入以下提前收集到的信息：

表 2. 需提前采集的传参信息

调用支付接口（POST/v1/payments/pay）时，您可以根据自身业务需求选择是否使用以下增值功能，关于如何在集成中使用以上功能，参考增值功能：

设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行3D认证。自动挽回交易：对于您指定的非 3D 认证的交易，当卡组要求该笔交易进行 3D 认证时，可自动发起 3D 认证，挽回失败交易。增值风控服务：为您提供交易维度的升级风控服务，根据交易的风险等级智能决策风控策略。AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。买家绑卡：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。MIT 交易：在用户未参与的情况下发起定期或非定期的交易，即 Merchant-initiated Transactions (MIT) 场景。

调用支付请求的示例：

{ "env": { "terminalType": "APP", "clientIp": "112.80.248.78", "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe", "osType": "IOS", "deviceLanguage": "zh_CN" }, "order": { "orderAmount": { "currency": "EUR", "value": "30000" }, "orderDescription": "Cappuccino #grande (Mika's coffee shop)", "referenceOrderId": "ORDER_20221114141714891", "goods": [ { "referenceGoodsId": "383382011_SGAMZ-904520356", "goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto", "goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3", "goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages", "goodsUnitAmount": { "currency": "EUR", "value": "30000" }, "goodsQuantity": "10" } ], "shipping": { "shippingName": { "firstName": "Dehua", "lastName": "Liu", "fullName": "Dehua Skr Liu", "middleName": "Skr" }, "shippingAddress": { "zipCode": "310000", "address2": "Xihu", "city": "Hangzhou", "address1": "Wuchang road", "state": "Zhejiang", "region": "CN" }, "shippingCarrier": "FedEx", "shippingPhoneNo": "12345678912", "shipToEmail": "test@gmail.com" }, "buyer": { "referenceBuyerId": "test12345678", "buyerPhoneNo": "12345678912", "buyerEmail": "alipay@alipay.com", "buyerName": { "firstName": "Dehua", "lastName": "Liu", "fullName": "Dehua Skr Liu", "middleName": "Skr" } } }, "paymentAmount": { "currency": "EUR", "value": "30000" }, "paymentMethod": { "paymentMethodType": "CARD" }, "settlementStrategy": { "settlementCurrency": "EUR" }, "paymentNotifyUrl": "https://www.alipay.com/notify", "paymentRedirectUrl": "https://www.alipay.com", "paymentRequestId": "PAY_20221114141714891", "productCode": "CASHIER_PAYMENT", "paymentFactor": { "isAuthorization": true } }

在用户存卡后的后续支付中，您需要通过支付接口的 paymentMethod.paymentMethodId 字段传入获取的卡令牌信息。卡令牌可以通过以下两种方式之一被获取：

接收异步通知（notifyPayment）：异步通知中的 cardInfo 字段包含卡令牌。调用支付查询接口（inquiryPayment）：接口返回中的 cardInfo 字段包含卡令牌。

获取授权支付结果

调用支付接口后，Alipay 为您返回的响应数据中的 resultStatus 参数值反应了该笔交易的授权支付结果：

图 3. 支付响应中 resultStatus 参数说明

值为 S：授权支付成功。值为 F：授权支付失败。值为 U 且 resultCode 值为 PAYMENT_IN_PROCESS：授权支付的处理尚未达到终态，需将您的买家跳转至 normalUrl 参数的地址，等待买家完成授权支付。完成授权支付后，您需通过异步通知或主动查询的方式获取授权支付的结果。

注意：托管表单模式下，支付请求的响应中仅会返回 resultStatus 参数值为 F 或 U 的情况。

以下示例展示了调用支付接口后，您收到的响应中可能包含授权支付成功信息、授权支付失败信息、或授权支付未达终态返回跳转链接的信息：

{ "paymentAmount": { "currency": "EUR", "value": "1314" }, "paymentCreateTime": "2021-11-12T01:27:50-08:00", "paymentId": "20211112194010800100188570271832381", "paymentRequestId": "PAY_20211112172747856", "paymentResultInfo": { "avsResultRaw": "A", "cvvResultRaw": "Y", "networkTransactionId": "sampleNetworkTransactionId123456" }, "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } }

接收异步通知

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

主动查询授权支付结果

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

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

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

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

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

{ "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" } } }