Refund

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

如果您需要将资金退还给用户（例如用户退货），需要对该笔支付进行退款。

只有已完成的支付才能退款。尚未完成的支付需要改为撤销。详情请参阅 Cancel（撤销） 章节。

您可以退还全部已完成金额，也可以退还部分已完成金额。只要累计退款金额不超过已完成金额，也可以进行多次部分退款。

退款的最长时限为支付完成后 365 天。

单笔支付订单的部分退款次数不能超过 50 次。

同一支付订单的多次退款请求之间必须间隔至少 1 分钟。

发起退款请求

步骤 1：发起退款请求

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

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

对初始支付进行退款，并指定以下参数：

查询参数	是否必填	说明
merchantTransID	M	初始支付的 merchantTransInfo.merchantTransID。

Body 参数	是否必填	说明
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}/refund?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_TRANS_ID_OF_INITIAL_REFUND",
        "merchantTransTime": "2021-12-31T08:35:59+08:00"
    },
    "transAmount": {
        "currency": "USD",
        "value": "10.00"
    },
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
    "initiatingReason": "Goods returned by customers",
    "metadata": "This is a metadata"
}'

请求成功时，响应中会包含 refund 对象和 payment 对象，分别展示退款交易及原支付的状态和相关信息。

refund 对象详细说明：

1. refund.status：本次退款的状态，必填，取值可为 Success、Failed 或 Received。如果 refund.status 为 Received，您需要再发起一次 HTTP GET 请求获取本次退款的最终状态（详情请参阅步骤 2），或等待 EVO Payment 的通知 Webhook。

2. refund.transAmount：退款的币种和金额，必填，从您的请求中原样返回。

3. refund.merchantTransInfo：退款交易的参考信息对象，由您的服务端生成，必填，从您的请求中原样返回。

4. refund.evoTransInfo：退款交易的参考信息对象，由 EVO Payment 生成，必填。包含 evoTransID、evoTransTime、traceNum（可选），以及部分 PSP（如 Visa 或 Mastercard）的 retrievalReferenceNum。

5. refund.pspTransInfo：退款交易的参考信息对象，由 PSP 生成，可选。包含 pspTransID、pspTransTime 和 authorizationCode。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。

6. refund.billingAmount 和 refund.billingFXRate：用户账单币种及完成金额，以及 refund.transAmount.currency 与 refund.billingAmount.currency 之间的汇率，可选。如果 PSP 返回了这些信息，EVO Payment 会将其转发给您的服务端。适用于 PSP 进行货币转换的部分电子钱包支付，或您开通 DCC 功能的部分银行卡支付。详情请联系 EVO Payment 客户经理。

7. refund.convertTransAmount 和 refund.convertTransFXRate：交易发送至 PSP 时，EVO Payment 根据 transAmount 及 transAmount.currency 到其他币种的汇率计算出的币种和金额，以及 refund.transAmount.currency 与 refund.convertTransAmount.currency 之间的汇率，可选。当您在 EVO Payment 开通货币转换功能且本次完成使用了货币转换时，会提供该汇率。详情请联系 EVO Payment 客户经理。

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

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "card": {
            "first6No": "476134",
            "last4No": "0019",
            "paymentBrand": "Visa",
            "fundingType": "credit"
        }
    },
    "payment": {
        "status": "Refunding",
        "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"
        }
    },
    "refund": {
        "status": "Received",
        "merchantTransInfo": {
            "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_REFUND",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "2cf248d44a0f4ed5991fa4f77879d71e",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "pspData": {
        "name": "Visa"
    },
    "metadata": "This is a metadata"
}

步骤 2：查询退款结果

如果 refund.status 为 Received，且您未使用通知 Webhook，可以向 EVO Payment 查询最终结果。

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

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

查询参数	是否必填	说明
merchantTransID	M	初始退款交易的 merchantTransInfo.merchantTransID。

以下示例展示如何查询退款结果：

curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/refund?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_REFUND} \
-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": "Refunded",
        "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"
        }
    },
    "refund": {
        "status": "Success",
        "merchantTransInfo": {
            "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_REFUND",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "2cf248d44a0f4ed5991fa4f77879d71e",
            "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"
}

改为发起撤销

如果您发起退款请求后收到 result.code 为 B0012，请检查响应报文中 payment.status 的原交易状态。如果为 authorised，说明该笔支付尚未完成，因此无法退款。此时您需要改为发起撤销。详情请参阅 Cancel（撤销） 章节。

异常处理

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

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