EVO Payment API Portal

简体中文

ENG

简体中文

ENG

Accept Notification ​

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

EVO Cloud 通知是一个 webhook，用于通知您请求的状态更新。对于任何异步处理的请求，您都可以收到通知。例如，处于 pending 状态的 payment 请求，或 capture、cancel、refund 和 data submission 请求。您可以使用该通知来自动化您的业务流程，例如订单管理。

下面这张矩阵供您参考，查看您可以在何时收到通知：

API 请求API 用途通知触发时机
POST PaymentMethod为用户 tokenize 一种支付方式token 生成成功或失败时发送通知。使用 paymentMethod.merchantTransInfo 在数据库中匹配您的 tokenization 请求。
POST Payment发起一笔支付支付完成或失败时发送通知。如果 authenticationOnly 为 true，您将在认证完成或失败时收到通知。使用 payment.merchantTransInfo 在数据库中匹配您的支付请求。
不同的 Capture 模式：
- Instant Payment（实时支付）： 支付被 capture 或失败时发送通知。
- Separate Authorization and Capture（分开授权和 capture）： 授权成功或失败时发送通知，如果授权成功则会再发送一条 capture 状态的通知（包含额外的 capture 对象）。
POST Capturecapture 一笔支付支付被 capture 成功或失败时发送通知。使用 payment.merchantTransInfo 或 capture.merchantTransInfo 在数据库中匹配请求。
POST Cancelcancel 一笔支付支付被 cancel 成功或失败时发送通知。使用 payment.merchantTransInfo 或 cancel.merchantTransInfo 在数据库中匹配请求。
POST Refundrefund 一笔支付支付被 refund 成功或失败时发送通知。使用 payment.merchantTransInfo 或 refund.merchantTransInfo 在数据库中匹配请求。
POST CancelOrRefund关闭或 refund 一笔支付支付被 refund/close 成功或失败时发送通知。使用 payment.merchantTransInfo 或 refund.merchantTransInfo/cancel.merchantTransInfo 在数据库中匹配请求。
POST DataSubmission提交数据进行清关支付订单被成功提交给海关或失败时发送通知。使用 payment.merchantTransInfo 或 dataSubmission.merchantTransInfo 在数据库中匹配请求。
PUT DataSubmission重新提交或更正已提交给海关的信息支付订单被成功重新提交或失败时发送通知。使用 payment.merchantTransInfo 或 dataSubmission.merchantTransInfo 在数据库中匹配请求。

其他与 API 调用无关的异步通知场景。

场景说明
MPM（静态二维码）交易如果已配置，EVO Cloud 将在支付成功后向指定的 Webhook 发送异步通知。仅成功的交易会触发这些通知。
结算通知如果已配置，EVO Cloud 将在发生结算操作时向指定的 Webhook 发送异步通知。下面这张矩阵供您参考，查看您可以在何时收到结算通知。
结算操作说明
Merchant Dispute Debit这是一条因争议交易而从商户扣款的交易记录。
Merchant Dispute Credit这是一条因争议交易而向商户入账的交易记录。
Merchant Risk Hold这是一条被收单机构暂扣以作进一步结算的交易记录。
Merchant Risk Release这是一条从被暂扣的交易中释放给商户的交易记录。
Merchant Fee Debit这是一条收单机构向商户收取商户手续费的交易记录。
Merchant Fee Credit这是一条收单机构向商户支付商户手续费的交易记录。

要处理通知，需要执行以下步骤。

Step 1: Expose an endpoint on your server ​

通知以 HTTP 回调（webhooks）的方式发送到您服务器的一个端点。EVO Cloud 要求您使用支持 TLS v1.2 的 HTTPS 端点。

要接收通知，您需要一台满足以下条件的服务器：

  1. 一个可以接收 HTTP POST 的端点。
  2. 对于生产环境：一个用于 HTTPS 流量的开放 TCP 端口（443、8443 或 8843），支持 TLS v1.2。
  3. 对于测试环境：一个用于 HTTP 流量（80、8080 或 8888）或 HTTPS 流量（448、8443 或 8843）的开放 TCP 端口，支持 TLS v1.2。

