充值成功消息推送

概述

领科Cube API 出口（Webhook）系统采取RESTful API发送Notification API。
通知的内容为领科系统的events。
客户通过以下方式可以收到event通知

经过客户的授权，FAE在BBC为客户代为配置某些系统事件的notification API

Header结构

参数	必须	类型	示例值	说明	是否加入签名计算
x-lf-notification-version	必须	String	1.0	Notification api的版本标识	是
x-lf-algo	必须	String	HMAC-SHA1	算法标识，目前支持HMAC-SHA1。以后可以扩展, md5, sha256,等，默认为hmac-sha1	是
x-lf-signature	必须	String	{keyId}/{signature}	签名。有可能存在多对业务密钥。需要传keyid	是
x-lf-timestamp	必须	String	1683524066000	发送的时间戳，毫秒	是

算法

API出口携带领科定义的算法标识，其目的是加强通信双方的安全，防止报文篡改或非法发送。
接收Notification需要独立的Key。

HMAC-SHA1

计算signature步骤

Load notification key ( in raw hex)

组织报文：
2.1 POST 的body做JSON String encode, top-level key按字典排序（即数组不排序）=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例：

算法HMAC-SHA1（key=key_hex, data =message)

摘要做base64转换

x-lf-signature = {keyId}/{digest}
例：

验证signature步骤

根据x-lf-signature中的{keyId}, Load notification key

组织报文
2.1 POST 的body做JSON String encode, top-level key按字典排序（即数组不排序）=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例：

做HAMC-SHA1（key=key_hex, data =message)
注：key_hex指Cube页面中开发者模块的notification key value位置如下图所示

base64转换摘要

计算的摘要和接收到的x-lf-signature中的digest比较

推荐客户端应用在接收到校验失败的报文时，进行抛弃。

签名代码示例

Notification签名代码示例
如何获取Notification Key

重发机制

遇到下列情况，启动自动重发。自动重发3次（共4次），阶梯间隔：1，5， 10 （分钟）

领科内部超时(wait timeout, 等）或发送服务异常时

外部响应超时(read timeout, connection timeout等）

Status code >=500 时（2xx,3xx,4xx不需要重发）

请求参数

Header 参数

Body 参数application/json

示例

{
    "notification_id": "NT-09887665434565",
    "org_id": "P001234",
    "event_type": "payment",
    "event_subtype": "payment_succeeded",
    "level": "normal",
    "trigger_mode": 0,
    "source": {
        "type": "bbc-event",
        "reference_id": "bbc001",
        "reference_name": "payment_succeeded"
    },
    "event": {
        "occurred_at": 1683178613876,
        "sim_id": "89852123456789012345",
        "id": "EV-9988776666666",
        "detail": {
            "order_id": "CU-7ZOIHX0RB16U20250828111429591",
            "purchase_order_id": "4567",
            "bundle_name": "CLJF_ZRR_20250317_001",
            "cycles": "1",
            "total_amount": 1000,
            "payment_method": "stripe",
            "payee": "linksfield",
            "currency": "USD",
            "partner_name": "Excepteur deserunt eu labore",
            "paid_at": 1683178613876,
            "order_status": "active",
            "payment_status": "paid",
            "dispute_status": "none",
            "risk_status": "normal",
            "transaction_type": "one-time"
        }
    }
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

概述#

Header结构#

算法#

HMAC-SHA1#

计算signature步骤#

验证signature步骤#

签名代码示例#

重发机制#