Capture

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

部分支付方式的支付流程分为两步完成：

授权（Authorization）：验证用户的支付信息并冻结资金。
完成（Capture）：将冻结的资金从用户账户转入您的账户。

对于即时支付方式，付款在授权后立刻被完成。
对于支持授权与完成分离的非即时支付方式，您可以稍后完成付款。这样在出现问题时可以取消支付。

以下是各支付方式是否支持授权与完成分离的对照表。

支付方式	支付品牌	是否支持
Token & Card（令牌及银行卡）	VISA	是
	Mastercard	是
	AMEX	是
	JCB	是
	Diners / Discover	是
	UnionPay	是
	TPN	是
E-Wallet（电子钱包）	全部	否
Online Banking（网银）	全部	否
Points（积分）	全部	否
Bank Transfer（银行转账）	全部	否
By Now Pay Later（先买后付）	全部	否
Carrier Billing（运营商代扣）	全部	否
Cash（现金）	全部	否
Prepaid Card（预付卡）	全部	否
Google Pay™️	全部	是

手动完成

如需完成，请向 EVO Payment 以下接口发起 HTTP POST 请求：

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

要点：

默认行为：如果您在初始支付请求（/g2/v1/payment/mer/{sid}/payment）中未指定 captureAfterHours 字段，对于支持授权与完成分离的支付方式，将采用默认的完成设置。
没有单独的完成：对于不支持授权与完成的支付方式，captureAfterHours 字段会被忽略，因为这类支付在授权后会立即完成。
时效：建议在授权后 7 天内发送完成请求，因为大多数发卡行会在此之后使授权失效。
金额限制：完成金额不能超过初始支付金额。

自动完成

EVO Payment 可以在授权后自动完成支付，也就是说您无需调用完成接口。

如需开启该功能，您需要在向 EVO Payment 接口（/g2/v1/payment/mer/{sid}/payment）发起 HTTP POST 请求时指定 captureAfterHours 字段。EVO Payment 后台会根据您指定的 captureAfterHours 创建自动完成任务。

captureAfterHours 的有效范围为 0 到 168，即最多可设置在授权后 168 小时（7 天）自动完成。0 表示授权后立即完成支付。

在授权与完成之间设置延迟，可以让您在完成前取消支付，例如商品缺货时。如果您取消了支付，EVO Payment 会取消后台的自动完成任务。

即使支付以自动完成模式授权，您仍可以在 EVO Payment 自动完成之前，按照手动完成方式手动完成支付。以这种方式手动触发完成时，EVO Payment 会取消后台的自动完成任务，避免重复支付。

部分完成

部分支付方式还支持部分完成。以下是支持部分完成的支付方式和支付品牌对照表。

支付方式	支付品牌
Token & Card（令牌及银行卡）	VISA
	Mastercard
	AMEX
	JCB
	Diners / Discover
	UnionPay
	TPN
Google Pay™️	全部

:::info[]

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

:::

发起完成请求

步骤 1：发起完成请求

当您获取到的支付结果中 payment.status 为 Authorised 时，可以从服务端向 EVO Payment 以下接口发起 HTTP POST 请求：

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

对该笔支付进行手动完成，并指定以下参数：

参数	是否必填	说明
merchantTransID	M	初始支付的 `merchantTransInfo.merchantTransID`。
merchantTransInfo	M	完成的参考信息，包括唯一的 `merchantTransID`，以及表示您发起请求时间的 `merchantTransTime`。
transAmount	M	支付的币种和金额。金额必须符合该币种的最小单位规则。
initiatingReason	O	您可在该字段中说明发起本次请求的原因。
webhook	O	接收通知的 URL。传入该参数后，支付成功时将收到 EVO Payment 的通知。
metadata	O	您可在请求中自定义的参考信息，会在响应中原样返回。

以下是发起 10 USD 完成的示例：

curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/capture?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_PAYMENT}\
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
-d '{
    "merchantTransInfo": {
        "merchantTransID": "YOUR_CAPTURE_TRANS_ID",
        "merchantTransTime": "2021-12-31T08:35:59+08:00"
    },
    "transAmount": {
        "currency": "USD",
        "value": "10.00"
    },
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
    "initiatingReason": "This order is completed",
    "metadata": "This is a metadata"
}'

请求成功时，响应中会包含 capture 对象和 payment 对象。capture 对象的详细说明如下：

capture 对象详细说明：

