Tài liệu nhà phát triển

Tạo đơn thanh toán stablecoin

Tạo đơn USDT / USDC từ máy chủ với yêu cầu API có chữ ký. Kiểm tra tham số, mạng, đầy đủ số tiền, liên kết thanh toán, thời hạn và cấu hình Webhook.

POST /api/v1/order/create

Yêu cầu xác thực

Bao gồm X-Bolt-Key, X-Bolt-Timestamp và X-Bolt-Signature. Sử dụng timestamp mili giây hiện tại và ký timestamp cùng với nội dung yêu cầu thô chính xác.

USDTUSDC

Khớp số lượng chính xác

Vì sao số tiền thanh toán API trả về có thể cao hơn một chút?

Kế hoạch ra mắt

3 chữ số cố định

Chuyên nghiệp kinh doanh

Có thể định cấu hình 2-6

Hệ thống làm tròn lên theo độ chính xác nhận diện đã cấu hình. Nếu một đơn đang chờ khác trên cùng mạng, loại tiền và ví nhận đã dùng số tiền đó, hệ thống cộng một khoản chênh lệch nhỏ để phân biệt đơn mới. Số tiền phải trả không thấp hơn số tiền gốc. Tài khoản miễn phí dùng 3 chữ số thập phân; thành viên Pro có thể chọn 2–6. Dùng payment.amount trong phản hồi.

Luồng phù hợp

Tạo đơn hàng

1

amount

Phần phụ trợ của bạn gửi số tiền thanh toán và BoltUtil trả về số tiền phải trả trên chuỗi.

Hiển thị thanh toán

2

payment.amount

Hiển thị chính xác số tiền được trả lại, mạng và địa chỉ nhận cho người trả tiền.

Đối chiếu thanh toán trên chuỗi

3

Webhook

Màn hình khớp với mạng, địa chỉ, mã thông báo, số tiền và trạng thái đơn hàng trước khi thông báo cho bạn.

Ghi chú tích hợp

1

Hiển thị payment.amount từ phản hồi tạo đơn hàng, không phải số lượng yêu cầu hoặc giá sản phẩm ban đầu.

2

Không làm tròn, cắt bớt hoặc xóa phần thập phân nhỏ khi hiển thị hướng dẫn thanh toán.

3

Việc thay đổi độ chính xác bù trừ chỉ ảnh hưởng đến các đơn hàng mới được tạo, không ảnh hưởng đến các đơn hàng đang chờ xử lý hiện có.

4

Xác minh chữ ký Webhook và loại bỏ thông báo trùng lặp trước khi externalOrderId thực hiện và xác nhận trạng thái thanh toán. Thanh toán đang chờ xác nhận không phải là thanh toán thành công.

01. Nội dung yêu cầu

JSON Payload
amount
Bắt buộc
Decimal

Số lượng đơn đặt hàng kinh doanh hoặc sản phẩm gốc bằng đơn vị tiền tệ được chỉ định bởi currency. Gửi một chuỗi để tránh mất độ chính xác của dấu phẩy động. Người trả tiền phải thanh toán payment.amount được trả lại thay vì giá trị này.

Mức tối thiểu cơ bản: 1.00. Đồng thời phải đáp ứng mức tối thiểu được cấu hình cho mạng và loại tiền đã chọn.Giới hạn độ chính xác: Tối đa 6 chữ số thập phânRủi ro bảo mật: Nghiêm cấm chuyển số tiền được tính toán trên giao diện người dùng. Luôn truy xuất các giá trị từ cơ sở dữ liệu phụ trợ của bạn.
externalOrderId
Bắt buộc
String

Đơn đặt hàng kinh doanh ID của bạn, được sử dụng để liên kết đơn hàng BoltUtil. Truy vấn sử dụng externalOrderId; phản hồi tạo trả về merchantExternalId và Webhooks trả về externalOrderId.

Phải là duy nhất trên toàn cầu cho mỗi người bánĐược hỗ trợ: Chữ cái, số, dấu gạch dưới (_), dấu gạch ngang (-)Giới hạn độ dài: 6 - 64 ký tựID trùng lặp trả về lỗi thay vì đơn hàng hiện có.
network
Bắt buộc
String

Chọn mạng thanh toán bằng cách sử dụng một trong các giá trị chữ hoa bên dưới. Ví dụ: sử dụng BASE cho Base hoặc ERC20 cho Ethereum.

Giá trị mẫu

"network": "BASE"
Các giá trị được phép: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEHiển thị cùng một mạng khi thanh toán.
currency
Bắt buộc
String

Chọn loại tiền thanh toán. Chỉ vượt qua USDT hoặc USDC; chỉ định mạng riêng trong network.

Giá trị mẫu

"currency": "USDC"
Giá trị được phép: USDT, USDC⚠️ TRC20 chỉ hỗ trợ USDT. Các cặp khác yêu cầu tuyến đường được kích hoạt và ví nhận hợp lệ.
orderDesc
String

Tóm tắt doanh nghiệp hoặc sản phẩm tùy chọn cho hồ sơ đơn hàng. Thanh toán hiện tại không hiển thị trường này.

Định dạng được đề xuất: Nạp tiền - [Tài khoản người dùng]Độ dài tối đa: 255 ký tự
notifyUrl
URL

