Recharge Success Message Push

Overview

The Linksfield Cube API Outbound (Webhook) system uses RESTful API to send Notification APIs.
The notification content consists of events from the Linksfield system.
Customers can receive event notifications in the following way:

With customer authorization, an FAE configures notification APIs for certain system events on behalf of the customer via BBC.

Header Structure

Parameter	Required	Type	Example Value	Description	Included in Signature Calculation
x-lf-notification-version	Required	String	1.0	Version identifier of the Notification API	Yes
x-lf-algo	Required	String	HMAC-SHA1	Algorithm identifier. Currently supports HMAC-SHA1. Can be extended in the future to md5, sha256, etc. Default is HMAC-SHA1.	Yes
x-lf-signature	Required	String	{keyId}/{signature}	Signature. Multiple business key pairs may exist. The keyId must be included.	Yes
x-lf-timestamp	Required	String	1683524066000	Send timestamp, in milliseconds	Yes

Algorithm

The API outbound carries a Linksfield-defined algorithm identifier, intended to strengthen security between communicating parties and prevent message tampering or unauthorized sending.
Receiving Notifications requires a separate key.

HMAC-SHA1

Steps to Compute the Signature

Load the notification key (in raw hex).

Construct the message:
2.1 JSON String encode the POST body, with top-level keys sorted in lexicographic order (arrays are not sorted) => sorted_message
2.2 Prepend the header information: {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
Example:

Apply HMAC-SHA1 (key = key_hex, data = message).

Base64-encode the digest.

x-lf-signature = {keyId}/{digest}
Example:

Steps to Verify the Signature

Based on the {keyId} in x-lf-signature, load the notification key.

Apply HMAC-SHA1 (key = key_hex, data = message).
Note: key_hex refers to the notification key value in the Developer module on the Cube page.

Base64-encode the digest.

Compare the computed digest with the digest received in x-lf-signature.

It is recommended that the client application discard any messages that fail signature verification.

Signature Code Examples

Notification Signature Code Examples
How to Obtain the Notification Key

Retry Mechanism

Automatic retry is triggered in the following situations. The system retries up to 3 times (4 attempts total), with escalating intervals of: 1, 5, and 10 minutes.

Internal Linksfield timeout (wait timeout, etc.) or send service exception

External response timeout (read timeout, connection timeout, etc.)

HTTP status code >= 500 (2xx, 3xx, 4xx do not trigger a retry)

Request

Header Params

Body Params application/json

Example

{
    "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",
            "payer_email": "linksfield@gmail.com"
        }
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Overview#

Header Structure#

Algorithm#

HMAC-SHA1#

Steps to Compute the Signature#

Steps to Verify the Signature#

Signature Code Examples#

Retry Mechanism#