Capture

适用于 EC 和 In-Store（线下）场景。

对于部分支付方式，支付流程分两步完成：

Authorization（预授权）：验证用户的支付信息并预冻结资金。

Capture（请款）：将预冻结的资金从用户账户划转至您的账户。

对于即时支付方式，资金会在 Authorization 后立即 Capture。

对于支持 Authorization 与 Capture 分离的非即时支付方式，您可以稍后再 Capture，便于在出现问题时取消交易。

下面是支付方式与是否支持独立 Authorization/Capture 的矩阵。

支付方式	卡组织	是否支持
Card	VISA	是
	Mastercard	是
	AMEX	是
	JCB	是
	Diners / Discover	是
	UnionPay	是
	TPN	否

Manual capture

要 Capture 一笔交易，向 EVO Cloud 端点发起 HTTP POST 请求：
/g2/v1/payment/mer/{sid}/capture
Key Points:

默认行为（Default Behavior）：如果在初始 Payment 请求 /g2/v1/payment/mer/{sid}/payment 中未指定 captureAfterHours 字段，对于支持 Authorization/Capture 分离的支付方式，将采用默认 Capture 设置。

不支持独立 Capture（No Separate Capture）：对于不支持 Authorization/Capture 分离的支付方式，captureAfterHours 字段被忽略，资金会在 Authorization 后立即 Capture。

时效（Timing）：建议在 Authorization 后的 7 天内 发起 Capture 请求，因为大多数发卡行会在该时限后清除预授权。

金额限制（Amount Limit）：Capture 金额不得超过初始 Payment 金额。

Automatic capture

Payment 可由 EVO Cloud 在 Authorization 后自动 Capture，无需调用 Capture 端点。

需要在向 EVO Cloud 端点（/g2/v1/payment/mer/{sid}/payment）发起 HTTP POST 请求时指定 captureAfterHours 字段以启用此功能。EVO Cloud 后端将根据您指定的 captureAfterHours 设置自动 Capture 任务。

captureAfterHours 的有效范围为 0 到 168，即您可以设置最迟在 Authorization 后 168 小时（7 天）自动 Capture。0 表示 Authorization 后立即 Capture。

设置 Authorization 与 Capture 之间的延迟，允许您在 Capture 前 cancel 支付（例如商品缺货时）。如果取消支付，EVO Cloud 会取消后端的自动 Capture 任务。

即使一笔支付以自动 Capture 模式被预授权，您仍可在 EVO Cloud 自动 Capture 之前按手动 Capture 模式发起 Capture。如果通过此方式手动触发了 Capture，EVO Cloud 中后端的自动 Capture 任务将被取消，以避免重复 Capture。

Partial capture

部分支付方式支持对一笔支付进行部分 Capture。下面是支持部分 Capture 的支付方式与卡组织矩阵。

支付方式	卡组织
Token & Card	VISA
	Mastercard
	AMEX
	JCB
	Diners / Discover
	UnionPay

请注意：一笔支付只能 Capture 一次。如果进行部分 Capture，未 Capture 的剩余金额将被自动取消。

Make capture request

Step 1: Make a capture request

当您收到 payment.status 为 Authorised 的支付结果时，可以从您的服务器向 EVO Cloud 端点

/g2/v1/payment/mer/{sid}/capture

发起 HTTP POST 请求以手动 Capture 该支付，

并指定以下参数。

参数	必填	说明
merchantTransID	M	初始 Payment 的 `merchantTransInfo.merchantTransID`。
merchantTransInfo	M	本次 Capture 的引用信息，包含唯一的 `merchantTransID` 和 `merchantTransTime`（发起请求的时间）。
transAmount	M	支付的币种与金额。金额须符合该币种的最小货币单位。
initiatingReason	O	可在该字段中说明本次请求的原因。
webhook	O	用于接收通知的 URL。指定后可在支付成功后从 EVO Cloud 接收通知。
paymentMethod	O	支付方式对象。
paymentMethod.type	O	本文档场景下须为 `card`。
metadata	O	您可在请求中自定义的引用信息，将在响应中原样回显。Metadata

paymentMethod 对象的更多细节：

1.paymentMethod.type：请求中设置为 card。

2.paymentMethod.card.encryptedCardInfo：加密后的卡信息。如果使用 EVO Cloud 客户端方案安全加密用户卡信息，前端会从 EVO Cloud SDK 获取该值，需发送至您的服务器，再由服务器原样转发至 EVO Cloud。

3.paymentMethod.card.cardInfo：卡信息原始数据。如果将原始卡数据采集并发送至 EVO Cloud，需要在此对象中指定 cardNumber、expiryDate、cvc（可选）、track2 与 holderName。对于部分 UnionPay 借记卡，expiryDate 也为可选。
（如果 paymentMethod.card.encryptedCardInfo 和 paymentMethod.card.cardInfo 同时存在，将以 paymentMethod.card.cardInfo 为准。）

4.paymentMethod.card字段

