Fejlesztői dokumentáció - BlockSettler API integrációs útmutató

Quick Start

Gyors kezdés

5 lépés a fizetési integráció befejezéséhez

Regisztráció és API Key beszerzése

Regisztráljon kereskedői fiókot, hozzon létre projektet a vezérlőpulton, szerezze be az Access Key-t és a Secret Key-t.

Aszinkron értesítési cím beállítása

A projekt beállításaiban konfigurálja az aszinkron értesítések fogadási URL-jét, a rendszer értesítést küld a rendelés állapotváltozásakor.

Rendelés létrehozási API hívása

Használjon HMAC-SHA256 aláírást a POST /payments hívásához, szerezze be a fogadási címet és a pénztár hivatkozást.

Aszinkron értesítések kezelése

Fogadja az aszinkron értesítéseket, ellenőrizze az X-BS-Signature aláírást és frissítse a helyi rendelés állapotát.

Tesztelés és éles indítás

Végezze el a teljes tesztelést sandbox környezetben, majd az ellenőrzés után váltson az éles környezetre.

🔑

HMAC-SHA256 aláírás-hitelesítés

Minden kéréshez Access Key, időbélyeg, véletlenszerű Nonce és HMAC aláírás szükséges, biztosítva, hogy a kérések nem hamisíthatók.

🔔

Aszinkron értesítés (Webhook)

8 eseménytípus támogatása, beleértve a payment.completed, order.expired és payment.underpaid típusokat, lefedve a teljes fizetési életciklust.

🔄

12 állapotú rendelésállapot-gép

PENDING → PAID_UNCONFIRMED → CONFIRMED → COMPLETED, kivételes ágakkal (alulfizetés/túlfizetés/lejárat/kockázatkezelés), átlátható és ellenőrizhető állapotátmenetek.

🔒

Idempotencia és újrajátszás elleni védelem

A Nonce megakadályozza az újrajátszást, a merchant_order_no a duplikált létrehozást, az event_id a duplikált feldolgozást, háromszoros idempotencia-biztosítás.

Authentication

API hitelesítési módszer

Minden kereskedői API kéréshez HMAC-SHA256 aláírás-hitelesítés szükséges

Kérés fejlécek (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`

Aláírási algoritmus

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 felület dokumentáció

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

Aszinkron értesítés (Webhook)

Amikor a rendelés állapota megváltozik, a BlockSettler HTTP POST kérést küld a kereskedő konfigurált visszahívási címére

Támogatott eseménytípusok

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

Értesítési üzenet formátum

系统向商户 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"
  }
}

Aláírás-ellenőrzés

商户收到通知后，必须验证 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)

Újrapróbálkozási mechanizmus

成功标准

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

重试策略

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

幂等处理

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

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

Code Samples

Kódpéldák

Teljes példa rendelés létrehozásra (aláírással) és aszinkron értesítések fogadására

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

Rendelés állapotátmenetek

A BlockSettler 12 állapotú állapotgépet használ a rendelés-életciklus kezeléséhez

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

Készen áll az integráció megkezdésére?

Regisztráljon fiókot, szerezze be az API Key-t, teszteljen sandbox környezetben, átlagosan 1 nap az éles indításig

Ingyenes regisztráció Technikai támogatás elérése

Fejlesztői integrációs útmutató

Gyors kezdés

Regisztráció és API Key beszerzése

Aszinkron értesítési cím beállítása

Rendelés létrehozási API hívása

Aszinkron értesítések kezelése

Tesztelés és éles indítás

HMAC-SHA256 aláírás-hitelesítés

Aszinkron értesítés (Webhook)

12 állapotú rendelésállapot-gép

Idempotencia és újrajátszás elleni védelem

API hitelesítési módszer

Kérés fejlécek (Required Headers)

Aláírási algoritmus

API felület dokumentáció

请求参数 (Request Body)

响应参数 (Response Body)

请求示例

响应示例

响应示例（支付完成后）

请求参数

Aszinkron értesítés (Webhook)

Támogatott eseménytípusok

Értesítési üzenet formátum

通知请求头

通知 Body 示例（payment.completed）

Aláírás-ellenőrzés

Újrapróbálkozási mechanizmus

成功标准

重试策略

幂等处理

Kódpéldák

Rendelés állapotátmenetek

Készen áll az integráció megkezdésére?