API 集成
本文为您介绍如何通过 API 方式发起授权支付，此方案适合对支付流程的自定义程度有较高要求的商户。
发起授权支付
在买家点击 确认支付 后，您需调用 支付 接口（POST/v1/payments/pay）发起授权支付。在此过程中，需要注意以下事项：
- 在买家点击 确认支付 后，商家买家端收到结果并处理之前，请将支付按钮禁用，以免买家多次点击多次触发操作。
- 需要您在授权支付过程中收集买家卡信息。如何发起授权支付请参考 交互流程 。
- 发起授权支付时，可以根据业务需求，进行 更多功能 的设定。
- 发起授权支付时，指定后续请款模式为自动请款还是手动请款。默认模式为自动请款。
- 自动请款：在如下任意情况下，APO 会在授权完成后自动发起请款：
交互流程
请按照以下步骤发起并完成授权支付：
- 在买家选择支付方式后，为买家展示卡信息收集页面（此页面由您自行开发）。此过程中您需要采集用户的卡信息、环境信息、及订单信息。
- 调用 支付 接口，提交授权支付请求。
- 接收请求的响应，响应中可能包含授权支付的结果。更多关于响应的信息及处理方式，参见获取授权支付结果 。
- 为买家展示授权支付结果。
图 1. 授权支付交互流程（服务器对服务器模式）
接口调用
发送 支付 请求 （POST/v1/payments/pay）时， 您需传入以下信息：
卡信息 | 环境信息：用于提升支付成功率 | 订单信息：用于降低拒绝率和盗卡率 |
cardNo cvv expiryYear expiryMonth cardholderName billingAddress ... | browserInfo clientIp terminalType | goods shipping buyer |
表 1. 需采集的传参信息
发送 支付 请求 （POST/v1/payments/pay）时 ，您可以根据自身业务需求选择是否使用以下更多功能，关于如何在集成中使用以上功能，参考更多功能：
- 设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行 3D 认证。
- AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。
- 存储卡信息：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。
- MIT 交易：在用户未参与的情况下发起定期或非定期的交易，即 Merchant-initiated Transactions (MIT) 场景。
- MPI 能力：商家在交易发起前优先让买家完成第三方核身校验，在支付请求中传入核身结果信息并指定走非 3D 验证；若商家不采集卡信息，则此功能不可用。
调用 支付 请求的示例：
copy
{
"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
}
}用户体验
首次支付（Web 端）
首次支付（App 端）
已存卡支付（Web 端）
已存卡支付（App 端）
获取授权支付结果
调用 支付 接口后，APO 为您返回的响应数据中的 resultStatus 参数值反应了该笔交易的授权支付结果：
图 3. 支付响应中 resultStatus 参数说明
- 值为
S：授权支付成功。 - 值为
F：授权支付失败。 - 值为
U且 resultCode 值为PAYMENT_IN_PROCESS：授权支付的处理尚未达到终态，需将您的买家跳转至 normalUrl 参数的地址，等待买家完成授权支付。完成授权支付后，您需通过异步通知或主动查询的方式获取授权支付的结果。
以下示例展示了调用 支付 接口后，您收到的响应中可能包含授权支付成功信息、授权支付失败信息、或授权支付未达终态返回跳转链接的信息：
授权支付成功
授权支付失败
授权支付未达终态
copy
{
"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"
}
}接收异步通知
通过接收 APO 发送给您的异步 支付结果通知（notifyPayment）获取授权支付结果时，需要提前配置异步通知的接收地址，当授权成功或失败后，APO 会利用 支付结果通知 向您发送异步通知。未达终态，则不会发送异步通知。收到异步通知后，请按接口响应要求进行回应，否则 APO 会重发异步通知。
主动查询授权支付结果
由于网络原因，异步通知有无法触达或延迟的可能性，因此建议您在后端通过 支付结果查询 接口（POST/v1/payments/inquiryPayment）主动查询交易状态，可以设置在以下时机时主动触发查询：
- 页面回跳时：发起支付后，在跳回时，触发查询支付结果接口同步交易状态，并引导至后续动作。
- 买家询问时：当买家在商家页面中点击 我已支付 或相关按钮后，通过查询支付结果接口核实交易状态。
- 交易到达预定超时时间后：在到达交易预定的超时时间后，通过查询支付结果接口确认订单支付状态。
异步通知及主动查询获得的响应中包含授权支付结果及其它下述关键信息：
方法 | 授权支付结果 | AVS 信息 | CVV 信息 | 3D 验证信息 |
异步通知 | resultStatus | avsResultRaw | cvvResultRaw | threeDSResult （仅 3D 验证的交易存在此参数） |
主动查询 | paymentStatus | avsResultRaw | cvvResultRaw | threeDSResult （仅 3D 验证的交易存在此参数） |
表 3. 异步通知和主动查询响应中关键信息
下列代码示例展示了接受到的异步通知及查询响应：
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"
}
}
}