مستندات API

احراز هویت (HMAC)

هر درخواست API باید این headerها را داشته باشد:

• X-Api-Key — کلید API از پنل merchant
• X-Timestamp — زمان Unix (حداکثر ±۵ دقیقه اختلاف)
• X-Signature — امضای HMAC-SHA256

فرمت امضا:

payload = timestamp + "\n" + METHOD + "\n" + path + "\n" + body
signature = HMAC-SHA256(api_secret, payload)

برای GET، body رشته خالی است. path شامل query string می‌شود.

ایجاد تراکنش

POST https://bank.hostkhaneh.com/api/v1/transactions/createContent-Type: application/json

{
  "order_id": "ORDER-1001",
  "amount": 1000000,
  "description": "خرید محصول",
  "callback_url": "https://yoursite.com/callback",
  "customer_mobile": "09123456789"
}

amount به ریال. حداقل ۱۰,۰۰۰ ریال.

پاسخ شامل gateway_url، unique_amount و expires_at است.

وضعیت تراکنش

GET https://bank.hostkhaneh.com/api/v1/transactions/status?order_id=ORDER-1001
GET https://bank.hostkhaneh.com/api/v1/transactions/status?transaction_id=123

وضعیت‌ها: pending | paid | expired | failed

Callback پرداخت موفق

بعد از تأیید SMS، POST JSON به callback_url ارسال می‌شود.

{
  "transaction_id": 123,
  "order_id": "ORDER-1001",
  "amount": 1000000,
  "unique_amount": 1000127,
  "status": "paid",
  "signature": "..."
}

امضا: فیلد signature را حذف کنید، ksort + json_encode + HMAC-SHA256 با api_secret.

دریافت SMS

POST https://bank.hostkhaneh.com/api/v1/sms/incomingX-Device-Token: YOUR_DEVICE_TOKEN

{"message": "متن SMS بانک..."}

$apiKey = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';
$body = json_encode(['order_id' => 'T1', 'amount' => 500000]);
$path = '/api/v1/transactions/create';
$ts = time();
$payload = $ts . "\nPOST\n" . $path . "\n" . $body;
$sig = hash_hmac('sha256', $payload, $secret);

// Headers: X-Api-Key, X-Timestamp, X-Signature