Accept Notification

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

EVO Cloud 通知是一种 Webhook，用于告知您请求的状态更新。所有异步处理的请求都会发送通知，例如处于 Pending 状态的支付请求，以及完成、撤销、退款和数据报送请求。您可以利用通知实现业务流程自动化，例如订单管理。

以下对照表可帮助您了解何时会收到通知：

API 请求	API 用途	通知触发条件
POST PaymentMethod	为用户的支付方式生成令牌	令牌生成成功或失败时发送通知。使用 `paymentMethod.merchantTransInfo` 匹配数据库中的令牌化请求。
POST Payment	发起支付	支付完成或失败时发送通知。如果 `authenticationOnly` 为 true，认证完成或失败时会收到通知。使用 `payment.merchantTransInfo` 匹配数据库中的支付请求。不同的完成模式： - 即时支付：支付完成或失败时发送通知。 - 授权与完成分离：授权成功或失败时发送通知；如果授权成功，完成状态变化时会再发送一次通知（包含额外的 capture 对象）。
POST Capture	完成一笔支付	支付完成成功或失败时发送通知。使用 `payment.merchantTransInfo` 或 `capture.merchantTransInfo` 匹配数据库中的请求。
POST Cancel	撤销一笔支付	支付撤销成功或失败时发送通知。使用 `payment.merchantTransInfo` 或 `cancel.merchantTransInfo` 匹配数据库中的请求。
POST Refund	退款一笔支付	支付退款成功或失败时发送通知。使用 `payment.merchantTransInfo` 或 `refund.merchantTransInfo` 匹配数据库中的请求。
POST CancelOrRefund	关闭或退款一笔支付	支付退款或关闭成功或失败时发送通知。使用 `payment.merchantTransInfo`、`refund.merchantTransInfo` 或 `cancel.merchantTransInfo` 匹配数据库中的请求。
POST DataSubmission	报送清关数据	支付订单向海关报送成功或失败时发送通知。使用 `payment.merchantTransInfo` 或 `dataSubmission.merchantTransInfo` 匹配数据库中的请求。
PUT DataSubmission	重新报送或更正已向海关报送的信息	支付订单重新报送成功或失败时发送通知。使用 `payment.merchantTransInfo` 或 `dataSubmission.merchantTransInfo` 匹配数据库中的请求。

以下是与 API 调用无关的其他异步通知场景：

场景	说明
MPM (Static QR Code)交易	如已配置，支付成功后 EVO Cloud 会向指定的 Webhook 发送异步通知。只有成功的交易才会触发此类通知。
Settlement notification	如已配置，发生清算操作时 EVO Cloud 会向指定的 Webhook 发送异步通知。何时会收到清算通知，请参考下表。

清算操作	说明
Merchant Dispute Debit	因争议交易从商户扣款的交易记录。
Merchant Dispute Credit	因争议交易向商户入账的交易记录。
Merchant Risk Hold	被收单机构暂扣、待后续清算的交易记录。
Merchant Risk Release	已暂扣交易释放给商户的交易记录。
Merchant Fee Debit	收单机构向商户收取费用的记录。
Merchant Fee Credit	收单机构向商户支付费用的记录。

处理通知需要完成以下步骤。

步骤 1：在服务端开放接收地址

通知以 HTTP 回调（Webhook）的形式发送到您服务端的接收地址。EVO Cloud 要求使用 TLS v1.2 的 HTTPS 地址。

接收通知的服务端需要具备：

一个可以接收 HTTP POST 请求的地址。

生产环境：开放用于 HTTPS 流量的 TCP 端口（443、8443 或 8843），并使用 TLS v1.2。

测试环境：开放用于 HTTP 流量的 TCP 端口（80、8080 或 8888），或用于 HTTPS 流量的 TCP 端口（448、8443 或 8843），并使用 TLS v1.2。

根据您的网络和安全要求，您可能还需要将我们的网络加入防火墙白名单，方式可以是添加域名白名单，或通过 DNS 查询定期解析我们的 IP 地址。请注意，我们不提供用于白名单的 IP 地址列表，因为 IP 地址会因 ISP 配置变更等各种原因随时间变化。如果您选择对 EVO Cloud 域名进行 DNS 查询，建议每小时检查一次。但如果您选择将解析出的 IP 地址硬编码到白名单中，当 IP 地址在两次 DNS 查询间隔内发生变化时，仍存在服务中断的风险。

步骤 2：在请求中传入 Webhook URL

向 EVO Cloud 发送的任何请求报文都可以在请求参数中传入 webhook。发送请求时指定该参数后，交易状态更新时您将收到通知。

请注意，只有当交易状态变为 Success 时，您才会收到 EVO Cloud 的通知。

步骤 3：接收通知

为确保您的服务端正确接收通知，我们要求您对每一条通知（无论何种类型）都返回 HTTP 状态码 200 作为确认。

如果我们在 5 秒内未收到该响应，发往您接收地址的所有通知都将进入队列并重试。详情请参阅“通知排队”章节。

您的服务端收到通知后：

验证通知中的签名，以确认通知由 EVO Cloud 发送，且在传输过程中未被篡改。详情请参阅《EVO Cloud API 规范》中的 API 规则。如果签名无效，建议不要确认该通知。

将通知存储到数据库或队列中。

返回 HTTP 200 OK 确认该通知。

执行您的业务逻辑。请确保在执行任何业务逻辑之前先确认通知，因为业务逻辑出错可能导致重要的状态更新无法到达您的系统。

详情请参阅“通知结构”章节。

通知排队

为确保通知正确送达，您需要返回合适的响应报文进行确认。详情请参阅步骤 3。

如果我们在 15 秒内未收到响应报文，该通知将进入队列，我们会持续重试发送，直到通知被接收。

重试会定期进行，最多 9 次，间隔逐次递增：

15 秒

30 秒

3 分钟

30 分钟

60 分钟

90 分钟

120 分钟

240 分钟

如果完成以上全部重试后您的服务端仍未确认通知，我们的 CE 团队会联系您。

每条通知的队列相互独立，一条通知排队不会影响其他通知。

通知结构

每条通知都包含一个 eventCode，用于标识触发该通知的事件类型。

事件码	说明
PaymentMethod	支付方式通知
Payment	支付通知
Capture	完成通知
Cancel	撤销通知
Refund	退款通知
DataSubmission	数据报送通知
StaticQRCode	MPM（静态二维码）交易通知
NetworkTokenDeleted	网络令牌删除通知
NetworkTokenStatusUpdated	网络令牌状态更新通知
Settlement	清算操作通知

通知报文中的其他字段，请参阅《EVO Cloud API 规范》。

以下是支付成功的通知示例：

步骤 1：在服务端开放接收地址#

步骤 2：在请求中传入 Webhook URL#

步骤 3：接收通知#

通知排队#

通知结构#

步骤 1：在服务端开放接收地址

步骤 2：在请求中传入 Webhook URL

步骤 3：接收通知

通知排队

通知结构