وثائق المطورين - دليل تكامل API من BlockSettler

Quick Start

البدء السريع

5 خطوات لإتمام تكامل الدفع

التسجيل والحصول على API Key

سجّل حساب تاجر، أنشئ مشروعًا في لوحة التحكم، واحصل على Access Key وSecret Key.

تكوين عنوان الإشعارات غير المتزامنة

كوّن عنوان URL لاستقبال الإشعارات في إعدادات المشروع، سيرسل النظام إشعارات عند تغيّر حالة الطلب.

استدعاء API إنشاء الطلب

استدعِ POST /payments باستخدام توقيع HMAC-SHA256 للحصول على عنوان الاستقبال ورابط صفحة الدفع.

معالجة الإشعارات غير المتزامنة

استقبل الإشعارات غير المتزامنة، تحقق من توقيع X-BS-Signature ثم حدّث حالة الطلب المحلي.

الاختبار والإطلاق

أكمل اختبار التدفق الكامل في بيئة الاختبار، ثم انتقل إلى بيئة الإنتاج بعد التأكد.

🔑

مصادقة توقيع HMAC-SHA256

يجب أن يحمل كل طلب Access Key والطابع الزمني وNonce عشوائي وتوقيع HMAC، لضمان عدم إمكانية تزوير الطلبات.

🔔

إشعارات غير متزامنة (Webhook)

يدعم 8 أنواع أحداث تشمل payment.completed وorder.expired وpayment.underpaid والمزيد، لتغطية دورة حياة الدفع الكاملة.

🔄

آلة حالة الطلب من 12 حالة

PENDING → PAID_UNCONFIRMED → CONFIRMED → COMPLETED، مع فروع استثنائية (دفع ناقص/زائد/منتهي/تحكم مخاطر)، تدفق حالات واضح وقابل للتحكم.

🔒

عدم التكرار ومنع إعادة التشغيل

Nonce لمنع إعادة التشغيل، merchant_order_no لمنع الإنشاء المزدوج، event_id لمنع المعالجة المزدوجة، ضمان ثلاثي لعدم التكرار.

Authentication

طريقة مصادقة API

جميع طلبات API للتجار تتطلب مصادقة توقيع HMAC-SHA256

رؤوس الطلب (Required Headers)

Header	说明	示例
`X-BS-Access-Key`	商户 Access Key（公钥），标识商户身份	`ak_live_xxxxxxxxxxxx`
`X-BS-Timestamp`	请求时间戳（秒级 Unix 时间），与服务器时间偏差不超过 5 分钟	`1704067200`
`X-BS-Nonce`	随机字符串（UUID），防止重放攻击，每次请求唯一	`550e8400-e29b-41d4-a716-446655440000`
`X-BS-Signature`	HMAC-SHA256 签名（Hex 编码）	`a1b2c3d4e5f6...`
`Content-Type`	固定为 JSON 格式	`application/json`

خوارزمية التوقيع

signature.txt

// 1. Construct signature body
signature_body = "{timestamp}" + "." + "{nonce}" + "." + "{request_body}"

// 2. Compute HMAC-SHA256 with Secret Key
signature = HMAC-SHA256(signature_body, secret_key)

// 3. Convert signature to Hex string, set as X-BS-Signature header
X-BS-Signature = hex(signature)

// Example:
// timestamp  = "1704067200"
// nonce      = "550e8400-e29b-41d4-a716-446655440000"
// body       = '{"merchant_order_no":"ORD-001","fiat_amount":"100.00",...}'
// secret_key = "sk_live_your_secret_key"
// signature_body = "1704067200.550e8400-e29b-41d4-a716-446655440000.{...json...}"

安全提示：Secret Key 仅在创建时展示一次，请妥善保存。请勿在前端代码中暴露 Secret Key，所有签名计算应在服务端完成。

API Reference

وثائق واجهات API

Base URL: https://api.blocksettler.com/api/v1/merchant

POST/payments创建支付订单

请求参数 (Request Body)

