Documentazione sviluppatori - Guida all'integrazione API BlockSettler

Quick Start

Avvio rapido

Integra i pagamenti in 5 passaggi

Registrati e ottieni la tua API Key

Crea un account commerciante, configura un progetto nella dashboard e ottieni il tuo Access Key e Secret Key.

Configura l'URL di notifica

Imposta l'URL di notifica Webhook nelle impostazioni del progetto. Il sistema inviera notifiche quando lo stato dell'ordine cambia.

Chiama l'API di creazione ordine

Usa HMAC-SHA256 per firmare la richiesta e chiama POST /payments per ottenere un indirizzo di ricezione e un link di pagamento.

Gestisci le notifiche Webhook

Ricevi le notifiche Webhook, verifica la firma X-BS-Signature e aggiorna lo stato dell'ordine locale.

Testa e vai in produzione

Completa i test end-to-end nell'ambiente sandbox, poi passa alla produzione dopo la verifica.

🔑

Autenticazione con firma HMAC-SHA256

Ogni richiesta deve includere un Access Key, timestamp, Nonce casuale e firma HMAC per garantire che le richieste non possano essere falsificate.

🔔

Notifiche asincrone (Webhook)

Supporto per 8 tipi di evento tra cui payment.completed, order.expired e payment.underpaid, coprendo l'intero ciclo di vita del pagamento.

🔄

Macchina a stati dell'ordine a 12 stati

PENDING → PAID_UNCONFIRMED → CONFIRMED → COMPLETED, con rami di eccezione (sottopagamento/sovrapagamento/scadenza/controllo rischi). Transizioni di stato chiare e controllabili.

🔒

Idempotenza e protezione anti-replay

Il Nonce previene attacchi replay, merchant_order_no previene creazioni duplicate, event_id previene elaborazioni duplicate: tripla protezione di idempotenza.

Authentication

Autenticazione API

Tutte le richieste API del commerciante richiedono l'autenticazione con firma HMAC-SHA256

Header richiesti (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`

Algoritmo di firma

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

Documentazione di riferimento 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

Notifiche asincrone (Webhook)

Quando lo stato di un ordine cambia, BlockSettler invia una richiesta HTTP POST all'URL di callback configurata dal commerciante

Tipi di evento supportati

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

Formato del messaggio di notifica

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

Verifica della firma

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

Meccanismo di tentativi

成功标准

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

重试策略

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

幂等处理

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

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

Code Samples

Esempi di codice

Esempi completi per la creazione di ordini (con firma) e la ricezione di notifiche Webhook

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

Transizioni di stato dell'ordine

BlockSettler utilizza una macchina a 12 stati per gestire il ciclo di vita dell'ordine

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

Pronto per iniziare l'integrazione?

Registrati per ottenere un'API Key, testa nell'ambiente sandbox e vai in produzione in 1 giorno in media

Registrazione gratuita Contatta il supporto tecnico

Guida all'integrazione per sviluppatori

Avvio rapido

Registrati e ottieni la tua API Key

Configura l'URL di notifica

Chiama l'API di creazione ordine

Gestisci le notifiche Webhook

Testa e vai in produzione

Autenticazione con firma HMAC-SHA256

Notifiche asincrone (Webhook)

Macchina a stati dell'ordine a 12 stati

Idempotenza e protezione anti-replay

Autenticazione API

Header richiesti (Required Headers)

Algoritmo di firma

Documentazione di riferimento API

请求参数 (Request Body)

响应参数 (Response Body)

请求示例

响应示例

响应示例（支付完成后）

请求参数

Notifiche asincrone (Webhook)

Tipi di evento supportati

Formato del messaggio di notifica

通知请求头

通知 Body 示例（payment.completed）

Verifica della firma

Meccanismo di tentativi

成功标准

重试策略

幂等处理

Esempi di codice

Transizioni di stato dell'ordine

Pronto per iniziare l'integrazione?