字段路径	必填/选填	条件	说明
`paymentMethod.card`	M	`paymentMethod.type=card`	卡相关交易对象。
`paymentMethod.card.encryptedCardInfo`	O	已批准加密卡集成方案	加密卡信息。
`paymentMethod.card.cardInfo`	O	已批准卡信息集成方案	卡信息容器。
`paymentMethod.card.cardInfo.cardNumber`	M	手动/MOTO 或最终 schema 要求	卡号。在示例或测试数据中请勿使用真实值。
`paymentMethod.card.cardInfo.expiryDate`	O	MOTO 必填	过期日期，`MMYY` 格式。
`paymentMethod.card.posEntryMode`	O	POS 卡通道	卡数据输入方式。
`paymentMethod.card.pinFlag`	O	终端支持 PIN	`true` 表示终端可接受 PIN；`false` 表示不接受。
`paymentMethod.card.termReadability`	O	提供终端能力时	终端卡数据输入能力。
`paymentMethod.card.icCardCondCode`	O	UnionPay IC 场景	UnionPay 卡条件码。
`paymentMethod.card.noSecretNoSignFlag`	O	UnionPay 场景	UnionPay 无密/无签标识。
`paymentMethod.card.cardInfo.track1`	O	磁条或特定通道要求	Track 1 数据。最终字段名以已批准的 schema 为准。
`paymentMethod.card.cardInfo.track2`	O	磁条、ICC、contactless 或 fallback 场景	Track 2 数据。禁止以明文存储或记录。
`paymentMethod.card.cardInfo.cardSequenceNum`	O	ICC 或 contactless 场景	IC 卡序列号。
`paymentMethod.card.cardInfo.icCardData`	O	ICC 或 contactless 场景	EMV/ICC TLV 数据。
`paymentMethod.card.pin`	O	PIN 交易	PIN 容器（如最终 schema 中包含）。
`paymentMethod.card.pin.encryptedPin`	M	PIN 交易	加密后的 PIN block。禁止以明文记录或持久化。
`paymentMethod.card.pin.pinEncryptMethod`	M	PIN 交易	已批准的 PIN 加密方式，例如支持时的 `3DES`。
`paymentMethod.card.pin.checkValue`	O	启用密钥版本查询	用于识别适用工作密钥版本的值（如支持）。

5.Card posEntryMode 模式

posEntryMode 模式	交易活动	典型条件数据
`magnetic`	磁条读取	track2
`ICC`	接触式芯片插入	track2 、icCardData 、cardSequenceNum
`contactless`	NFC EMV 挥卡	track2 、icCardData 、cardSequenceNum
`contactless magnetic`	使用磁条通道的 contactless 交易	track2
`fallback`	EMV 回退至磁条	track2
`manual`	手工输入卡	cardNumber 、expiryDate
`MOTO`	邮购/电话订购	cardNumber 、expiryDate

最终 API schema 是字段名、长度、条件必填与 PSP 特定限制的权威依据。

以下为 10 USD Capture 请求示例：

如果请求成功，响应中将包含一个 capture 对象和一个 payment 对象。capture 对象详细信息如下：

capture 对象详细信息：

capture.status：Capture 状态，必填。取值可为 Success、Failed 或 Received。如果 capture.status 为 Received，您需要再发起一次 HTTP GET 请求以获取 Capture 的最终状态（详见 Step 2），或等待 EVO Cloud 的通知 webhook。

capture.transAmount：Capture 的币种与金额，必填。从您的请求中原样回显。

capture.merchantTransInfo：本次 Capture 的引用对象，由您的服务器生成，必填。从您的请求中原样回显。

capture.evoTransInfo：本次 Capture 的引用对象，由 EVO Cloud 生成，必填。包含 evoTransID、evoTransTime，以及部分 PSP（如 Visa 或 Mastercard）的可选字段 traceNum 与 retrievalReferenceNum。

capture.pspTransInfo：本次 Capture 的引用对象，由 PSP 生成，可选。包含 pspTransID、pspTransTime 与 authorizationCode。如果 PSP 返回，EVO Cloud 会将该信息从 PSP 转发至您的服务器。

capture.billingAmount 与 capture.billingFXRate：Capture 的用户账单币种与金额，以及 capture.transAmount.currency 与 capture.billingAmount.currency 之间的汇率，可选。如果 PSP 返回，EVO Cloud 会将该信息从 PSP 转发至您的服务器。适用于 PSP 进行货币换算的 E-Wallet 支付，或您启用了 DCC 功能的卡支付。详情请联系 EVO Cloud 客户经理。

capture.convertTransAmount 与 capture.convertTransFXRate：EVO Cloud 在将交易发送至 PSP 时，基于 transAmount 与 transAmount.currency 到目标币种的汇率计算出的币种与金额，以及 capture.transAmount.currency 与 capture.convertTransAmount.currency 之间的汇率，可选。如果您在 EVO Cloud 启用了货币换算功能且本次 Capture 适用，将提供该汇率。详情请联系 EVO Cloud 客户经理。

以下为成功响应示例：

Step 2: Retrieve the capture result

如果收到 capture.status 为 Received，且您未使用 Accept Notification webhook，可以从 EVO Cloud 查询最终结果。

从您的服务器向 EVO Cloud 端点

/g2/v1/payment/mer/{sid}/capture

发起 HTTP GET 请求，并指定以下参数。

参数	必填	说明
merchantTransID	M	初始 Capture 的 `merchantTransInfo.merchantTransID`。

以下为查询 Capture 结果示例：

以下为 GET 响应示例。POST 响应与 GET 响应类似：

Error handling

For HTTP POST request to EVO Cloud:建议在请求发送后至少等待 45 秒。如果在规定时间内未收到响应，需要从 EVO Cloud 查询结果。请参阅 Step 2 发起请求。
For HTTP GET request to EVO Cloud: 可以多次发起请求直到获取结果，建议相邻两次请求之间至少等待 45 秒。如果多次请求后仍无法获取结果，可以改为发起一次新的 Capture 请求。

Manual capture#

Automatic capture#

Partial capture#

Make capture request#

Step 1: Make a capture request#

Step 2: Retrieve the capture result#

Error handling#

Manual capture

Automatic capture

Partial capture

Make capture request

Step 1: Make a capture request

Step 2: Retrieve the capture result

Error handling