字段	类型	必填	说明
`merchant_order_no`	string	是	商户订单号，同一应用下唯一（最长 64 字符）
`title`	string	是	订单标题，展示给付款方（最长 128 字符）
`description`	string	否	订单描述（最长 512 字符）
`fiat_amount`	string	是	法币金额，如 `"100.00"`
`fiat_currency`	string	是	法币币种，如 `"USD"`, `"CNY"`
`pay_chain`	string	否	支付链：POLYGON / TRON / ETH / BSC / SOLANA，不传则使用项目默认值
`pay_token`	string	否	支付代币：USDT / USDC，不传则使用项目默认值
`notify_url`	string	否	异步通知地址，不传则使用项目配置的默认地址
`return_url`	string	否	支付完成后前端跳转地址
`expires_in`	int	否	订单有效期（秒），范围 300~86400，默认 1800（30分钟）
`metadata`	object	否	商户自定义数据，原样返回在异步通知中

响应参数 (Response Body)

字段	类型	说明
`platform_order_no`	string	平台订单号（BlockSettler 生成的唯一标识）
`merchant_order_no`	string	商户订单号（请求时传入）
`status`	string	订单状态，创建时为 `"PENDING"`
`fiat_amount`	string	法币金额
`fiat_currency`	string	法币币种
`pay_amount`	string	应付加密货币金额（系统按实时汇率计算）
`paid_amount`	string	已付加密货币金额（创建时为 0）
`pay_chain`	string	支付链名称
`pay_token`	string	支付代币
`pay_address`	string	收款地址（付款方需向此地址转账）
`expired_at`	string	订单过期时间（ISO 8601 格式）
`created_at`	string	创建时间

请求示例

POST /api/v1/merchant/payments

// Request Body
{
  "merchant_order_no": "ORD-20250415-0001",
  "title": "Premium Plan - 1 Month",
  "description": "Premium membership subscription",
  "fiat_amount": "99.00",
  "fiat_currency": "USD",
  "pay_chain": "TRON",
  "pay_token": "USDT",
  "notify_url": "https://your-site.com/api/payment/notify",
  "return_url": "https://your-site.com/payment/success",
  "expires_in": 1800,
  "metadata": {
    "user_id": "U-10086",
    "plan": "premium"
  }
}

响应示例

Response 200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "platform_order_no": "BS2025041500000001",
    "merchant_order_no": "ORD-20250415-0001",
    "status": "PENDING",
    "fiat_amount": "99.00",
    "fiat_currency": "USD",
    "pay_amount": "99.000000000000000000",
    "paid_amount": "0.000000000000000000",
    "pay_chain": "TRON",
    "pay_token": "USDT",
    "pay_address": "TN7gK3Wfxy4RDXG5DPGnXmkJJPqozvMBkR",
    "return_url": "https://your-site.com/payment/success",
    "expired_at": "2025-04-15T11:30:00Z",
    "created_at": "2025-04-15T11:00:00Z"
  }
}

GET/payments/:order_no查询订单详情

通过平台订单号查询订单最新状态。 :order_no = platform_order_no

响应示例（支付完成后）

Response 200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "platform_order_no": "BS2025041500000001",
    "merchant_order_no": "ORD-20250415-0001",
    "status": "COMPLETED",
    "fiat_amount": "99.00",
    "fiat_currency": "USD",
    "pay_amount": "99.000000000000000000",
    "paid_amount": "99.000000000000000000",
    "pay_chain": "TRON",
    "pay_token": "USDT",
    "pay_address": "TN7gK3Wfxy4RDXG5DPGnXmkJJPqozvMBkR",
    "expired_at": "2025-04-15T11:30:00Z",
    "paid_at": "2025-04-15T11:05:32Z",
    "confirmed_at": "2025-04-15T11:06:45Z",
    "completed_at": "2025-04-15T11:06:45Z",
    "created_at": "2025-04-15T11:00:00Z"
  }
}

POST/payments/:order_no/close关闭订单

关闭一个待支付的订单。仅 PENDING、UNDERPAID、OVERPAID、LATE_PAID 状态的订单可关闭。

