EVO Payment API Portal

简体中文

ENG

简体中文

ENG

Cancel ​

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

如果您已授权一笔支付但不希望完成该支付（例如商品缺货或系统超时错误），需要撤销该笔支付。

  • 适用支付方式：只有支持授权与完成分离的支付方式才能撤销，且必须在支付完成之前撤销。

  • 时效：建议在授权后 7 天内发送撤销请求，因为大多数发卡行会在此之后使授权失效。

  • 撤销金额：撤销金额始终与初始支付金额相同，因此撤销请求中无需指定金额参数。

发起撤销请求 ​

步骤 1：发起撤销请求 ​

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

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

撤销该笔支付，并指定以下参数：

参数是否必填说明
merchantTransIDM初始支付的 merchantTransInfo.merchantTransID。
参数是否必填说明
merchantTransInfoM撤销交易的参考信息，包括唯一的 merchantTransID，以及表示您发起请求时间的 merchantTransTime。
initiatingReasonO本次请求的原因，可选。
webhookO接收通知的 URL。传入该参数后，支付成功时将收到 EVO Payment 的通知。
metadataO自定义的参考信息，会在响应中原样返回。通知中的 metadata 与请求中的 metadata 一致。

以下是撤销请求示例：

js
curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/cancel?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_CANCEL",
        "merchantTransTime": "2021-12-31T08:35:59+08:00"
    },
     "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
    "initiatingReason": "Customer cancels order",
    "metadata": "This is a metadata"
}'

请求成功时，响应中会包含 cancel 对象和 payment 对象，分别提供撤销交易及原支付的状态和相关信息。

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

  2. cancel.merchantTransInfo：撤销交易的参考信息对象，由您的服务端生成，必填，从您的请求中原样返回。

  3. cancel.evoTransInfo：撤销交易的参考信息对象，由 EVO Payment 生成，必填。包含 evoTransID 和 evoTransTime。

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

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

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

步骤 2：查询撤销结果 ​

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

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

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

并指定以下参数：

参数是否必填说明
merchantTransIDM初始撤销交易的 merchantTransInfo.merchantTransID。

以下是查询撤销结果的示例：

js
curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/cancel?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_CANCEL} \
-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 响应类似：

js
{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "card": {
            "first6No": "476134",
            "last4No": "0019",
            "paymentBrand": "Visa",
            "fundingType": "credit"
        }
    },
    "payment": {
        "status": "Cancelled",
        "merchantTransInfo": {
            "merchantTransID": "37693fac0946498f8afe35b9ffdcfe89",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "ecf19b3be090407b97d74884077f08a4",
            "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"
        }
    },
    "cancel": {
        "status": "Success",
        "merchantTransInfo": {
            "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CANCEL",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "a36a6c5c6b224eaf923ca2c93ff3e63a",
            "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 的原交易状态。如果为 Captured，说明该笔支付已经完成，因此无法撤销。此时您需要改为发起退款。详情请参阅 Refund（退款） 章节。

异常处理 ​

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

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