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 [email protected]
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.

​
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.123hub.pro/public/api/multihub/v1 \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 1" \
  -H "X-Data-Hash: ${HASH}" \
  -d "${BODY}"

​
Verifying Webhook Signatures

When 123hub sends webhook notifications to your server, the request includes an X-Data-Hash header. You should verify this signature to ensure the webhook is authentic. The signature is computed the same way: SHA512(webhookBody + secretKey). 
import hashlib

def verify_webhook(raw_body: bytes, signature: str, secret_key: str) -> bool:
    expected = hashlib.sha512(raw_body + secret_key.encode()).hexdigest()
    return expected == signature
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 are rate-limited to ensure fair usage:
Method TypeLimit
payment.in / payment.out5000 requests/minute (burst: 500/10sec)
payment.status / balance.get100 requests/minute
gateway.ping100 requests/minute
Rate limits are applied per application_id. If you exceed the limit, the response will contain success: false with an appropriate error code and message.

​
Error Responses

Authentication errors are returned in the standard response envelope with HTTP 200:
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