Bộ thu Webhook cho đơn hàng này. Nếu bị bỏ qua, địa chỉ mặc định đã bật trong trang tổng quan dành cho người bán của bạn sẽ được sử dụng.

Phải là HTTPSPhải có thể truy cập công khaiKhông thể thay đổi: URL này không thể sửa đổi sau khi đơn hàng được tạo.Trước khi tạo đơn hàng, hãy định cấu hình và bật Webhook cũng như bí mật ký tên trong trang tổng quan của bạn. Tham số này không thay thế cấu hình đó.Độ dài tối đa: 255 ký tự
returnUrl
URL

Sau khi thanh toán hoàn tất hoặc người dùng chọn quay lại, thanh toán sẽ chuyển hướng trình duyệt tới URL này. Nó chỉ là một điểm đến điều hướng và không chứng minh được sự thành công của việc thanh toán.

Xác minh thanh toán thông qua Webhook đã ký hoặc truy vấn trạng thái đơn hàngNếu bỏ qua, mặc định là https://boltutil.com.Độ dài tối đa: 255 ký tự
expiredMinutes
Long

Số phút mà một đơn hàng còn lại có thể thanh toán sau khi tạo. Gói miễn phí được cố định ở mức 30 phút; Thành viên chuyên nghiệp có thể chọn 15-60 phút.

Phạm vi có thể định cấu hình: 15-60 phútMặc định: 30 phútChỉ thành viên Pro mới có thể tùy chỉnh giá trị này; gói miễn phí được cố định ở mức 30 phútTài khoản miễn phí bỏ qua các giá trị tùy chỉnh trong phạm vi hợp lệ và sử dụng 30 phút. Sử dụng time.expireTimestamp làm thời hạn thực tế.
metadata
Map

JSON data do người bán xác định. BoltUtil không sửa đổi nó và trả về nó không thay đổi trong phản hồi tạo đơn hàng, phản hồi trạng thái đơn hàng và Webhook.

Định dạng: đối tượng JSON tiêu chuẩnĐược trả về không thay đổi và không bao giờ được sử dụng để khớp thanh toánTối đa 10 khóa cấp cao nhất

02. Chi tiết phản hồi

application/json
orderToken
BoltUtil mã định danh đơn hàng để mở thanh toán. Truy vấn API của người bán sử dụng externalOrderId.
merchantExternalId
Tương ứng với externalOrderId trong yêu cầu.
status
PENDING sau khi tạo thành công. Xem tài liệu về trạng thái đơn hàng để biết trạng thái thanh toán và gọi lại sau này.
Tra cứu trạng thái đơn hàng →
checkoutUrl
Liên kết thanh toán thanh toán độc quyền.
returnUrl
Địa chỉ trả lại thanh toán. Mặc định là https://boltutil.com nếu bị bỏ qua.
metadata
Đối tượng data chuyển qua tùy chỉnh.

data.payment { ... }

address
Người bán nhận ví được đơn đặt hàng này sử dụng. Nhiều đơn hàng có thể chia sẻ địa chỉ này; không có địa chỉ mới nào được tạo cho mỗi đơn hàng.
amount
Số tiền phải trả chính xác, được trả về dưới dạng chuỗi. Hiển thị đầy đủ mà không làm tròn hoặc cắt bớt.
rawAmount
Số lượng trong đơn vị mã thông báo nhỏ nhất, được trả về dưới dạng chuỗi số nguyên: payment.amount × 10^payment.decimal. Đối với decimal = 6, một mã thông báo bằng 1.000.000 đơn vị nhỏ nhất.
currency
Ký hiệu tiền tệ.
network
Mã định danh mạng.
qrData
Chuỗi địa chỉ để tạo mã QR thanh toán. Không chứa số tiền, loại tiền hay mạng. Hiển thị riêng payment.amount, currency và network.
decimal
Độ chính xác của token trên mạng này, dùng để quy đổi rawAmount. Đây không phải độ chính xác dùng để phân biệt số tiền của các đơn hàng.

data.time { ... }

expireTimestamp
Trong data.time: lệnh hết hạn dưới dạng Unix mili giây timestamp.
serverTimestamp
Trong data.time: thời gian máy chủ khi phản hồi được tạo, dưới dạng Unix mili giây timestamp.

Các lỗi thường gặp

Đây là những trường hợp phổ biến. Sử dụng trạng thái HTTP thực tế và mã/thông báo phản hồi để chẩn đoán lỗi. Phản hồi lỗi không phải là kết quả thanh toán.

  • 401: Kiểm tra Khóa API, chữ ký nội dung thô và timestamp mili giây hiện tại (trong vòng 5 phút tính từ đồng hồ máy chủ).
  • 400: externalOrderId đã tồn tại. Truy vấn đơn hàng ban đầu thay vì tạo đơn hàng kinh doanh trùng lặp.
  • 400: Kiểm tra các tham số bắt buộc, mạng/tài sản có sẵn, ví nhận và cấu hình Webhook đã bật.
  • 429: Vượt giới hạn tần suất hoặc hạn ngạch tạo đơn miễn phí mỗi ngày. Kiểm tra mã lỗi nghiệp vụ và message.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Địa chỉ, băm giao dịch và đơn đặt hàng là ví dụ. Thay thế chúng bằng bài kiểm tra data của riêng bạn.

Base URL

PROD
https://api.boltutil.com