Alipay 支持您通过多种多样的支付方式进行收单，其中卡支付是在全球众多地区较为流行的支付方式。卡支付的集成与其他支付方式的集成略有差异，本文主要针对卡支付方式的集成进行详细说明。

集成前提

在正式开始集成之前，您需要完成以下准备工作：

• 注册 Alipay 开发者中心账号。
• 设置您的密钥。
• 若您集成的业务包含香港或新加坡地区的卡收单，请联系您对应的 SA 做内部系统的配置。
• 在沙箱中测试。

欲知更多详情，请参考 Alipay 的 集成指南。

卡收单场景

所有通过卡支付方式进行的收单交易均为授权请款模式。即收单分为授权和请款两步，买家在结账时先授权付款，授权阶段会锁定特定金额的付款资金，仅在请款成功后才将资金转移到您的账户。值得注意的是，您需要在授权成功之后的 7*24 小时内发起请款，否则资金的冻结将自动解除。

卡支付方式下，有如下几个常见场景：

支付：

对于支付场景的集成，主要步骤如下：

1. 获取并呈现支付方式。
2. 发起授权。
3. 获取授权结果。
4. 发起请款。
5. 获取请款结果。

完成集成后，在购物类网站的下单支付过程中，您向买家呈现的页面流程如下：

图 2. 卡支付用户体验

1. 买家核对订单信息，点击 确认下单 之后系统生成订单，进入支付方式选择页。
2. 买家选择支付方式，填入支付要素信息，点击 确认支付 后进入对应支付过程。
3. 根据下单返回结果决定跳转的页面：

• SUCCESS：直接跳转到步骤 4，展示支付成功的结果页。
• FAIL：直接跳转到步骤 4，展示支付失败的结果页。
• PAYMENT_IN_PROCESS，跳转至支付方式提供的 WAP 页面，买家根据 WAP 页面的引导，填入对应信息，完成支付。注意：跳转至 支付 接口返回的 normalUrl 地址即可，该 URL 地址展示逻辑针对不同类型的商户及支付验证类型有所不同，详情参考 支付流程买家体验。

4. 在支付完成后回跳至支付完成页。

在支付产品的对接中，您的主要工作将集中在支付方式选择页，该页面一般会有以下作用：

• 呈现可用支付方式列表：根据订单金额、地区等信息过滤支付方式并呈现。
• 控制交易状态：显示支付倒计时，根据订单状态判断是否允许推进到支付过程。
• 推进至支付过程：向后台请求支付链接，并拉起支付。
• 接收支付回调（可选）：通过页面唤起或者生命周期函数感知支付回调，并根据支付状态推进到支付结果页。
  

步骤一：获取并呈现支付方式

建议您通过接入 咨询 接口动态获取当前支持的支付方式及支付方式相关信息，并对获取到的支付方式进行合理呈现。

1. 获取支付方式

您可调用 咨询 接口 （POST/v1/payments/consult）来获取卡支付方式列表：

在请求中，您需要传入该笔订单的金额、支付的端类型、地区信息；返回参数会告知您该支付渠道的 logo、正确显示名以及当前状态。具体可参照 咨询 接口说明。请注意以下字段信息：

表 1. 咨询接口关键请求参数说明

在响应中，返回对应的支付方式列表，几个关键字段如下：

表 2. 咨询接口关键返回参数说明

2. 呈现支付方式

步骤二：发起授权支付

买家在结账时先给您授权付款，授权阶段会锁定特定金额的付款资金，您需通过调用 支付 接口（POST/v1/payments/pay），获取买家的授权。

授权支付过程中，需要进行支付信息采集以完成支付的推进。获取卡信息有两种模式，对应的授权支付流程有所差异：

• 商户收集卡信息模式
• 卡令牌模式

在授权支付阶段，关键步骤的处理需按照以下建议进行：

1. 支付信息采集

在卡支付流程中，需采集用户卡信息用于支付流程的推进：向用户提供卡支付要素填写页，进行支付信息采集；并询问用户是否同意卡信息被存储，用于再次支付时无需重复输入卡支付要素。采集支付信息可通过两种模式进行：

• 商户收集卡信息模式
• 卡令牌模式

2. 拦截无效支付单

建议您在买家点击 确认支付 后，先校验下该笔订单的状态与有效期，以避免重复支付或者对已失效的订单进行支付：

图 3. 拉起支付过程

3. 发起支付请求

在买家点击 确认支付 后，商家服务器向 Alipay 服务器请求支付链接，商家服务器调用 Alipay 支付 接口获得支付链接并返回。在此过程中，需要注意以下事项：

• 在买家点击 确认支付 后，商家买家端收到结果并处理之前，请将支付按钮禁用，以免买家多次点击多次触发操作。
• 发送支付请求时，是否传入支付要素等卡相关信息将影响后续的支付流程。
• 在处理请求过程中，需设定请求超时的时限，避免买家等待时间过长。
• 卡支付过程中，2D 验证和 3D验证的响应及对应的处理有所不同。

发送请求

商家收集卡信息模式下与卡令牌模式下，在发送支付请求时，通过 paymentMethod 字段传入信息有所不同，具体如下：