请求参数

字段	类型	必填	说明
`reason`	string	否	关闭原因（最长 128 字符）

INFO统一响应格式与错误码

所有接口返回统一 JSON 结构：

response_format.json

// Success response
{ "code": 200, "message": "success", "data": { ... } }

// Invalid parameters
{ "code": 400, "message": "invalid fiat_amount", "data": null }

// Authentication failed (invalid signature / Access Key / expired timestamp)
{ "code": 401, "message": "invalid signature", "data": null }

// Resource not found
{ "code": 404, "message": "order not found", "data": null }

// Internal server error
{ "code": 500, "message": "internal error", "data": null }

Async Notification

إشعارات غير متزامنة (Webhook)

عندما تتغير حالة الطلب، يرسل BlockSettler طلب HTTP POST إلى عنوان رد الاتصال المكوّن من قبل التاجر

أنواع الأحداث المدعومة

event_type	触发时机	说明
`payment.confirmed`	链上确认数达标	交易已确认，可发货或交付服务
`payment.completed`	订单完成结算	订单流程正常完结
`order.expired`	订单超时未支付	超过有效期仍未收到足额支付
`order.closed`	订单被关闭	商户主动关闭或系统关闭
`payment.underpaid`	实付金额不足	收到的金额少于应付金额
`payment.overpaid`	实付金额超额	收到的金额超过应付金额
`payment.late_paid`	过期后到账	订单已过期，但仍收到了链上支付
`payment.failed`	支付失败	风控审核拒绝等异常

تنسيق رسالة الإشعار

系统向商户 notify_url 发送 POST 请求，Content-Type 为 application/json。

通知请求头

Header	说明
`Content-Type`	`application/json`
`X-BS-Event-ID`	事件唯一 ID，用于幂等去重
`X-BS-Event-Type`	事件类型，如 `payment.completed`
`X-BS-Timestamp`	通知发送的时间戳（秒级 Unix 时间）
`X-BS-Signature`	HMAC-SHA256 签名（用于验证通知来源）

通知 Body 示例（payment.completed）

webhook_payload.json

{
  "event_id": "evt_8f14e45f-ceea-4a4d-a8e0-3c2b5d4e9f01",
  "event_type": "payment.completed",
  "timestamp": "2025-04-15T11:06:45Z",
  "platform_order_no": "BS2025041500000001",
  "status": "COMPLETED",
  "payment": {
    "fiat_amount": "99.00",
    "fiat_currency": "USD",
    "pay_amount": "99.000000",
    "paid_amount": "99.000000",
    "pay_chain": "TRON",
    "pay_token": "USDT",
    "pay_address": "TN7gK3Wfxy4RDXG5DPGnXmkJJPqozvMBkR",
    "tx_hash": "6a1b2c3d4e5f...abc123def456"
  }
}

التحقق من التوقيع

商户收到通知后，必须验证 X-BS-Signature 以确认通知来源可信。验证方式：

verify_signature.txt

// 1. Get timestamp and signature from request headers
timestamp  = request.headers["X-BS-Timestamp"]
signature  = request.headers["X-BS-Signature"]

// 2. Read the raw request body (JSON string)
raw_body   = request.body

// 3. Construct signature body and compute HMAC-SHA256
expected   = HMAC-SHA256(timestamp + "." + raw_body, your_webhook_secret)

// 4. Use constant-time comparison to verify signature (prevent timing attacks)
is_valid   = constant_time_equal(hex(expected), signature)

آلية إعادة المحاولة

成功标准

商户接口返回 HTTP 2xx 状态码视为成功

重试策略

指数退避：1s → 5s → 30s → 5m → 30m → 2h，最多 6 次

幂等处理

请根据 event_id 做幂等判断，同一事件可能被投递多次

最佳实践：收到通知后应先返回 200 OK，再异步处理业务逻辑。若处理耗时过长（>5s），可能导致超时触发重试。

Code Samples

أمثلة الأكواد

أمثلة كاملة تشمل إنشاء الطلب (مع التوقيع) واستقبال الإشعارات غير المتزامنة