capture.status：完成状态，必填，取值可为 Success、Failed 或 Received。如果 capture.status 为 Received，您需要再发起一次 HTTP GET 请求获取完成的最终状态（详情请参阅步骤 2），或等待 EVO Payment 的通知 Webhook。
capture.transAmount：完成的币种和金额，必填，从您的请求中原样返回。
capture.merchantTransInfo：完成的参考信息对象，由您的服务端生成，必填，从您的请求中原样返回。
capture.evoTransInfo：完成的参考信息对象，由 EVO Payment 生成，必填。包含 evoTransID、evoTransTime、traceNum（可选），以及部分 PSP（如 Visa 或 Mastercard）的 retrievalReferenceNum。
capture.pspTransInfo：完成的参考信息对象，由 PSP 生成，可选。包含 pspTransID、pspTransTime 和 authorizationCode。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。
capture.billingAmount 和 capture.billingFXRate：用户账单币种及请款金额，以及 capture.transAmount.currency 与 capture.billingAmount.currency 之间的汇率，可选。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。适用于 PSP 进行货币转换的部分电子钱包支付，或您开通 DCC 功能的部分银行卡支付。详情请联系 EVO Payment 客户经理。
capture.convertTransAmount 和 capture.convertTransFXRate：交易发送至 PSP 时，EVO Payment 根据 transAmount 及 transAmount.currency 到其他币种的汇率计算出的币种和金额，以及 capture.transAmount.currency 与 capture.convertTransAmount.currency 之间的汇率，可选。当您在 EVO Payment 开通货币转换功能且本次完成使用了货币转换时，会提供该汇率。详情请联系 EVO Payment 客户经理。

以下是请求成功的响应示例：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "card": {
            "first6No": "476134",
            "last4No": "0019",
            "paymentBrand": "Visa",
            "fundingType": "credit"
        }
    },
    "payment": {
        "status": "Capturing",
        "merchantTransInfo": {
            "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "pspTransInfo": {
            "pspTransTime": "2021-12-31T08:30:59+08:00",
            "authorizationCode": "091410",
            "retrievalReferenceNum": "135616370503"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "capture": {
        "status": "Received",
        "merchantTransInfo": {
            "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CAPTURE",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "d9e9022475f84ef09932becef13f7113",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "pspData": {
        "name": "Visa"
    },
    "metadata": "This is a metadata"
}

步骤 2：查询请款结果

如果 capture.status 为 Received，且您未使用 Accept Notification（接收通知）Webhook，可以向 EVO Payment 查询最终结果。

您可以从服务端向 EVO Payment 以下接口发起 HTTP GET 请求：

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

并指定以下参数：

参数	是否必填	说明
merchantTransID	M	初始完成的 `merchantTransInfo.merchantTransID`。

以下是查询请款结果的示例：

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/capture?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_CAPTURE} \
-H "Content-Type: application/json" \
-H "DateTime: 2021-12-31T08:30:59+0800" \
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"

以下是 GET 响应示例，POST 响应与 GET 响应类似：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "card": {
            "first6No": "476134",
            "last4No": "0019",
            "paymentBrand": "Visa",
            "fundingType": "credit"
        }
    },
    "payment": {
        "status": "Captured",
        "merchantTransInfo": {
            "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "pspTransInfo": {
            "pspTransTime": "2021-12-31T08:30:59+08:00",
            "authorizationCode": "091410",
            "retrievalReferenceNum": "135616370503"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "capture": {
        "status": "Success",
        "merchantTransInfo": {
            "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CAPTURE",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "d9e9022475f84ef09932becef13f7113",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "pspTransInfo": {
            "pspTransTime": "2021-12-31T08:35:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "pspData": {
        "name": "Visa"
    },
    "metadata": "This is a metadata"
}

异常处理

向 EVO Payment 发起 HTTP POST 请求时：建议请求发送后至少等待 45 秒。如果在该时间内未收到响应，需要向 EVO Payment 查询结果，请参阅步骤 2 发起请求。

向 EVO Payment 发起 HTTP GET 请求时：您可以多次发起请求直至获取结果，建议每次后续请求前至少等待 45 秒。如果多次请求后仍无法获取结果，可以改为重新发起一次完成请求。

Features

After Payment

Features

Authentication

Tokenization

Quickstart

Payment

After Payment

ZPK

Payment

After Payment

PaymentMethod

FXRateInquiry

Payment

Payout

Capture

Coupon Reversal

Coupon Write-off

Cancel

Refund

ZPK

DataSubmission

Cryptogram

CancelOrRefund

Notification

HealthCheck

TransactionHistoryInquiry

MerchandiseCredit

Linkpay

Retrieve Linkpay

Refund

Retrieve Linkpay Refund

Notification

Cancel or Refund

Capture ​

手动完成 ​

自动完成 ​

部分完成 ​

发起完成请求 ​

步骤 1：发起完成请求 ​

步骤 2：查询请款结果 ​

异常处理 ​

Capture

手动完成

自动完成

部分完成

发起完成请求

步骤 1：发起完成请求

步骤 2：查询请款结果

异常处理