表 4. paymentMethod 子字段传参说明

Alipay 根据 支付 接口被调用时的请求体中支付要素信息是否齐全，来判断后续流程：

• 如果卡信息齐全，则继续推进支付流程。
• 如果卡信息不齐全，则 Alipay提供中间页进行卡信息的收集。
  

支付请求中其他关键字段如下（具体字段详情请参见 支付 接口）：

表 5. 支付接口关键字段列表

请求处理

在请求支付链接的过程中，可能发生订单失败的情况，对于失败的订单，商户端可能会重新发起支付，此时需重新调用 支付 接口下单，并更新 paymentRequestId。 但第二次请求依然有可能因网络原因失败，建议在买家端请求中设定 HTTP 请求的超时时限，以避免买家等待过长。在获取支付链接失败后，能够允许买家重新发起支付。建议按照如下逻辑进行请求处理：

图 4. 请求支付流程及处理支付逻辑

接收响应

针对一笔支付请求的响应，会因以下两个因素有所差异：

• 卡信息收集模式
• 支付流程是否使用 3D 验证。未使用 3D 验证则为 2D 验证。

下表汇总了两种卡信息收集模式下、不同认证方式的响应结果及对应的商户处理：

表 6. 不同场景下的支付返回结果

2D 验证：

• 在商户收集卡信息模式下，对于已确认成功或失败的交易，Alipay 直接在响应中返回支付结果；对于尚在处理中的交易，Alipay 在响应中返回用于推进交易的 normalUrl。在收到 normalUrl 后，需跳转买家至该地址继续推进支付流程。
• 在 Alipay 收集卡信息模式下，无论交易状态如何，Alipay 在响应中返回用于推进交易的 normalUrl。在收到 normalUrl 后，需完成页面重定向到该地址或新标签页打开该地址，买家可根据页面引导继续推进支付流程。

3D 验证：

无论交易状态如何，Alipay 在响应中均返回用于推进 3D 验证的 normalUrl。在收到 normalUrl 后，需完成页面重定向到该地址或新标签页打开该地址，买家可根据页面引导完成 3D 验证后再进行支付。

4. 获取授权结果

您可以通过三种方式获取授权结果：同步回跳，异步通知，主动查询。

同步回跳

在 支付 接口的同步回跳响应中，若 resultStatus 的值为 S 或 F，则授权成功或失败；若 resultCode 的值为 U，则需等待异步通知或发起主动查询。

异步通知

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

异步通知的关键字段：

表 7. notifyPayment 关键字段说明

配置异步通知接收地址：

可以通过两种方式进行异步通知地址的配置：

• 通过 支付 接口中的参数 paymentNotifyUrl 设定异步通知地址。
• 在 Alipay 开发者中心 Integration Settings 标签页下，编辑 Notification URL进行配置。

主动查询

无论是同步回跳还是异步通知，均有无法触达或延迟的可能性：

表 8. 交易状态获取失败场景

建议您在后端通过 查询支付结果 接口主动查询交易状态，可以设置在以下时机时主动触发查询：

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

在 查询支付结果 接口的返回中，务必依赖 paymentStatus 作为交易状态，建议您按照以下表格做后续引导：

表 9. paymentStatus 字段取值详情

建议在商家服务端维护订单/交易单状态，买家端依赖商家服务端进行后续操作。交易状态的更多相关内容，请参考 交易状态说明。

对于 Alipay 进行卡信息收集的情况，如果买家在卡信息收集页勾选确认同意授权保存卡信息，则在支付结果查询的响应中会返回买家的卡信息（cardInfo），包括：

• 脱敏号卡（cardNo）
• 卡品牌（cardBrand）
• 卡令牌（cardToken）
• 如果交易使用的是 3D 验证，还会返回电子商务安全评级指标（eci）
• 发卡国家 (issuingCountry)
• 卡类型 (funding)
• 支付方式所在区域 (paymentMethodRegion)

5. 处理绑卡用户的再次支付

当买家在支付要素收集页同意卡信息被存储，在完成第一次支付后即完成了绑卡。当该买家再次发起支付时，无需手动填写卡信息。

再次支付

对于绑卡用户再次发起支付时，针对两种收集卡信息模式，人卡关系维护及用户再次支付时的接口调用情况均有不同，您需要根据卡信息收集模式进行对应的操作：

图 5. 不同卡信息收集模式下的支付处理

卡片管理

绑卡用户可能需要对卡片进行信息更新或删除等操作，即对卡片进行管理。针对此需求，在两种卡信息收集模式下，您根据相应的建议帮助用户进行卡片管理：

6. （可选）取消授权

您可以通过调用 取消 接口，进行授权的取消。当以下情况发生时，需要进行授权取消：

• 在买家完成授权支付之后、商户进行请款之前，如果买家申请了退款，则商户需取消该买家的授权。
• 商户风控系统判断该笔交易有风险。

如果授权取消成功，取消 接口的响应中 result.resultStatus 字段值为 S。

步骤三：发起请款