create_order.sh
# ====== Create Payment Order ======

TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"merchant_order_no":"ORD-20250415-0001","title":"Premium Plan","fiat_amount":"99.00","fiat_currency":"USD","pay_chain":"TRON","pay_token":"USDT","notify_url":"https://your-site.com/api/notify"}'

# Compute signature: HMAC-SHA256(timestamp.nonce.body, secret_key)
SIGN_BODY="${TIMESTAMP}.${NONCE}.${BODY}"
SIGNATURE=$(echo -n "${SIGN_BODY}" | openssl dgst -sha256 -hmac "sk_live_xxxx" | awk '{print $2}')

curl -X POST https://api.blocksettler.com/api/v1/merchant/payments \
  -H "Content-Type: application/json" \
  -H "X-BS-Access-Key: ak_live_xxxxxxxxxxxx" \
  -H "X-BS-Timestamp: ${TIMESTAMP}" \
  -H "X-BS-Nonce: ${NONCE}" \
  -H "X-BS-Signature: ${SIGNATURE}" \
  -d "${BODY}"

# ====== Query Order ======
curl -X GET https://api.blocksettler.com/api/v1/merchant/payments/BS2025041500000001 \
  -H "X-BS-Access-Key: ak_live_xxxxxxxxxxxx" \
  -H "X-BS-Timestamp: ${TIMESTAMP}" \
  -H "X-BS-Nonce: $(uuidgen)" \
  -H "X-BS-Signature: {computed_signature}"

Order Status

تدفق حالات الطلب

يستخدم BlockSettler آلة حالة من 12 حالة لإدارة دورة حياة الطلب

CREATED已创建

PENDING待支付

PAID_UNCONFIRMED已支付待确认

CONFIRMED已确认

COMPLETED已完成

EXPIRED已过期

CLOSED已关闭

UNDERPAID少付

OVERPAID多付

LATE_PAID过期到账

RISK_REVIEW风控审核

FAILED失败

order_status_flow.txt

                         Normal Payment Flow
CREATED ──> PENDING ──> PAID_UNCONFIRMED ──> CONFIRMED ──> COMPLETED
                │
                │          Exception Branches
                ├──> EXPIRED          Timed out without payment
                ├──> CLOSED           Closed by merchant
                ├──> UNDERPAID        Paid < Required
                ├──> OVERPAID         Paid > Required
                └──> LATE_PAID        Payment after expiry

EXPIRED ──> LATE_PAID                Payment received after expiry
PAID_UNCONFIRMED ──> RISK_REVIEW   Risk control triggered
RISK_REVIEW ──> CONFIRMED / FAILED  Approved / Rejected

هل أنت مستعد لبدء التكامل؟

سجّل حسابًا واحصل على API Key، اختبر في بيئة الاختبار، متوسط يوم واحد للإطلاق

تسجيل مجاني تواصل مع الدعم التقني

دليل تكامل المطورين

البدء السريع

التسجيل والحصول على API Key

تكوين عنوان الإشعارات غير المتزامنة

استدعاء API إنشاء الطلب

معالجة الإشعارات غير المتزامنة

الاختبار والإطلاق

مصادقة توقيع HMAC-SHA256

إشعارات غير متزامنة (Webhook)

آلة حالة الطلب من 12 حالة

عدم التكرار ومنع إعادة التشغيل

طريقة مصادقة API

رؤوس الطلب (Required Headers)

خوارزمية التوقيع

وثائق واجهات API

请求参数 (Request Body)

响应参数 (Response Body)

请求示例

响应示例

响应示例（支付完成后）

请求参数

إشعارات غير متزامنة (Webhook)

أنواع الأحداث المدعومة

تنسيق رسالة الإشعار

通知请求头

通知 Body 示例（payment.completed）

التحقق من التوقيع

آلية إعادة المحاولة

成功标准

重试策略

幂等处理

أمثلة الأكواد

تدفق حالات الطلب

هل أنت مستعد لبدء التكامل؟