Cancel or Refund
适用于 EC 和 In-Store（线下）场景。
商户可以使用该接口来关闭或退还交易的金额，无论原始交易状态如何。EVO Cloud 将判断交易状态并自动发起 cancel 或 refund。
Make a cancel or refund request
Step 1: Make a cancel or refund request
当您收到 payment.status 为 Captured 或 Authorised 的支付结果时，可以从您的服务器向 EVO Cloud 端点
/g2/v1/payment/mer/{sid}/cancelOrRefund
发起 HTTP POST 请求以 refund 初始 payment，并指定以下参数。
| 查询参数 | 必填 | 说明 |
|---|---|---|
merchantTransID | M | 初始 Payment 的 merchantTransInfo.merchantTransID。 |
| Body 参数 | 必填 | 说明 |
|---|---|---|
merchantTransInfo | M | 本次 refund 的引用信息，包含唯一的 merchantTransID 和 merchantTransTime（发起请求的时间）。 |
transAmount | O | refund 支付的币种与金额。金额须符合该币种的最小货币单位。 |
initiatingReason | O | 可在该字段中说明本次请求的原因。 |
paymentMethod | O | 支付方式对象。 |
paymentMethod.type | O | 本文档场景下须为 card。 |
webhook | O | 用于接收通知的 URL。指定后可在支付成功后从 EVO Cloud 接收通知。 |
metadata | O | 您可在请求中自定义的引用信息，将在响应中原样回显。 |
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 特定限制的权威依据。
如果请求成功，响应中将包含一个 cancel 或 refund 对象和一个 payment 对象，分别提供 cancel 或 refund 和原始 payment 的状态及相关信息。
cancel 或 refund 对象详细信息：
cancel.status或refund.status：capture 的状态，必填。取值可为Success、Failed或Received。如果XXX.status为Received，您需要再发起一次 HTTP GET 请求以获取 capture 的最终状态（详见 Step 2），或等待 EVO Cloud 的通知 webhook。cancelOrRefund：用于指示交易已被 refund 或 cancel。
Step 2: Retrieve the cancel or refund result
如果收到 refund.status 或 cancel.status 为 Received，且您未使用 notification webhook，可以从 EVO Cloud 查询最终结果。
从您的服务器向 EVO Cloud 端点
/g2/v1/payment/mer/{sid}/cancelOrRefund
发起 HTTP GET 请求，并指定以下参数。
| 查询参数 | 必填 | 说明 |
|---|---|---|
merchantTransID | M | 初始 cancel 或 refund 的 merchantTransInfo.merchantTransID。 |
Error handling
For HTTP POST request to EVO Cloud: 建议在请求发送后至少等待 45 秒。如果在规定时间内未收到响应，需要从 EVO Cloud 查询结果。请参阅 Step 2 发起请求。
For HTTP GET request to EVO Cloud: 可以多次发起请求直到获取结果，建议相邻两次请求之间至少等待 45 秒。如果多次请求后仍无法获取结果，可以改为发起一次新的 cancelOrRefund 请求。
