Authentication
Secure your API requests using HMAC-SHA256 signatures.
We use HMAC-SHA256 signatures for all endpoints.
Please note that:
- Content-Type enforcement (for POST only method, must be
application/json) - Payload size limit (max 4KB for orders)
- API Key extraction → SHA-256 hash → 60s in-memory cache lookup
- Reseller status must be
active - IP Whitelist: your server IP must be whitelisted in the dashboard
- Timestamp anti-replay: reject if drift exceeds 5 minutes
- HMAC-SHA256 timing-safe verification
- Abuse detection: anomaly tracking for suspicious patterns
- Field-level validation (per-route envelope schema: allowed fields, types, and size limits; unknown fields are rejected)
- Request ID: unique UUID attached to every response via
X-Request-Id
You can whitelist Algan’s IP Address to make sure callback from us is not blocked: 208.77.246.15
What validation does (and does not) check
Our schema enforcement validates the request envelope only: which fields are allowed (ref_id, product_code, target, zone, price, and on POST /order the optional test), their types, and their length limits. It does not validate the content of target/zone against a game’s form patterns. The validation.pattern values returned by GET /categories are helpers for your own checkout UI. A wrongly-formatted target still passes our validation and is only rejected downstream by the supply partner; the order ends as failed and the balance is automatically refunded. Validate your customer’s input on your side before ordering.
IP Whitelist Mandatory
You must configure at least one IP address in your dashboard before making any API request. Requests from non-whitelisted IPs are rejected with 403 IP_NOT_WHITELISTED.
Required Headers
Every request to /api/v1/* must include three required headers:
Authentication Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Api-Key | String | Yes | Your public API Key (e.g., algan_live_...). |
X-Timestamp | String | Yes | Current Unix timestamp in milliseconds (e.g., 1715700000000). |
X-Signature | String | Yes | HMAC-SHA256 hex digest of dataToSign using your API Secret. |
Generating the Signature
For GET Requests (no body)
Since GET requests have no JSON body, the payload is an empty string "".
dataToSign = "" + timestamp
= timestamp
So you simply sign the timestamp:
HMAC-SHA256(timestamp, apiSecret) → hex string
For POST Requests (with body)
Stringify your JSON body and append the timestamp:
dataToSign = JSON.stringify(body) + timestamp
Then:
HMAC-SHA256(dataToSign, apiSecret) → hex string
We verify the raw bytes of the body you send, so sign exactly the string you send. Serialising the object a second time (another key order or spacing) gives a different signature.
What a signature covers
A signature covers the request body and the timestamp, nothing else. It does not cover the method, the path, the query string or any header. A GET signature is therefore a signature of the timestamp alone: for 5 minutes it is valid on any GET endpoint with any query. The other gates are what bind a request to you: it must carry your API key and come from an IP on your whitelist. Keep the API key and the API Secret on your servers, never in an app or a browser, and keep the whitelist to your own servers’ addresses.
Key Insight
The API Key is a public identifier (like an AWS Access Key ID). It tells us who you are. The API Secret is a private signing key (like an AWS Secret Key). It proves you authorized this specific request. Never send your API Secret over the wire.
Live Tester
Use this interactive tool to verify your signature generation logic. The signature generated here should match the output of your code.
Live Signature Tester
HMAC-SHA256 of the body followed by the timestamp, keyed with your API Secret.
Generated Signature (X-Signature)
Code Examples
Node.js (GET Request)
const crypto = require('crypto');
const API_KEY = 'algan_live_...';
const API_SECRET = 'sk_live_...';
const timestamp = Date.now().toString();
// For GET requests, payload is empty
const dataToSign = '' + timestamp;
const signature = crypto
.createHmac('sha256', API_SECRET)
.update(dataToSign)
.digest('hex');
const response = await fetch('https://algan.id/api/v1/balance', {
headers: {
'X-Api-Key': API_KEY,
'X-Timestamp': timestamp,
'X-Signature': signature,
},
});
Node.js (POST Request)
const crypto = require('crypto');
const API_KEY = 'algan_live_...';
const API_SECRET = 'sk_live_...';
const timestamp = Date.now().toString();
const body = {
ref_id: 'R-123',
product_code: 'ALGAN-MLBB-86',
target: '12345678',
zone: '1234',
price: 25000,
};
const payloadString = JSON.stringify(body);
const dataToSign = payloadString + timestamp;
const signature = crypto
.createHmac('sha256', API_SECRET)
.update(dataToSign)
.digest('hex');
const response = await fetch('https://algan.id/api/v1/order', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': API_KEY,
'X-Timestamp': timestamp,
'X-Signature': signature,
},
body: payloadString,
});
PHP
<?php
$apiKey = 'algan_live_...';
$apiSecret = 'sk_live_...';
$timestamp = round(microtime(true) * 1000);
// For GET requests:
$dataToSign = '' . $timestamp;
$signature = hash_hmac('sha256', $dataToSign, $apiSecret);
// For POST requests:
$payload = ['ref_id' => 'R-123', 'product_code' => 'ALGAN-MLBB-86', 'target' => '12345678', 'zone' => '1234', 'price' => 25000];
$payloadString = json_encode($payload, JSON_UNESCAPED_SLASHES);
$dataToSign = $payloadString . $timestamp;
$signature = hash_hmac('sha256', $dataToSign, $apiSecret);
$headers = [
'Content-Type: application/json',
'X-Api-Key: ' . $apiKey,
'X-Timestamp: ' . $timestamp,
'X-Signature: ' . $signature,
];
Python
import hmac
import hashlib
import time
import json
import requests
API_KEY = "algan_live_..."
API_SECRET = "sk_live_..."
timestamp = str(int(time.time() * 1000))
# For GET requests:
data_to_sign = "" + timestamp
signature = hmac.new(
API_SECRET.encode(), data_to_sign.encode(), hashlib.sha256
).hexdigest()
response = requests.get(
"https://algan.id/api/v1/balance",
headers={
"X-Api-Key": API_KEY,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
)
# For POST requests:
body = {"ref_id": "R-123", "product_code": "ALGAN-MLBB-86", "target": "12345678", "zone": "1234", "price": 25000}
payload_string = json.dumps(body, separators=(",", ":"))
data_to_sign = payload_string + timestamp
signature = hmac.new(
API_SECRET.encode(), data_to_sign.encode(), hashlib.sha256
).hexdigest()
cURL (GET, e.g. Balance)
API_KEY="algan_live_..."
API_SECRET="sk_live_..."
TIMESTAMP=$(python3 -c "import time; print(int(time.time() * 1000))")
SIGNATURE=$(echo -n "${TIMESTAMP}" | \
openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')
curl -s https://algan.id/api/v1/balance \
-H "X-Api-Key: ${API_KEY}" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Signature: ${SIGNATURE}"
cURL (POST, e.g. Order)
API_KEY="algan_live_..."
API_SECRET="sk_live_..."
TIMESTAMP=$(python3 -c "import time; print(int(time.time() * 1000))")
BODY='{"ref_id":"R-123","product_code":"ALGAN-MLBB-86","target":"12345678","zone":"1234","price":25000}'
SIGNATURE=$(echo -n "${BODY}${TIMESTAMP}" | \
openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')
curl -s -X POST https://algan.id/api/v1/order \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${API_KEY}" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Signature: ${SIGNATURE}" \
-d "${BODY}"