EVO Payment API Portal

简体中文

ENG

简体中文

ENG

Accept Notification ​

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

EVO Payment 通知是一种 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 Payment 会向指定的 Webhook 发送异步通知。只有成功的交易才会触发此类通知。
Settlement notification如已配置，发生清算操作时 EVO Payment 会向指定的 Webhook 发送异步通知。何时会收到清算通知，请参考下表。
清算操作说明
Merchant Dispute Debit因争议交易从商户扣款的交易记录。
Merchant Dispute Credit因争议交易向商户入账的交易记录。
Merchant Risk Hold被收单机构暂扣、待后续清算的交易记录。
Merchant Risk Release已暂扣交易释放给商户的交易记录。
Merchant Fee Debit收单机构向商户收取费用的记录。
Merchant Fee Credit收单机构向商户支付费用的记录。

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

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

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

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

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

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

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

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

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

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

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

步骤 3：接收通知 ​

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

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

您的服务端收到通知后：

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

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

  3. 返回 HTTP 200 OK 确认该通知。

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

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

通知排队 ​

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

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

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

  1. 15 秒

  2. 15 秒

  3. 30 秒

  4. 3 分钟

  5. 30 分钟

  6. 60 分钟

  7. 90 分钟

  8. 120 分钟

  9. 240 分钟

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

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

通知结构 ​

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

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

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

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

js
{
    "eventCode": "Payment",
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "Alipay"
        }
    },
    "payment": {
        "status": "Captured",
        "merchantTransInfo": {
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "pspTransInfo": {
            "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
            "pspTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "pspData": {
        "name": "Alipay"
    },
    "metadata": "This is a metadata"
}