根据您的网络和安全要求，您可能还需要通过添加域名白名单或通过 DNS 查找系统地解析我们的 IP 地址来将我们的网络添加到您的防火墙白名单中。请注意，我们不提供用于白名单的 IP 地址列表，因为 IP 地址会因各种原因（例如 ISP 配置变更）而随时变化。如果您倾向于对 EVO Cloud 域名执行 DNS 查找，我们建议您每小时检查一次。但是，如果您选择将解析到的 IP 地址硬编码到白名单中，在 DNS 查找间隔内 IP 地址发生变化时，您仍然会面临中断的风险。

Step 2: Send a request with webhook URL ​

对于发送给 EVO Cloud 的任何请求消息，webhook 在请求参数中是可接受的。在您发送请求时指定它，然后您就可以收到该交易状态更新的通知。

请注意，仅当交易状态变为 Success 时，您才能从 EVO Cloud 收到通知。

Step 3: Accept the notification ​

为确保您的服务器正确接收通知，我们要求您使用 HTTP 状态码 200 的响应来确认每一条任何类型的通知。

如果我们未在 5 秒内收到此响应，所有发往您端点的通知将被排队并重试。更多详情请参阅 Queued notifications 章节。

当您的服务器收到通知时：

  1. 验证通知中包含的签名。这是为了确认通知是由 EVO Cloud 发送的，并且在传输过程中未被修改。更多详情请参阅 EVO Cloud API Specification 中的 API Rules。如果签名无效，我们建议您不要确认该通知。
  2. 将通知存储到您的数据库/队列中。
  3. 使用 HTTP 200 OK 确认该通知。
  4. 应用您的业务逻辑。请确保在应用任何业务逻辑之前先确认通知，因为您业务逻辑中的故障可能会阻止重要的更新到达您的系统。

更多详情请参阅 Notification structure 章节。

Queued notifications ​

为确保通知被正确送达，您需要使用适当的响应消息对其进行确认。更多详情请参阅 Step 3。

如果我们未在 15 秒内收到响应消息，该通知将被排队，然后我们将重试发送该通知，直到被接受为止。

重试会按以下递增的时间间隔定期进行，最多 9 次：

  1. 15 秒
  2. 15 秒
  3. 30 秒
  4. 3 分钟
  5. 30 分钟
  6. 60 分钟
  7. 90 分钟
  8. 120 分钟
  9. 240 分钟

如果您的服务器在以上所有重试后仍未确认通知，我们的 CE 团队将就此通知您。

通知队列为每条通知单独维护，意味着一个被排队的通知不会影响其他通知。

Notification structure ​

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

事件码说明
PaymentMethod支付方式通知
Payment支付通知
Capturecapture 通知
Cancelcancel 通知
Refundrefund 通知
DataSubmissiondata submission 通知
StaticQRCodeMPM（静态二维码）交易通知
NetworkTokenDeletednetwork token 删除通知
NetworkTokenStatusUpdatednetwork token 更新通知
Settlement结算操作通知

有关通知消息中的其他字段，请参阅 EVO Cloud API Specification 以了解更多详情。

下面是一个成功支付通知的示例：

js
1.{  
2.    "eventCode": "Payment",  
3.    "paymentMethod": {  
4.        "e-wallet": {  
5.            "paymentBrand": "Alipay"  
6.        }  
7.    },  
8.    "payment": {  
9.        "status": "Captured",  
10.        "merchantTransInfo": {  
11.            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
12.            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
13.        },  
14.        "evoTransInfo": {  
15.            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
16.            "evoTransTime": "2021-12-31T00:30:59Z"  
17.        },  
18.        "pspTransInfo": {  
19.            "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",  
20.            "pspTransTime": "2021-12-31T08:30:59+08:00"  
21.        },  
22.        "transAmount": {  
23.            "currency": "USD",  
24.            "value": "10.00"  
25.        }  
26.    },  
27.    "pspData": {  
28.        "name": "Alipay"  
29.    },  
30.    "metadata": "This is a metadata"  
31.}