Ontwikkelaarsdocumentatie - BlockSettler API-integratiegids

Quick Start

Snel Starten

Betalingsintegratie in 5 stappen

Registreren en API Key Ophalen

Registreer een handelaarsaccount, maak een project aan in de console en ontvang uw Access Key en Secret Key.

Asynchroon Notificatieadres Configureren

Configureer de URL voor asynchrone notificaties in de projectinstellingen. Het systeem stuurt notificaties bij statuswijzigingen van orders.

API voor Orderaanmaak Aanroepen

Gebruik HMAC-SHA256 handtekening om POST /payments aan te roepen en het ontvangstadres en de afrekenlink te ontvangen.

Asynchrone Notificatie Verwerken

Ontvang de asynchrone notificatie, verifieer de X-BS-Signature handtekening en werk de lokale orderstatus bij.

Testen en Live Gaan

Voltooi alle tests in de sandbox-omgeving, bevestig dat alles werkt en schakel over naar de productieomgeving.

🔑

HMAC-SHA256 Handtekeningauthenticatie

Elk verzoek moet een Access Key, tijdstempel, willekeurige Nonce en HMAC-handtekening bevatten, zodat verzoeken niet vervalst kunnen worden.

🔔

Asynchrone Notificatie (Webhook)

Ondersteuning voor 8 eventtypen waaronder payment.completed, order.expired, payment.underpaid, die de volledige betalingslevenscyclus dekken.

🔄

12-State Order State Machine

PENDING → PAID_UNCONFIRMED → CONFIRMED → COMPLETED, met uitzonderingstakken (onderbetaling/overbetaling/verlopen/risicocontrole), duidelijke en controleerbare statusovergangen.

🔒

Idempotentie & Anti-Replay

Anti-replay via Nonce, preventie van dubbele aanmaak via merchant_order_no, preventie van dubbele verwerking via event_id, drievoudige idempotentiegarantie.

Authentication

API-authenticatiemethode

Alle handelaars-API-verzoeken vereisen HMAC-SHA256 handtekeningauthenticatie

Vereiste Headers (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`

Handtekeningalgoritme

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-interfacedocumentatie

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

Asynchrone Notificatie (Webhook)

Wanneer de orderstatus wijzigt, stuurt BlockSettler een HTTP POST-verzoek naar het door de handelaar geconfigureerde callback-adres

Ondersteunde Eventtypen

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

Notificatieberichtformaat

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

Handtekeningverificatie

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

Herhaalmechanisme

成功标准

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

重试策略

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

幂等处理

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

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

Code Samples

Codevoorbeelden

Bevat complete voorbeelden voor orderaanmaak (met handtekening) en ontvangst van asynchrone notificaties

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

Orderstatusovergangen

BlockSettler gebruikt een 12-state state machine om de orderlevenscyclus te beheren

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

Klaar om te beginnen met integreren?

Registreer om een API Key te ontvangen, test in de sandbox-omgeving, gemiddelde integratie in 1 dag

Gratis Registreren Contact Technische Ondersteuning

Integratiegids voor Ontwikkelaars

Snel Starten

Registreren en API Key Ophalen

Asynchroon Notificatieadres Configureren

API voor Orderaanmaak Aanroepen

Asynchrone Notificatie Verwerken

Testen en Live Gaan

HMAC-SHA256 Handtekeningauthenticatie

Asynchrone Notificatie (Webhook)

12-State Order State Machine

Idempotentie & Anti-Replay

API-authenticatiemethode

Vereiste Headers (Required Headers)

Handtekeningalgoritme

API-interfacedocumentatie

请求参数 (Request Body)

响应参数 (Response Body)

请求示例

响应示例

响应示例（支付完成后）

请求参数

Asynchrone Notificatie (Webhook)

Ondersteunde Eventtypen

Notificatieberichtformaat

通知请求头

通知 Body 示例（payment.completed）

Handtekeningverificatie

Herhaalmechanisme

成功标准

重试策略

幂等处理

Codevoorbeelden

Orderstatusovergangen

Klaar om te beginnen met integreren?