- 集成指南
- 支持的功能（付款操作）
- 交易操作
交易操作
如果您是通过 DirectAPI 集成到网关，您可以使用 DirectAPI 操作处理交易、检索交易详细信息、存储卡详细信息等。若要执行操作，您的网关商家配置文件必须具有必要权限。 若要查看您可以使用哪些操作，请联系 your payment service provider。
初始交易操作
此部分介绍您可以用于发起交易的操作。
Authorize 操作验证付款人的卡详细信息，根据付款人的信用额度检查其是否有足够的资金，并尝试预留请求的资金。 付款人的信用额度会减去授权金额的金额，资金将预留一段时间（多数情况为 5-8 天），具体时间由卡组织和付款人的卡发行规则确定。
授权不会从付款人账户中收取资金，但会预留总订单金额，以备 Capture 操作从卡中收取资金并转账到您的账户。 与 Capture 交易不同，Authorize 交易不会出现在付款人的账户账单中。
对于成功的授权，网关将在交易响应中返回 result=SUCCESS。 仅当初始交易为 Verify 且 Authorize 请求和 Verify 交易中的卡详细信息匹配时，您才能作为后续操作执行 Authorize。
Authorize 又称"Auth"、"Authorization"。
订单确定
您可以通过在 Authorize 请求中提供 order.certainty 字段来指示要过账的授权金额的确定级别。 为此，您必须让 your payment service provider 在您的商家配置文件中启用“更改订单确定”权限。 您可以将此字段设置为以下值中的一个：
- FINAL： 全部授权金额预期要在规定时间（通常为 7 天）内通过一次或多次过账完成过账。 订单将仅在特殊情况（例如，付款人取消了订单）下取消。 在交易中提供此值可能会让交易获得降低手续费的资格。
- ESTIMATED： 授权金额是将要在规定时间（通常为 30-31 天）内过账的金额的估计值。 过账的金额有可能少些或根本不过账，或授权可能被取消。 在交易中提供此值可能会提高您的手续费。
如果您没有更改订单确定值的权限且您在此字段中提供的值与在商家配置文件中配置的默认订单确定值不匹配，请求将被拒绝。
授权撤消
在收单行支持的情况下，网关可以为取消过账、部分过账或过期授权撤消未付授权金额。 这可以帮助您遵守卡组织对于完全撤消和部分撤消的要求。
未过账授权
如果您在提交 Authorize 请求后不希望过账授权金额，则必须通过提交 VOID 请求取消您的授权。 在 transaction.targetTransactionId 字段中提供要取消授权的交易 ID。
部分过账授权
在为订单提交 Capture 请求时，您可以为订单提供低于授权金额的过账金额 (order.AuthorizedAmount)。 如果您不打算过账其余授权金额，并且收单行支持，则可以取消未付授权金额。
您可以尝试使用两种方法取消/撤消未付授权金额：
- 在
transaction.targetTransactionId字段中提交包含要取消授权的交易 ID 的 VOID 请求。 - 在 Capture 请求中的
order.expectedNumberOfCaptures中或通过 Merchant Administration 提供预期的订单 Capture 数量。 如果订单的过账总数（包括当前过账）超过或等于预期的 Capture 请求总数，如果收单行支持，网关将自动触发对未付授权金额的取消。 要实现此目的，您必须让 your payment service provider 在您的商家配置文件中启用“自动撤消未付授权金额”权限。
例如，如果您在第一个 Capture 请求中提供order.expectedNumberOfCaptures=2，网关会在处理第二个 Capture 请求时自动撤消剩余授权金额。
如果您在后续的 Capture 请求中减少了预期 Capture 数，即在第二个 Capture 请求中更新order.expectedNumberOfCaptures=1，网关将在处理第二个 Capture 请求时自动撤消剩余授权金额。 这是因为 2（订单的 Capture 总数，包括当前 Capture）超过了 1（预期 Capture 数）。 但是，如果您在后续的 Capture 请求中增加了预期 Capture 数，即在第二个 Capture 请求中更新order.expectedNumberOfCaptures=3，网关在收到第三个 Capture 请求前不会撤消未付金额。
order.expectedNumberOfCaptures 只能在 DirectAPI 版本 44 中提交。过期授权
授权在过期后具有一个有效期。 授权有效期可以在网关中针对收单行、卡类型和订单确定组合配置。
在向网关提交 Authorize 请求时，网关将根据配置的授权有效期确定授权过期日期和时间（使用卡类型、收单行、订单确定组合）。 如果收单行支持，授权过期将在 Retrieve Transaction 操作响应的 authorizationResponse.autoExpiry 字段中返回。 此字段包含网关让授权自动过期的日期和时间。
授权有效期过期后，网关将：
- 自动尝试取消授权，并释放资金，将其退回付款人（如果收单行支持）。 要实现此目的，您必须让 your payment service provider 在您的商家配置文件中启用“自动撤消过期授权”权限。
如果订单已经部分过账，并且您的收单行支持取消部分过账的授权，网关将尝试取消/撤消未付授权金额。
- 拒绝订单的任何 Capture 请求
授权更新
网关允许您延长授权期间，以及有选择地增加或减少有效授权的授权金额（如果收单行支持）。 为此，您必须让 your payment service provider 在您的商家配置文件中启用“更新授权”权限。 有关详细信息，请参见 Update Authorization。
授权延期
如果您在完成与付款人的交易时无法提交 Authorize 或 Pay 交易，网关会允许您推迟授权。 提交失败可能是由于连接或系统问题，或其他需要您推迟提交直到系统恢复连接的限制。 Visa 组织要求必须确定延期授权。
下面列出了一些您必须为 Visa 卡付款指明延期授权的情况：
- 如果您是在 POS 授权系统离线的 POS 终端上接受卡在位付款的商家，那么在系统恢复连接时您要向下游提交的授权必须标记为延期。
- 如果您是在 POS 授权系统离线的情况下接受电话订单付款的零售商，那么在系统恢复连接时您要向下游提交的授权必须标记为延期。
要延期授权，在 Authorize、Pay 或 Standalone Capture 请求中提供 transaction.deferredAuthorization 字段并将字段值设置为 TRUE。 如果不提供此字段，默认值将设置为 FALSE。
对于运输商家，您在旅行结束时为旅行期内的所有付款的汇总金额提交的授权必须标记为延期。 有关详细信息，请参见聚合运输费用付款。
常见问题
若要过账比订单的授权金额更多的金额，您在网关上的商家配置文件必须启用“超额过账”权限。 请参见超额过账
可以，这称为 Standalone Capture 请求，如果收单行支持，您只需提交 Capture 请求，其中应包含您的收单行返回的授权代码（在授权响应中）。
Pay 操作有效地将 Authorize 和 Capture 合并到一条消息内。 一个交易会授权付款并将资金从付款人账户转移到您的账户。
如果您想要作为后续操作提交 Pay，您必须有成功的验证交易，并且 Pay 请求和 Verify 交易中的卡详细信息必须一致。
Pay 交易的订单确定级别设置为 FINAL。 有关详细信息，请参见订单确定。
Pay 又称"Sale"、"Purchase"。
Initiate Browser Payment 操作来发起 Pay 操作。 有关详细信息，请参见实施浏览器付款集成。Auto Capture
Auto-Capture 是 Pay 操作的变型，允许具有执行 Pay 交易权限且使用仅支持 Authorize/Capture 交易的收单行的商家先执行 Authorize，然后自动触发 Capture。 使用此交易类型，Pay 请求转换为 Authorize 和 Capture 操作。
此操作可以使用 Direct Payment、Hosted Session 或 Batch 集成模式执行。
Authorize 和 Capture 请求的交易识别码均为您在初始 Pay 请求中提供的交易识别码。 在 Pay 响应中，transaction.type 字段指示尝试执行请求的上一次交易，即 Authorize 或 Capture。
您可以使用 Retrieve 操作检索 Auto-Capture 操作的结果。 返回尝试执行请求的上一次交易的结果。
您可以使用 Void Pay 操作取消自动过账的 Pay 交易。 执行此操作时，Mastercard Gateway：
- 会尝试对 Capture 交易执行“Void Capture”。
- 如果“Void Capture”成功，将为 Authorization 尝试“Void Authorization”。 如果“Void Capture”未成功，那么响应将指示取消失败；且不尝试 Void Authorization。
授权延期
您可以在 Pay 请求中提供指示器来延期授权。 有关详细信息，请参见授权延期。
Verify 操作允许您在执行 Pay 或 Authorize 交易前先验证付款人的账户详细信息。 它使用收单行支持的验证方法验证付款详细信息。 例如，如果收单行支持地址验证服务 (AVS)，那么 Verify 将发送包含零交易金额的仅 AVS 交易和付款人的地址详细信息。
Standalone Capture 交易是授权在外部对网关执行的过账交易。 向网关提交 Standalone Capture 时，您必须在 transaction.authorizationCode 字段中提供外部生成的授权代码，以及其他强制字段。
如果您已在商家配置文件中启用了过账权限，则可以提交 Standalone Capture。
Standalone Capture API 参考 [REST][NVP]
授权延期
您可以在 Standalone Capture 请求中提供一个表示推迟授权的指示符。 有关详细信息，请参见授权延期。
Standalone Refund 交易是一种 Refund 交易，允许您将您账户中的资金转移给付款人，但跟上一次购买无关。 当您希望贷记付款人账户而不将贷记与之前的交易关联时，可以执行独立退款。
使用 Disbursement 操作，您可以在需要时将资金发送到付款人的卡账户，例如，支付游戏或投注奖金或支付付款人的信用卡账单。 执行 Disbursement 时，不需要付款人的账单和送货详细信息，也不适用卡安全码 (CSC) 验证。 Disbursement 可以在没有事先交易的情况下或在验证付款人的账户详细信息后执行。
后续操作
此部分介绍您可以对初始交易（Authorize 或 Pay）执行的操作。
若要查看在您的商家配置文件中配置了哪些操作，请联系 your payment service provider。
使用 Update Authorization 操作，您可以：
- 延长现有授权的有效期
- 有选择地增加或减少授权金额
如果您只是要延长授权期间，请不要在请求中提交 transaction.amount。 更新后的授权过期日期和时间在 Retrieve Transaction 响应的 authorizationResponse.autoExpiry 字段中返回。 建议您在原始授权的有效期内提交 Update Authorization 请求。
如果提供的金额大于现有授权的金额，那么授权金额将更新为新金额。 例如，如果现有授权金额为 100 美元，您在 Update Authorization 请求中提供 120 美元作为交易金额，那么可以过账的新授权金额将为 120 美元。
如果提供的金额小于现有授权的金额，那么授权金额将更新为新金额。 例如，如果现有授权金额为 100 美元，您在 Update Authorization 请求中提供 80 美元作为交易金额，那么可以过账的新授权金额将为 80 美元。 网关会自动处理 20 美元剩余授权金额的撤消请求（如果收单行支持）。
请注意，仅当满足以下条件时网关才能够更新现有授权：
- 您在网关上的商家配置文件必须由 your payment service provider 启用“更新授权”权限。
- 订单货币必须与现有授权的货币匹配。
- 现有授权必须为有效、成功和完全批准状态。
订单总额
在 Update Authorization 请求成功后（卡或 PayPal），订单金额 (order.amount) 和授权总金额 (order.totalAuthorizedAmount) 将更新为 Update Authorization 交易的交易金额 (transaction.amount)。 不论 Update Authorization 交易是被提交到收单行还是由网关自动审批 (response.gatewayCode=APPROVED_AUTO)，这都适用。 不过，如果您选择为超额 Capture 请求绕过授权更新（通过提交 transaction.authorizationAdjustmentActions=NO_ACTION，参见超额过账），并且网关将超额 Capture 提交到收单行，订单总额将不更新。
response.gatewayCode=APPROVED_AUTO) 仅在提供的金额大于现有授权金额时适用。 订单小计
您可以在卡或 PayPal 付款的 Update Authorization 请求中提供以下小计金额：
order.itemAmountorder.shippingAndHandlingAmountorder.taxAmountorder.discount.amount（仅限卡付款）order.gratuityAmount（仅限卡付款）
order.cashbackAmount。网关不会验证小计金额的总和是否等于 transaction.amount（即 order.amount）；但在使用 PayPal 付款时，您必须确保这一点。
附加费
您可以使用以下任一字段在 Update Authorization 请求中更新附加费金额：
order.surchargeAmount: 如果您提供了预先计算的附加费金额，则使用此字段。order.netAmount: 如果网关计算附加费金额（根据您的附加费规则），则使用此字段。
order.surchargeAmount，包含此字段的请求将被拒绝。 如果您在 PayPal 付款中提供 order.netAmount，处理交易时将不应用附加费。Capture 操作使用初始 Authorize 操作后获取的授权将资金从付款人账户转移到您的账户。 Capture 应始终在成功授权之前执行，且至少必须通过 Capture 请求发送授权 ID。 过账金额时使用的货币必须与授权交易使用的货币匹配。
过账通常由网关或通过收单行主机进行批处理，因此，在批处理结束、结算发生前资金不会实际转账。
Capture 又称"Bill"、"Complete"。
如果在商家配置文件中启用了超额过账权限，过账总额可以超过原始授权金额。
超额过账是过账的变体，允许您执行金额超过授权金额的过账。 允许的超额以原始授权金额的百分比指定，由 your payment service provider 确定。 如果过账达到或超过原始授权金额，每个非部分过账的订单只能执行一次超额过账。
在提交超额 Capture 请求时，网关将自动尝试将授权金额更新为您要过账的金额。 如果收单行支持更新授权，网关将向收单行提交 Update Authorization 请求。 如果不支持，网关将自动审批授权更新（最多为您为商家配置文件配置的超额过账限制）。
如果您不希望网关在向收单行提交 Capture 请求前尝试更新授权，请在 Capture 请求中提交 transaction.authorizationAjustmentAction=NO_ACTION。 请注意，如果授权值与过账不匹配，订单可能没有退单保护。
如果您想要部分过账授权金额或要了解其他相关信息，请参见常见问题。
Refund 允许您将现有订单的资金退还到付款人账户。 仅当资金转账通过 Pay 或 Capture 完成时才能够执行退款。 您可以对原始交易执行任何数量的退款交易，但退款金额不能超过通过与订单相关的所有购买或过账交易获取的总额。
执行退款可能出于很多原因，例如，不需要的商品、错误商品或次品退货。
退款授权
默认情况下，在将退款请求提交到收单行进行清算和结算之前，网关会自动尝试通过发卡机构向退款授权（在收单行支持的情况下）。这样，发卡机构可以验证退款请求中提供的卡详细信息，以确保退款成功。
退款授权在线执行，并实时返回响应。这有很多好处：
- 如果退款成功或未成功，您会立即收到发卡机构的通知。 这样，当发卡机构的响应是拒绝时，您可以采取适当的行动。 例如，如果用于退款交易的卡不再有效，发卡机构拒绝退款授权。您可以联系付款人安排通过其他付款方式退款。
- 发卡机构会立即收到退款请求的通知，从而可以将有关退款的信息即时显示给付款人。另外还可以让他们有效地管理付款人质询/投诉。
如果您不希望网关为退款提交授权请求，必须启用“支持无授权退款”特权。即使启用了此特权，您也可以通过在 Refund API 请求中设置字段 action.refundAuthorization = true 来请求对退款的授权。
如果退款授权成功，支付服务器将继续处理退款，否则退款将被拒绝。 退款交易的结果会在交易响应中返回。从发卡机构收到的授权代码将显示在 Merchant Administration 中。
特定过账的退款
您必须在“退款”部分选择目标过账，然后输入退款金额。 如果有多个过账，则将显示新的 UI，否则，如果有一个过账，将显示现有的 UI。 在使用 API 的过渡期间，transaction.targetTransactionld 仅当存在多个过账时才是强制的。
如果在商家配置文件中启用了超额退款权限，订单的退款总额可以超过订单成功过账的金额。
允许的超出 DirectAPI 交易过账金额的额度可以在 Merchant Administration 的“集成设置”中按币种配置。 如果您没有为某个币种设置超额退款限制，则使用此货币的订单的超额退款将被拒。
提交退款时，订单的退款总额（包括已尝试退款）超过该订单已过账总金额的金额不能超过允许的最大超出额度。 例如，如果您通过 DirectAPI 提交某个订单的超额退款，订单的总过账金额为 100 美元，您为 DirectAPI 交易设置的超额退款限制为 20 美元，那么您最多可以退还 120 美元。
使用 Disbursement 操作，您可以在需要时将资金发送到付款人的卡账户，例如，支付游戏或投注奖金或支付付款人的信用卡账单。 执行 Disbursement 时，不需要付款人的账单和送货详细信息，也不适用卡安全码 (CSC) 验证。 Disbursement 可以在没有事先交易的情况下或在验证付款人的账户详细信息后执行。
Retrieve Transaction 允许您使用订单 ID 和交易 ID 检索交易详细信息。 由于交易 ID 识别订单内的交易，因此两个 ID 都需要提供。
Void 尝试立即删除/撤消交易请求。 取消只能对在一天结束前收单行尚未发送到银行进行处理的交易执行。 如果交易已由收单行发送进行处理，那么您必须执行 Refund 而不是 Void。
您可以取消 Authorize、Capture、Pay 或 Refund 交易。 对 Authorize 执行的取消将立即解冻所有预留的资金。 对于所有其他交易类型，取消将阻止资金转账。
Referral 操作使用从发卡机构获取的授权代码作为新 Authorization 或 Pay 交易重新提交参考的初始交易（收到 "Refer to Issuer" 收单行响应的 Authorization 或 Pay 交易）。
可能需要付款人提供其他信息以帮助发卡机构审批交易并提供授权代码/手动授权 ID。
当付款人对支付给您的付款有争议时将发生退单。 例如，未收到商品，或付款人未授予向您付款的权限。Your payment service provider 可以选择将退单交易的详细信息导入到网关，以便可供您用于搜索和报告目的。Your payment service provider 也可以选择针对原始订单记录每个退单交易或使用独立的退单交易创建新订单。
网关可以为单个订单创建多个退单交易。 您可以对包含退单交易的订单执行后续交易，例如，取消或退款。
成功记录的退单交易将在 Retrieve Transaction/Retrieve Order 响应中返回以下字段：
order.status=CHARGEBACK_PROCESSED或DISPUTED： 在创建了退单交易时，对应的订单的状态将更新，以表示存在付款人提出的争议。order.status=DISPUTED指示争议已提出，但资金尚未转移。order.status=CHARGEBACK_PROCESSED指示退单要求已经处理，资金将从商家账户中转出或转入。
order.chargeback.amountorder.chargeback.currencytransaction.dispute参数组： 有关退单争议的信息，例如，争议事件、日期等。transaction.type=CHARGEBACKtransaction.source=SERVICE_PROVIDERgatewayEntryPoint=SERVICE_PROVIDER_API