Skip to main content

​
Authentication

All API requests to 123hub must be authenticated using two headers: your Application ID and a SHA512 hash computed from the request body and your secret key. This page explains how to obtain your credentials and sign requests.

​
Obtaining Credentials

API credentials and merchant accounts are created by the 123hub team during onboarding. Self-registration is not available.
To obtain your credentials:
  1. Contact your 123hub account manager
  2. Or email support@123hub.pro
Once your account is set up, you can view your credentials in the Merchant Dashboard under Settings > API Keys. You will receive:
CredentialTypeDescription
application_idIntegerYour unique application identifier (e.g., 1, 42)
secret_keyStringA random secret string used to sign requests
Keep your secret_key secure. Never expose it in client-side code, public repositories, or browser requests. If compromised, rotate it immediately from the dashboard.

​
Authentication Headers

Every request to the API must include two headers:
HeaderValueDescription
X-Data-Application-IdIntegerYour application ID
X-Data-HashHex stringSHA512 hash of requestBody + secretKey

​
How Signing Works

1

Prepare the request body

Serialize your request body as a JSON string. This is the exact string that will be sent as the HTTP body.
2

Compute the hash

Concatenate the JSON string with your secret_key (no separator), then compute the SHA512 hash of the result. Output as a lowercase hex string. hash = SHA512(jsonBody + secretKey)
3

Send the request

Include both headers with your POST request to the API endpoint.
The JSON string you hash must be byte-for-byte identical to the JSON string sent as the HTTP body. If you use compact serialization (e.g., json.dumps(body, separators=(',',':')) in Python), you must send that exact compact string as the request body. Differences in whitespace, key ordering, or formatting between the hashed string and the sent body will cause error 3000 (Authentication error).

​
Code Examples

# Step 1: Define your body
BODY='{"method":"gateway.ping","params":{}}'

# Step 2: Compute the SHA512 hash
# Concatenate body + secret key, then hash
HASH=$(echo -n "${BODY}your_secret_key" | sha512sum | awk '{print $1}')

# Step 3: Send the request
curl -X POST https://api.bafanglaicai88.com/public/api/multihub/v1 \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 1" \
  -H "X-Data-Hash: ${HASH}" \
  -d "${BODY}"

​
Verifying API Response Signatures

Successful MultiHub responses include X-Data-Hash. Verify it with the same merchant API secret: 
SHA512(rawResponseBody + apiSecret)
Use the raw response body bytes exactly as received. This check protects your integration from tampered responses and should be performed before trusting payment identifiers, balances, or status values.

​
Verifying Webhook Signatures

When 123hub sends webhook notifications to your server, the request includes an X-Data-Hash header. New deliveries also include replay-protection metadata in X-Webhook-Id, X-Webhook-Timestamp, X-Webhook-Nonce, and X-Webhook-Signature-V2. You should verify the body signature before processing the payload. The signature is computed the same way: SHA512(webhookBody + API secret). Webhook deliveries created or rotated after the API secret rollout use the merchant API secret. Existing legacy webhook configurations may continue to verify with the previously issued signing secret until the merchant rotates the API secret. 
import hashlib
import hmac

def verify_webhook(raw_body: bytes, signature: str, api_secret: str) -> bool:
    expected = hashlib.sha512(raw_body + api_secret.encode()).hexdigest()
    return hmac.compare_digest(expected, signature)  # constant-time comparison
Always verify webhook signatures before processing the payload. Use a constant-time comparison function (like hash_equals in PHP or crypto.timingSafeEqual in Node.js) to prevent timing attacks.

​
Test Mode vs Production

Test and production requests use the same API endpoint and the same authentication mechanism. The environment is determined by which credentials you use.
  • Test credentials create simulated transactions with no real money movement
  • Production credentials create real transactions with actual money movement
  • Webhooks are delivered in both environments for testing integrations
  • All API responses follow the same format in both environments

​
Rate Limits

API requests may be rate-limited to ensure fair usage. The public MultiHub controller is exempt from the gateway default throttler, so effective limits are configured per merchant, proxy, or deployment policy during onboarding.
ScopeLimit
MultiHub APIConfirmed during onboarding; no hard-coded per-method limit is exposed by the public contract
Webhook management APISubject to gateway/API-key policy
When a rate limit is applied, it is counted per authenticated merchant/application context across methods such as payment.in, payment.out, payment.status, payment.notification, balance.get, and gateway.ping.
If you exceed an applied limit, the response will contain success: false with an appropriate error code and message. Contact support if you need a higher production throughput profile.

​
Error Responses

Authentication errors are returned in the standard response envelope with HTTP 400:
Invalid Application ID
{
  "success": false,
  "error": {
    "code": 3003,
    "message": "The app does not exist",
    "details": null,
    "context": null
  },
  "request_id": "req_a1b2c3d4",
  "processing_time": 2
}
Invalid Hash Signature
{
  "success": false,
  "error": {
    "code": 3000,
    "message": "Authentication error",
    "details": null,
    "context": null
  },
  "request_id": "req_e5f6g7h8",
  "processing_time": 1
}

​
Best Practices

Use Environment Variables

Store your application_id and secret_key in environment variables, never in source code

Rotate Keys Regularly

Regenerate your secret key periodically from the dashboard for enhanced security

Verify Webhooks

Always verify the X-Data-Hash header on incoming webhooks before processing

Monitor Usage

Track API usage in the dashboard to detect anomalies and stay within rate limits