授权成功之后的七天内，您需要通过调用 请款 接口（POST/v1/payments/capture），完成请款，否则 Alipay 会自动将买家的资金冻结解除。对于部分卡支付方式，一次授权支持一次或多次请款，请款的总金额应小于等于授权的金额。

请款请求中关键字段如下（具体内容请参见 请款 接口）：

表 10. 请款接口关键字段说明

步骤四：获取请款结果

您可以通过三种方式获取授权结果：同步回跳，异步通知，主动查询。

同步回跳

在 请款 接口的返回中，若直接返回 resultStatus 值为 S 或者 F，代表了请款成功或失败。若返回 resultStatus 值为U，则可等待请款的异步通知或发起主动查询。

异步通知

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

异步通知关键字段：

表 11. 异步通知关键字段说明

配置异步通知接收地址：

可以通过两种方式进行异步通知地址的配置：

• 通过 支付 接口中的参数 paymentNotifyUrl 设定异步通知地址。
• 在 Alipay 开发者中心 Integration Settings 标签页下，编辑 Notification URL进行配置。

主动查询

同步跳转及异步通知均有无法触达或延迟的可能性；建议您在后端通过 查询支付结果 接口主动查询请款状态，该接口响应中的 transactions 字段的值为请款状态：

表 12. transactions 子参数说明

以下示例展示了支付查询接口的响应中，transactions 字段在不同情况下的返回值：

{
    "transactions": [
        {
            "transactionType": "CAPTURE",
            "transactionStatus": "SUCCESS",
            "transactionRequestId": "test_test_test_XXXX",
            "transactionAmount": {
                "currency": "BRL",
                "value": "110"
            },
            "transactionTime": "2022-09-29T07:13:50-07:00",
            "transactionId": "2022XXXXXXXX",
            "transactionResult": {
                "resultStatus": "S",
                "resultCode": "SUCCESS",
                "resultMessage": "success"
            }
        }
    ]
}

{
    "transactions": [
        {
            "transactionType": "CAPTURE",
            "transactionStatus": "FAIL",
            "transactionRequestId": "test_test_test_XXXX",
            "transactionAmount": {
                "currency": "BRL",
                "value": "110"
            },
            "transactionTime": "2022-09-29T07:13:50-07:00",
            "transactionId": "2022XXXXXXXX",
            "transactionResult": {
                "resultStatus": "F",
                "resultCode": "PROCESS_FAIL",
                "resultMessage": "General business failure. No retry."
            }
        }
    ]
}

{
    "transactions": [
        {
            "transactionType": "CAPTURE",
            "transactionStatus": "PROCESSING",
            "transactionRequestId": "test_test_test_XXXX",
            "transactionAmount": {
                "currency": "BRL",
                "value": "110"
            },
            "transactionTime": "2022-09-29T07:13:50-07:00",
            "transactionId": "2022XXXXXXXX",
            "transactionResult": {
                "resultStatus": "U",
                "resultCode": "PAYMENT_IN_PROCESS",
                "resultMessage": "payment in process"
            }
        }
    ]
}
  

拒付

如果买家选择卡支付方式，当某笔交易发生拒付时，Alipay 提供争议处理相关服务：

• 拒付发生时通知商户相关信息并冻结拒付相关交易。
• 帮助商户向卡组提供抗辩材料。
• 通知商户拒付判责结果。

Alipay通过人工或者 拒付通知 接口告知您拒付相关信息。

通过人工方式

在您通过邮件的方式接收到拒付通知后，需要在一定时效内回复是否接受拒付。如果未在规定时效内回复，默认接受该笔拒付。不同渠道时效要求不同，具体参考下表：

表 13. 渠道时效要求

通过接口方式（可选）

您可以选择接入 拒付通知 接口来接收拒付相关信息。拒付通知接收地址需要预先在开发者中心内进行配置。

拒付通知接收地址配置

您需要提前在 Alipay 开发者中心 Integration Settings 标签页下，编辑 Notification URL 进行接收拒付通知的地址配置。配置成功后，才可收到拒付通知。

当卡交易发生拒付时及拒付判责完成后，Alipay 均会通过 notifyDispute 接口给您发送通知。收到通知后，请按 要求进行回应，否则 Alipay 会重发通知。

• 当卡交易发生拒付时，您会收到拒付通知。即 notifyDispute 通知中的 disputeNotificationType 字段值为DISPUTE_CREATED。
• 当您对拒付持有疑问，可以发起拒付抗辩。该笔拒付的责任判定完成后，您会收到拒付判责通知，即notifyDispute 通知中的 disputeNotificationType 字段值为 DISPUTE_JUDGED 。判责结果由 disputeJudgedResult 字段的值进行传递：

• ACCEPT_BY_CUSTOMER：买家责任。您可以成功请款。
• ACCEPT_BY_MERCHANT：商户责任。您需要为买家退款。

退款

买家申请退款时，需确认是否符合退款条件。在符合退款条件的情况下，调用 退款 接口发起退款。可退款的时间窗口针对不同的卡会有所不同，详情参考 退款。

如果卡支付出现拒付，则在处理争议阶段，不可以发起退款。