交易
交易是对订单执行的操作。 可能是对付款人或卡进行身份验证、预留付款人资金，或在您和付款人之间转移资金。 您通过向 Mastercard Gateway 发送 API 请求在系统中发起交易，请求继而被处理并转发给相关的付款方式提供商或收单行。 要执行任何 API 操作，如发起交易，您必须在您在网关上的商家配置文件上设置所需权限。 要检查您可以发起哪些交易，请联系 your payment service provider。 与信用卡相比，非卡付款或借记网络的 API 操作集可能有限。
以下部分描述了各个卡交易的用例。 包括只包含强制字段的简单请求示例：使用信用卡付款方式，提供存储的信用卡详细信息作为令牌。 有关更多请求和响应示例，请参阅 Postman 集合。
初始、独立和后续交易
Mastercard Gateway 中支持的交易根据使用方式可分为四类：
- 初始
初始交易创建新订单并开始销售实例的付款流。 这些交易需要一个唯一的订单 ID 来定义新订单。 以下交易类型可以作为初始交易：
- 独立
独立交易是一种特殊类型的初始交易，在订单的初始交易在网关之外执行或您只是不想将交易与现有订单关联的情况下使用。 这些交易在业内也被称为： 无引用、不匹配或未关联的交易，由于存在欺诈风险默认不启用。
以下交易类型可以用作独立交易：
- 后续
后续交易与现有订单相关，因为它们会以某种形式修改或推进该订单。 这些交易必须使用其订单 ID 链接到初始交易。
以下交易类型可以作为后续交易：
- 信息传达
信息传达交易由付款处理器或收单行创建，提供有关订单的其他信息。
有关 Authorize 的详细信息，请参阅 Authorize。
Authorize
AUTHORIZE 交易验证付款人的卡详细信息，根据付款人的信用额度检查其是否有足够的资金，并尝试预留请求的资金。 付款人的信用额度会减去授权金额的金额，资金将预留一段时间（多数情况为 5-8 天），具体时间由卡组织和付款人的卡发行规则确定。 对于成功的授权，网关将在交易响应中返回 result = SUCCESS。
授权不会从付款人账户中收取资金，但会预留总订单金额，以备 CAPTURE 交易从卡中收取资金并转账到您的账户。 与 CAPTURE 交易不同，AUTHORIZE 交易不会出现在付款人的账户账单中。
许多网上银行系统现在提供授权活动的通知。
AUTHORIZE 交易可以是初始交易（没有先前的相关交易）或 VERIFY 或 AUTHENTICATE_PAYER 之后的后续交易。 在后一种情况下，VERIFY 或 AUTHENTICATE_PAYER 请求中的卡详细信息必须与 AUTHORIZE 相匹配。
如果您需要过账超过您的授权的金额，或者您需要过账在网关外执行的授权，请分别参阅使用超额过账和 Standalone Capture。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
设置订单确定性
您可以通过在 AUTHORIZE 请求中提供 order.certainty 字段来指示要过账的授权金额的确定性级别。 为此，您必须让 your payment service provider 在您的商家配置文件中启用“更改订单确定”权限。 您可以将此字段设置为以下值中的一个：
- 最终
全部授权金额会在规定时间内（通常为 7 天）通过一次或多次过账完成过账。 只有在特殊情况下才会取消订单（例如付款人取消了购买）。 在交易中提供此值可能会让交易获得降低手续费的资格。
- 估计
授权金额是将要在规定时间（通常为 30-31 天）内过账的金额的估计值。 过账的金额有可能少些或根本不过账，或授权可能被取消。 在交易中提供此值可能会提高您的手续费。
如果您没有更改订单确定值的权限且您在此字段中提供的值与在商家配置文件中配置的默认订单确定值不匹配，请求将被拒绝。
撤销授权
在收单行支持的情况下，网关可以为取消过账、部分过账或过期授权撤消未付授权金额。 这可以帮助您遵守卡组织对于完全撤消和部分撤消的要求。
- 未过账授权
如果您不想在提交 AUTHORIZE 请求后过账授权金额，则必须通过提交 VOID 请求来取消您的授权。 在
transaction.targetTransactionId字段中提供要取消授权的交易 ID。 - 部分过账授权
为订单提交 CAPTURE 请求时，您可以提供低于 AUTHORIZE 请求中定义的
(order.AuthorizedAmount)订单授权金额的 CAPTURE 金额。 如果您不打算过账其余授权金额，并且收单行支持，则可以取消未付授权金额。 - 在
transaction.targetTransactionId字段中提交包含要取消 AUTHORIZE 交易的交易 ID 的 VOID 请求。 - 在 CAPTURE 请求中或通过 Merchant Administration 在
order.expectedNumberOfCaptures字段内为订单提供预期的 CAPTURE 数量。 如果订单的 CAPTURE 总数（包括当前 CAPTURE）超过或等于预期的 CAPTURE 请求总数，如果收单行支持，网关将自动触发对未付授权金额的 VOID。 要允许自动触发，您必须在商家配置文件上启用“自动撤消未付授权金额”权限 your payment service provider。 - 过期授权
- 自动尝试取消授权，并释放资金，将其退回付款人（如果收单行支持）。 要实现此目的，您必须让 your payment service provider 在您的商家配置文件中启用自动撤消过期授权权限。
如果订单已部分过账，并且您的收单行支持取消部分过账的授权，网关将尝试取消/撤消未付授权金额。
- 拒绝对订单发起的任何 Capture 请求
- 更新授权
- 延期授权
- 您是在 POS 授权系统离线的 POS 终端上接受卡在位付款的商家。
- 如果您是零售商，通过电话订单接受付款，而 POS 授权系统处于离线状态。
您可以尝试通过两种方法取消（撤消）未付授权金额：
例如，如果您在第一个 CAPTURE 请求中提供 order.expectedNumberOfCaptures = 2，网关会在处理第二个 CAPTURE 请求时自动撤消剩余授权金额。
如果您在后续的 CAPTURE 请求中减少了预期 Capture 数（例如，在第二个 CAPTURE 请求中更新 order.expectedNumberOfCaptures = 1），网关将在处理第二个 CAPTURE 请求时自动撤消剩余授权金额。 这是因为 2（订单的 CAPTURE 总数，包括当前 CAPTURE）超过 1（预期 CAPTURE 数）。 但是，如果您在后续的 CAPTURE 请求中增加了预期 CAPTURE 数（例如，在第二个 CAPTURE 请求中更新 order.expectedNumberOfCaptures = 3），网关在收到第三个 CAPTURE 请求前不会撤消未付金额。
授权在过期后具有一个有效期。 授权有效期可以在网关中针对收单行、卡类型和订单确定组合配置。
在向网关提交 Authorize 请求时，网关将根据配置的授权有效期确定授权过期日期和时间（使用卡类型、收单行、订单确定组合）。 如果收单行支持，授权过期将在 Retrieve Transaction 操作响应的 authorizationResponse.autoExpiry 字段中返回。 此字段包含网关让授权自动过期的日期和时间。
一旦授权有效期到期，网关将：
网关允许您延长授权期限，并可选择增加或减少有效授权的授权金额（如果收单行支持）。 为此，您必须让 your payment service provider 在您的商家配置文件中启用“更新授权”权限。 有关详细信息，请参见 Update Authorization。
如果您无法在付款人完成交易时提交 AUTHORIZE 或 PAY 交易，可以延期授权。 失败可能是由于连接或系统问题，或需要您在系统恢复连线时向下游提交授权的其他限制所致。 Visa 组织要求必须确定延期授权。
下面列出了一些您必须为 Visa 卡付款指明延期授权的情况：
要延期授权，在 AUTHORIZE、PAY 或 STANDALONE CAPTURE 请求中提供 transaction.deferredAuthorization 字段并将字段值设置为 TRUE。 如果不提供此字段，则使用默认值 FALSE。
Capture
Capture 交易（也称为“bill”或“complete”）使用初始 AUTHORIZE 操作后获得的授权将资金从付款人的账户转移到您的账户。 "CAPTURE 之前必须始终有成功的授权。 过账金额时使用的货币必须与授权交易使用的货币匹配。
过账通常由网关或收单行的主机进行批处理，因此直到批处理结束并进行结算后，资金才会发生实际转移。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
要过账在网关外执行的 Authorization，请参阅 Standalone Capture。
使用超额过账
如果您的商家配置文件中启用了“执行超额过账”权限，您过账的总金额可能会超过原始授权金额。
超额过账是 CAPTURE 交易的一个变体，是指您要执行过账的金额大于授权金额。 允许的超额以原授权金额的百分比指定，由 your payment service provider 确定。
在提交超额 CAPTURE 请求时，网关将自动尝试将授权金额更新为您要过账的金额。 如果收单行支持更新授权，网关将向收单行提交 UPDATE AUTHORIZATION 请求。 如果不支持，网关将自动审批授权更新（最多为您为商家配置文件配置的超额过账限制）。
如果您不希望网关在向收单行提交过账之前尝试更新授权，请在请求中将 transaction.authorizationAjustmentAction 字段设置为 NO_ACTION。
Chargeback
当付款人对您的付款提出异议时，会发生 CHARGEBACK 交易。 例如，未收到商品，或付款人未授予向您付款的权限。Your payment service provider 可以将退单交易的详细信息导入到网关，以便可供您用于搜索和报告目的。Your payment service provider 也可以针对原始订单记录每个退单交易或使用独立的退单交易创建新订单。
- 如果您在多个商家配置文件之间共用一个 SE 编号或银行商家 ID（收单银行分配给您的标识符），会为每个配置文件创建独立的 Chargeback 交易。
- 网关记录退单交易仅用于参考 – 交易不会发送到收单行进行下游处理。
网关可以为单个订单创建多个退单交易。 您可以对包含退单交易的订单执行后续交易，例如，取消或退款。
成功记录的退单交易将在 RETRIEVE TRANSACTION 和 RETRIEVE ORDER 交易响应中返回以下字段：
- order.status
当创建 Chargeback 交易时，相应订单的状态会更新，以表示付款人提出异议。
- order.status
DISPUTED 表示出现争议，但资金尚未发生转移。
- order.status
CHARGEBACK_PROCESSED 指示退单要求已经处理，资金将从商家账户中转出或转入。
- order.status
- order.chargeback.amount - 退单金额。
- order.chargeback.currency - 退单货币。
- transaction.dispute 对象 - 有关退单争议的信息，例如，争议事件和日期。
- transaction.type - CHARGEBACK
- transaction.source - SERVICE_PROVIDER
- gatewayEntryPoint - SERVICE_PROVIDER_API
Disbursement
使用 DISBURSEMENT 交易，您可以将资金发送到付款人的卡账户，例如，游戏或投注奖金，或支付付款人的信用卡账单。
在 DISBURSEMENT 请求中，不需要付款人的账单和送货详细信息，也不适用卡安全码 (CSC) 验证。
DISBURSEMENT 交易可以是初始交易（没有先前的相关交易），也可以是用于验证付款人账户详细信息的 VERIFY 之后的后续交易。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "DISBURSEMENT",
"disbursementType": "GAMING_WINNINGS",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Pay
PAY 交易（也称为“购买”或“销售”）将 AUTHORIZE 和 CAPTURE 合并为一条消息。 单笔交易授权付款并将资金从付款人的账户一次性转入您的账户。 您可以在 PAY 请求中提供指示器来延期授权。 有关详细信息，请参阅延期授权。
PAY 交易可以是初始交易（没有先前的相关交易），也可以是用于验证付款人账户详细信息的 VERIFY 之后的后续交易。 在后一种情况下，VERIFY 和 PAY 请求中的卡详细信息必须匹配。
PAY 交易的订单确定性级别设置为 FINAL。 有关详细信息，请参阅设置订单确定性。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "PAY",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
使用自动过账
自动过账是 PAY 交易的一个变体，允许商家与仅支持 AUTHORIZE 和 CAPTURE 交易的收单行进行 PAY 交易。 当网关收到 PAY 请求，确定收单行不支持该请求时，网关会自动将 PAY 请求转换为 AUTHORIZE 请求，然后自动触发 CAPTURE。
要使用此交易，必须由 your payment service provider 在您的商家配置文件上为您启用 PAY 权限。 AUTHORIZE 和 CAPTURE 请求的交易标识符都是您在原始 PAY 请求中提供的交易标识符。 在 PAY 响应中，transaction.type 字段指示尝试执行请求（AUTHORIZE 或 CAPTURE）的最后一个交易。
您可以使用 RETRIEVE TRANSACTION 操作检索自动过账的结果。 将返回尝试执行请求的最后一个交易的结果。
您可以使用 VOID 交易来取消自动过账的 PAY 交易。 当您为自动过账发送 VOID 请求时，网关会：
- 尝试对 CAPTURE 交易进行 VOID。
- 如果第一个 VOID 成功，将会尝试为 AUTHORIZATION 交易发送第二个 VOID。 如果第一次 VOID 不成功，则响应表明 VOID 失败，并且不会尝试第二次 VOID。
Referral
当 AUTHORIZE 或 PAY 交易失败，收到“参考发卡机构”收单行响应（在响应的 response.gatewaycode 字段中提供）时，需要 REFERRAL 交易。
付款人可能需要提供其他信息，以便发卡机构批准交易并提供授权代码或手动授权 ID。
使用 REFERRAL 交易作为新 AUTHORIZE 或 PAY 交易重新提交引用的初始交易，提供从发卡机构获取的授权代码。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "REFERRAL",
"transaction": {
"authorizationCode": "123456"
}
}
Refund
通过 REFUND 交易，您可以将现有订单的资金退还到付款人的账户中，例如，如果他们退回不想要的、错误的或有缺陷的商品。 仅当资金转移通过 PAY、CAPTURE 或 STANDALONE CAPTURE 交易完成时才可进行退款。
您可以对原始交易执行任意数量的 REFUND 交易，但退款不能超过通过与订单关联的 PAY 或 CAPTURE 交易获取的总金额。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "REFUND",
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
使用退款授权
默认情况下，在将退款请求提交到收单行进行清算和结算之前，网关会自动尝试通过发卡机构向退款授权（在收单行支持的情况下）。 这可以让发卡机构能够验证退款请求中提供的卡详细信息，以确保退款成功。
退款授权在线执行，并实时返回响应。 这有很多好处：
- 如果无法退款，您会立即收到发卡机构的通知，并可以采取适当的措施。 例如，如果用于 REFUND 交易的卡不再有效，发卡机构将拒绝退款授权。 您可以联系付款人通过其他付款方式安排退款。
- 发卡机构会立即收到退款请求的通知，从而可以将有关退款的信息即时显示给付款人。 另外还可以让他们有效地管理付款人质询/投诉。
如果您不希望网关为您的 REFUND 交易提交授权请求，请联系 your payment service provider 启用“支持无授权退款”权限。 即使您已启用此权限，您也可以通过在 REFUND 请求中将 action.refundAuthorization 字段设置为 true 来请求对特定退款的授权。
如果退款授权成功，网关将继续退款。 REFUND 交易的结果将在响应中返回。 您可以在 Merchant Administration 中查看从发卡机构收到的授权代码。
退还特定过账
如果对单个订单执行了多次过账，必须确定在退还全部或部分订单时退还哪次过账：
- 要在 Merchant Administration 中退还特定过账，在“退款”部分选择目标过账，然后输入退款金额。 如果订单有多个过账，将显示一个新 UI 窗口，供您选择要退款的过账。
- 要使用 API 请求退还特定过账，在请求中加入 transaction.targetTransactionld 字段来确定要退还的特定过账，并将其设置为适用 CAPTURE 请求的交易 ID。
使用超额退款
如果您的商家配置文件中启用了“执行超额退款”权限，订单的退款总额可能会超过成功过账的金额。
允许的超出 API 交易过账金额的额度可以在 Merchant Administration 的“管理 > 集成设置”页面按币种配置。 如果您没有为某个币种设置超额退款限制，则使用此货币的订单的超额退款将被拒。
提交退款时，订单的退款总额（包括已尝试退款）超过该订单已过账总金额的金额不能超过允许的最大超出额度。 例如，如果您通过 API 为总过账金额为 100 USD 的订单提交超额退款，并且您将 API 交易的超额退款限额设置为 20 USD，那么您最多可以退款 120 USD。
Standalone capture
STANDALONE CAPTURE 交易是一个 CAPTURE，其授权在网关之外执行。 向网关提交 STANDALONE CAPTURE 请求时，您必须在 transaction.authorizationCode 字段中提供外部生成的授权代码。 您还需要提供通常在 AUTHORIZATION 交易中作为强制字段提供的所有卡详细信息，因为由于是外部授权，网关还没有这些信息。
如果您的商家配置文件中启用了“执行独立过账”权限，您可以提交 STANDALONE CAPTURE。
如果您需要过账的金额大于授权的金额，请参阅使用超额过账。
您可以在 STANDALONE CAPTURE 请求中提供一个指示器，来在需要时指示外部授权是延期授权。 有关详细信息，请参阅延期授权。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "CAPTURE",
"order": {
"amount": "100.00",
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
},
"transaction": {
"authorizationCode": "123456",
"amount": "100.00",
"currency": "EUR"
},
}
Standalone refund
STANDALONE REFUND 交易是一个 REFUND 交易，允许您在没有之前的购买交易的情况下，将资金从您的账户转回给付款人。 当您想要向付款人账户存入资金，而不将该款项与之前的交易关联时，可以使用 STANDALONE REFUND。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "REFUND",
"sourceOfFunds": {
"token": "<token>"
},
"transaction": {
"amount": "100.00",
"currency": "EUR"
}
}
Update authorization
UPDATE AUTHORIZATION 交易允许您：
- 延长现有授权的有效期。
- 有选择地增加或减少授权金额。
如果仅想延长授权期限，不要在请求中提交 transaction.amount 字段。 更新后的授权过期日期和时间在 RETRIEVE TRANSACTION 响应中的 authorizationResponse.autoExpiry 字段中返回。
如果提供的金额大于现有授权的金额，那么授权金额将更新为新金额。 例如，如果现有授权金额为 100 美元，您在 UPDATE AUTHORIZATION 请求中提供 120 美元作为交易金额，可以过账的新授权金额为 120 美元。
如果提供的金额小于现有授权的金额，那么授权金额将更新为新金额。 例如，如果现有授权金额为 100 美元，您在 UPDATE AUTHORIZATION 请求中提供 80 美元作为交易金额，可以过账的新授权金额为 80 美元。 网关会自动处理 20 美元剩余授权金额的撤消请求（如果收单行支持）。
仅当满足以下条件时，网关才能更新现有的授权：
- 您在网关上的商家配置文件必须由 your payment service provider 启用“更新授权”权限。
- 订单货币必须与现有授权上的货币相匹配。
- 现有的授权必须有效、成功且完全获得批准。
- 对于 Mastercard 卡交易，增加授权金额会自动延长授权有效期。 对于其他卡品牌，对有效期的影响取决于组织规则。
- 任何卡品牌的 S2I 收单行均不完全支持 UPDATE AUTHORIZATION 操作。 只能通过此操作减少授权金额。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "UPDATE_AUTHORIZATION"
}
管理订单总额
在 UPDATE AUTHORIZATION 请求成功后（卡或 PayPal），订单金额 (order.amount) 和授权总金额 (order.totalAuthorizedAmount) 将更新为 UPDATE AUTHORIZATION 交易的交易金额 (transaction.amount)。 不论 UPDATE AUTHORIZATION 交易是被提交到收单行还是由网关自动审批 (response.gatewayCode = APPROVED_AUTO)，这都适用。
如果您选择绕过超额 CAPTURE 请求的授权更新（通过提交 transaction.authorizationAdjustmentActions = NO_ACTION，请参阅使用超额过账），网关向收单行提交了超额 CAPTURE，订单总额不会更新。
管理订单小计
您可以在卡或 PayPal 付款的 UPDATE AUTHORIZATION 请求中提供以下小计金额：
- order.itemAmount
- order.shippingAndHandlingAmount
- order.taxAmount
- order.discount.amount（仅限卡付款）
- order.gratuityAmount（仅限卡付款）
不支持在 UPDATE AUTHORIZATION 请求中提供 order.cashbackAmount。
网关不会验证小计金额相加是否等于 transaction.amount (order.amount)。
附加费
您可以使用以下任一字段在 UPDATE AUTHORIZATION 请求中更新附加费金额：
- order.merchantCharge.amount - 如果您提供预先计算的附加费金额，请使用此字段。
- order.merchantCharge.type - 将此字段设置为 SURCHARGE，指示费用类型为附加费。
- order.netAmount - 如果网关计算附加费金额（根据您的附加费规则），则使用此字段。 净金额是在加收附加费之前订单应支付的金额。
Verify
使用 VERIFY 交易，您可以在执行 PAY 或 AUTHORIZE 交易之前验证付款人的账户详细信息。 它使用收单行支持的验证方法验证付款详细信息。 例如，如果网关确定收单行支持地址验证服务 (AVS)，网关会向收单行发送交易金额为零、包含付款人地址详细信息的仅 AVS 交易来获取验证结果。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "VERIFY",
"order": {
"currency": "EUR"
},
"sourceOfFunds": {
"token": "<token>"
}
}
Void
VOID 交易会尝试立即删除或撤消之前的交易请求。
您可以取消 AUTHORIZE、CAPTURE、PAY、REFUND、STANDALONE CAPTURE、STANDALONE REFUND 和 UPDATE AUTHORIZATION 交易。
对于 AUTHORIZE，VOID 会立即解冻所有预留资金。 对于所有其他交易类型，VOID 会阻止进行资金转移。
为 VOID 其他交易，交易不会在一天结束时被发送到收单行进行处理。 收单行发送交易进行处理后，VOID API 操作将失败，您必须执行 REFUND。
| URL | https://cn.gateway.mastercard.com/api/rest/version/72/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| HTTP 方法 | PUT |
{
"apiOperation": "VOID",
"transaction": {
"targetTransactionId": "<ID_of_transaction_to_be_voided>"
}
}