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

授权支付

本文为您介绍如何通过 API 方式发起授权支付。

发起授权支付

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

  • 在买家点击 确认支付 后，商家买家端收到结果并处理之前，请将支付按钮禁用，以免买家多次点击多次触发操作。
  • 发起授权支付的过程中，您可以通过以下两种模式之一采集卡信息并发起授权支付：
    • 服务器对服务器模式: 此模式需要您具有 PCI 资质。
    • 托管表单模式：此模式不需要您具有 PCI 资质。
  • 发起授权支付时，可以根据业务需求，进行 更多功能 的设定。
  • 发起授权支付时，指定后续请款模式为自动请款还是手动请款。默认模式为自动请款。
    • 自动请款：在如下任意情况下，Antom 会在授权完成后自动发起请款：
      • 您指定 支付 接口的 paymentFactor.captureMode 字段的值为 AUTOMATIC。
      • 支付 接口的 paymentFactor.captureMode 字段为空或不传。
    • 手动请款：授权成功后您手动调用 请款 接口。您需指定 支付 接口的 paymentFactor.captureMode 字段值为 MANUAL。

【注意】韩国本地卡认证场景仅支持自动请款，不支持手动请款。

服务器对服务器模式

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

集成前提

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

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

交互流程

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

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

6@3x.png

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

用户体验

01-商户有PCI资质自主卡管理-新卡支付.png

接口调用

发送 支付 请求时， 您需传入以下信息：

卡信息

环境信息：用于提升支付成功率

订单信息：用于降低拒绝率和盗卡率

cardNo

cvv

expiryYear

expiryMonth

cardholderName

billingAddress

...

browserInfo

clientIp

terminalType

goods

shipping

buyer

表 1. 需采集的传参信息

发送 支付 请求，您可以根据自身业务需求选择是否使用以下更多功能，关于如何在集成中使用以上功能，参考 更多功能：

  • 设置 3D 认证：通过设定 is3DSAuthentication 参数的值，指定交易是否进行 3D 认证。
  • 智能挽回交易：对于您指定的非 3D 认证的交易，当卡组要求该笔交易进行 3D 认证时，可自动发起 3D 认证，挽回失败交易。
  • 增值风控服务：为您提供交易维度的升级风控服务，根据交易的风险等级智能决策风控策略。
  • AVS 验证：地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。
  • 存储卡信息：买家在首次支付后，同意存储卡信息以便在下一次支付时无需再次输入卡信息。
  • MIT 交易：在用户未参与的情况下发起定期或非定期的交易，即 Merchant-initiated Transactions (MIT) 场景。
  • 指定卡品牌：当买家选择双标卡支付时，您可以指定授权支付使用的卡品牌或卡所属区域。
  • MPI 能力：商家在交易发起前优先让买家完成第三方核身校验，在支付请求中传入核身结果信息并指定走非 3D 验证；若商家不采集卡信息，则此功能不可用。
  • 分期付款：买家在支付时，可以选择将支付款项分期付清，按照约定的期次和金额进行支付。在买家完成首期支付后，Antom 就会将该笔交易的支付总额按合同中约定的结算周期结算给您。

调用 支付 请求的示例：

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

托管表单模式

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

注意：此模式下，大部分卡支付产品均遵循通用卡场景支付流程，包括韩国本地卡非认证流程。而韩国本地卡认证流程因需要额外采集支付信息，其支付流程的集成与通用卡场景有所不同。

交互流程

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

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

7@3x.png

图 2. 授权支付交互流程（通用卡支付场景）

用户体验

以下为通用卡支付场景下的用户体验流程。

02-商户无PCI资质，2C2P提供绑卡能力 - 新卡支付.png

韩国本地卡认证场景下的用户体验请参阅 认证支付。

接口调用

调用 支付 接口时，您需传入以下提前收集到的信息：

环境信息：用于提升支付成功率

订单信息：用于降低拒绝率和盗卡率

terminalType

goods

shipping

buyer

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

调用 支付 接口时，您可以根据自身业务需求选择是否使用以下更多功能，关于如何在集成中使用以上功能，参考 更多功能：

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

调用 支付 请求的示例：

copy
{
    "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 字段包含卡令牌。

获取授权支付结果

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

8@3x.png

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

  • 值为 S：授权支付成功。
  • 值为 F：授权支付失败。您可以更换 paymentRequestID 后重新调用支付请求。
  • 值为 U 且 resultCode 值为 PAYMENT_IN_PROCESS：授权支付的处理尚未达到终态，需将您的买家跳转至 normalUrl 参数的地址，等待买家完成授权支付。完成授权支付后，您需通过异步通知或主动查询的方式获取授权支付的结果。
  • 无响应：您可以更换 paymentRequestID 或使用原请求 ID 重试调用支付请求。

注意：

  • 通用卡支付场景下，支付 请求的响应中仅会返回 resultStatus 参数值为 F 或 U 的情况。
  • 韩国本地卡认证场景下，支付 请求的响应中仅会返回 resultStatus 参数值为 F 或 U 以及无响应的情况。

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

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

当支付完成或到达终态后，Antom 会给您发送异步通知，您也可以通过主动查询获取授权支付结果。

接收异步通知

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

主动查询授权支付结果

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

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

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

方法

授权支付结果

AVS 信息

CVV 信息

3D 验证信息

异步通知

resultStatus

avsResultRaw

cvvResultRaw

threeDSResult （仅 3D 验证的交易存在此参数）

主动查询

paymentStatus

avsResultRaw

cvvResultRaw

threeDSResult （仅 3D 验证的交易存在此参数）

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

注意：韩国本地卡认证场景和非认证场景下，异步通知及主动查询获得的响应中均不包含 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"
        }
    }
}

下列代码示例展示了韩国本地卡认证场景下接收到的异步通知及主动查询响应：

copy
{
  "actualPaymentAmount": {
    "currency": "KRW",
    "value": "120"
  },
  "cardInfo": {
    "avsResultRaw": "",
    "cvvResultRaw": "",
    "paymentMethodRegion": "KR",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "KRW",
    "value": "120"
  },
  "paymentCreateTime": "2024-03-18T19:35:39-07:00",
  "paymentId": "2020010123456789XXXX",
  "paymentRequestId": "2020010123456789XXXX",
  "paymentResultInfo": {
    "avsResultRaw": "",
    "cvvResultRaw": "",
    "paymentMethodRegion": "KR",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-03-18T19:36:54-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}