Nhà phát triển

Tài liệu tham khảo API

Một REST API nhỏ gọn cho hóa đơn, liên kết thanh toán, số dư và coin được chấp nhận. API dùng JSON qua HTTPS, và mọi yêu cầu đều được thực hiện bằng khóa bí mật của bạn.

URL gốc

Môi trường production: https://cryptomerchant.online/api/v1
Phát triển cục bộ: http://localhost:3000/api/v1

Bản mô tả API này mà máy có thể đọc nằm tại /openapi.json (OpenAPI 3.1). Bạn có thể nhập nó vào Postman hoặc một trình tạo client.

Xác thực

Gửi khóa bí mật của bạn trong header Authorization của mọi yêu cầu, dưới dạng Bearer token. Tạo khóa trong cổng quản lý, mục Nhà phát triển.

HTTP

Authorization: Bearer cm_live_…

Khóa bắt đầu bằng cm_live_ trên mainnet và cm_test_ trên testnet.
Khóa đầy đủ chỉ hiển thị một lần, khi bạn tạo. Chúng tôi chỉ lưu hash của khóa, vì vậy hãy cất giữ khóa ở nơi an toàn.
Chỉ dùng khóa trên máy chủ của bạn. Đừng bao giờ đặt khóa trong trang web, ứng dụng di động hoặc kho mã nguồn công khai.
Nếu một khóa có thể đã bị lộ, hãy thu hồi khóa đó trong cổng quản lý và tạo khóa mới.

Lỗi

Khi một yêu cầu thất bại, phản hồi có mã trạng thái lỗi HTTP và body JSON gồm code để máy đọc và message để người đọc:

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

Trạng thái HTTP

400: Yêu cầu không hợp lệ, ví dụ thiếu trường hoặc số tiền quá nhỏ.
401: Khóa API bị thiếu, sai hoặc đã bị thu hồi.
403: Tài khoản của bạn không thể thực hiện thao tác này: tài khoản chưa được kích hoạt hoặc đang bị tạm ngưng.
404: Đối tượng không tồn tại, hoặc thuộc về doanh nghiệp khác.
409: Hóa đơn không thể thực hiện thao tác này ở trạng thái hiện tại, ví dụ hủy một hóa đơn đã có thanh toán.
500: Đã xảy ra lỗi ở phía chúng tôi. Hãy thử lại sau ít phút.

Các mã bạn có thể gặp

invalid_json: Body của yêu cầu không phải là một đối tượng JSON.
invalid_request: Một trường bị thiếu hoặc không hợp lệ. Thông báo sẽ nêu tên trường.
unauthorized: Khóa API bị thiếu, sai hoặc đã bị thu hồi.
account_suspended: Tài khoản người bán này đang bị tạm ngưng.
merchant_not_live: Tài khoản của bạn chưa được kích hoạt. Hãy hoàn tất thiết lập trong cổng quản lý trước.
invalid_amount: Số tiền bị thiếu, không phải là số, hoặc không lớn hơn 0.
amount_too_small: Số tiền có giá trị dưới 0,50 đô la Mỹ.
invalid_asset: Mã coin không phải là coin đã biết.
asset_not_accepted: Bạn không chấp nhận coin đó.
invalid_state: Hóa đơn không thể thực hiện thao tác này ở trạng thái hiện tại.
not_found: Không có đối tượng nào với ID đó.
server_error: Đã xảy ra lỗi ở phía chúng tôi.

Đối tượng hóa đơn

Hóa đơn có cấu trúc này trong phản hồi API và trong webhook. Số tiền là chuỗi thập phân, nên không bị mất độ chính xác.

idstring: ID hóa đơn, bắt đầu bằng inv_.
objectstring: Luôn là invoice.
statusstring: Trạng thái hiện tại. Xem danh sách trạng thái bên dưới.
amountstring: Giá bạn yêu cầu, tính bằng currency.
currencystring: Tiền tệ của giá, ví dụ USD.
amount_usdstring: Giá tính bằng đô la Mỹ.
descriptionstring | null: Mô tả của bạn, hiển thị cho khách hàng.
order_idstring | null: Mã tham chiếu đơn hàng của riêng bạn.
customer_emailstring | null: Email của khách hàng, nếu bạn có cung cấp.
metadataobject: Đối tượng bạn truyền vào khi tạo hóa đơn, được trả về nguyên vẹn.
coinobject | null: Coin khách hàng đã chọn, hoặc coin họ thực sự dùng để thanh toán, với id, symbol và network. Là null cho đến khi coin được chọn.
requested_coinobject | null: Thường là null. Khi khách hàng thanh toán bằng coin khác hoặc trên mạng khác và khoản thanh toán được tính, đây là coin hóa đơn đã yêu cầu, với các trường giống như coin. Xem sai coin hoặc sai mạng.
pay_addressstring | null: Địa chỉ nạp cho hóa đơn này. Là null cho đến khi coin được chọn.
pay_amountstring | null: Số tiền chính xác cần gửi, tính bằng coin đã chọn.
network_fee_amountstring: Một phần của pay_amount: phí gas mà khách hàng trả thêm ngoài giá, tính bằng coin. 0 khi không có.
network_fee_usdstring: Cùng khoản phí gas đó, tính bằng đô la Mỹ.
rate_usdstring | null: Giá đã chốt của một đơn vị coin đã chọn, tính bằng đô la Mỹ.
received_amountstring: Số tiền đã đến cho đến nay, tính bằng coin đã chọn.
received_usdstring: Giá trị bằng đô la Mỹ của số đã đến.
overpaid_amountstring: Số tiền đã trả vượt quá yêu cầu của hóa đơn, tính bằng coin đã chọn.
refunded_amountstring: Số tiền bạn đã hoàn cho khoản thanh toán này bằng liên kết hoàn tiền, tính bằng coin đã thanh toán. Là 0 nếu chưa hoàn gì.
checkout_urlstring: Trang hóa đơn. Đưa khách hàng của bạn đến đây để thanh toán.
redirect_urlstring | null: Nơi khách hàng có thể đến sau khi thanh toán.
expires_atISO 8601: Thời điểm hóa đơn hết hạn nếu không thấy khoản thanh toán nào.
paid_atISO 8601 | null: Thời điểm hóa đơn được thanh toán, hoặc null.
created_atISO 8601: Thời điểm hóa đơn được tạo.

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Trạng thái hóa đơn

openĐang mở: Đã tạo. Khách hàng chưa chọn coin.
awaiting_paymentChờ thanh toán: Đã chọn coin, đã gán địa chỉ nạp và đã chốt tỷ giá.
confirmingĐang xác nhận: Đã thấy một khoản thanh toán on-chain và đang chờ xác nhận.
underpaidThanh toán thiếu: Khoản thanh toán đã xác nhận thiếu nhiều hơn mức dung sai của bạn. Khách hàng có thể trả phần còn lại hoặc yêu cầu hoàn tiền.
paidĐã thanh toán: Đã thanh toán và xác nhận. Số tiền, sau khi trừ phí, đã vào số dư của bạn. Hoàn tiền một phần vẫn giữ trạng thái này.
expiredĐã hết hạn: Đã hết thời gian trước khi thấy khoản thanh toán nào.
cancelledĐã hủy: Hóa đơn đã bị hủy trước khi thấy khoản thanh toán nào.
refundedĐã hoàn tiền: Khách hàng đã được hoàn lại số đã gửi cho một hóa đơn thanh toán thiếu, hoặc bạn đã hoàn toàn bộ số bạn giữ lại từ một hóa đơn đã thanh toán.

Tạo hóa đơn

POST/invoices

Tạo một hóa đơn và trả về đối tượng hóa đơn với trạng thái 201. Đưa khách hàng của bạn đến checkout_url của hóa đơn.

Tham số body

amountBắt buộcnumber | string: Giá, dưới dạng số hoặc chuỗi thập phân. Phải có giá trị ít nhất 0,50 đô la Mỹ.
currencyKhông bắt buộcstring: Tiền tệ của giá, ví dụ USD. Mặc định là USD.
descriptionKhông bắt buộcstring: Khách hàng đang trả tiền cho gì, tối đa 300 ký tự. Hiển thị trên trang hóa đơn.
order_idKhông bắt buộcstring: Mã tham chiếu đơn hàng của riêng bạn, tối đa 120 ký tự, để khớp hóa đơn với đơn hàng.
customer_emailKhông bắt buộcstring: Địa chỉ email của khách hàng. Các khoản thanh toán được nhóm theo khách hàng trong cổng quản lý.
customer_nameKhông bắt buộcstring: Tên khách hàng, tối đa 120 ký tự.
redirect_urlKhông bắt buộcstring: Một URL đầy đủ mà khách hàng có thể đến sau khi thanh toán.
metadataKhông bắt buộcobject: Bất kỳ đối tượng JSON nào tối đa 4 KB. Được trả về nguyên vẹn trên hóa đơn và trong webhook.
coinKhông bắt buộcstring: Chọn trước một coin theo ID, ví dụ USDT.TRON. Coin này phải nằm trong số coin được chấp nhận của bạn.

Khi chọn trước coin, địa chỉ nạp được gán và tỷ giá được chốt ngay lập tức, nên pay_address và pay_amount đã có giá trị và bạn có thể hiển thị thông tin thanh toán trong giao diện của riêng mình.

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Liệt kê hóa đơn

GET/invoices

Trả về các hóa đơn của bạn, mới nhất trước, mỗi lần một trang.

Tham số query

statusKhông bắt buộcstring: Chỉ các hóa đơn có trạng thái này, ví dụ paid. Phải là một trong các trạng thái ở trên.
limitKhông bắt buộcnumber: Số hóa đơn cần trả về, từ 1 đến 100. Mặc định là 20.
starting_afterKhông bắt buộcstring: Một ID hóa đơn. Trả về các hóa đơn đứng sau hóa đơn đó, cho trang tiếp theo.

Các hóa đơn nằm trong data. Khi has_more là true, hãy yêu cầu trang tiếp theo với starting_after đặt bằng ID của hóa đơn cuối cùng bạn nhận được.

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Phản hồi

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Lấy một hóa đơn

GET/invoices/{id}

Trả về một hóa đơn theo ID.

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Hủy hóa đơn

POST/invoices/{id}/cancel

Hủy một hóa đơn. Chỉ thực hiện được khi hóa đơn chưa được thanh toán và chưa thấy khoản thanh toán nào cho hóa đơn đó.

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Số dư

GET/balances

Trả về số coin doanh nghiệp của bạn đang giữ theo từng coin, tổng giá trị bằng đô la Mỹ, và số dư gas của bạn.

data[].coin: ID coin, ví dụ USDT.TRON.
data[].symbol: Ký hiệu coin, ví dụ USDT.
data[].network: Mạng chứa coin.
data[].amount: Số lượng coin bạn đang giữ, dưới dạng chuỗi thập phân.
data[].usd: Giá trị bằng đô la Mỹ theo giá hiện tại.
total_usd: Tổng giá trị tất cả coin của bạn bằng đô la Mỹ.
gas_balance_usd: Số dư gas của bạn bằng đô la Mỹ, dùng để trả phí gas.

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Phản hồi

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Coin được chấp nhận

GET/coins

Trả về các coin bạn đang chấp nhận, mỗi coin có id, symbol, name, network và decimals. Dùng id làm coin khi bạn tạo hóa đơn. Ví dụ:

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Phản hồi

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Tạo liên kết thanh toán

POST/payment-links

Tạo một liên kết thanh toán và trả về liên kết đó với trạng thái 201, bao gồm id và url có thể chia sẻ.

Tham số body

titleBắt buộcstring: Tên của thứ khách hàng trả tiền, tối đa 120 ký tự.
amountKhông bắt buộcnumber | string: Giá cố định. Bỏ trống để khách hàng tự nhập số tiền.
currencyKhông bắt buộcstring: Tiền tệ của giá. Mặc định là USD.
descriptionKhông bắt buộcstring: Thông tin chi tiết hơn hiển thị cho khách hàng, tối đa 300 ký tự.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

Phản hồi

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Liệt kê liên kết thanh toán

GET/payment-links

Trả về 100 liên kết thanh toán gần đây nhất của bạn, mới nhất trước, trong data.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Đối tượng chi trả

Các webhook chi trả (payout.sent và payout.failed) mang đối tượng này trong data. Các khoản chi trả phần của đối tác từ chia doanh thu dùng cùng đối tượng, với partner_share được đặt là true.

idstring: Mã khoản chi trả.
objectstring: Luôn là payout.
coinstring: Mã coin, ví dụ USDT.TRON.
amountstring: Số tiền đã chi trả, tính bằng coin đó.
network_feestring: Phí gas để gửi khoản này, tính bằng coin đó.
to_addressstring: Địa chỉ ví mà khoản này được gửi đến.
statusstring: queued, running, done hoặc failed.
tx_hashstring | null: Mã giao dịch trên blockchain, sau khi đã được gửi.
autoboolean: true nếu khoản chi trả được thực hiện tự động, không phải do một người yêu cầu.
partner_shareboolean: true nếu khoản chi trả này là phần của đối tác từ chia doanh thu, được gửi đến ví của đối tác.
created_atISO 8601: Thời điểm khoản chi trả được tạo.

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Tiếp theo, hãy thiết lập webhook để máy chủ của bạn nhận được thông tin về các khoản thanh toán ngay khi chúng xảy ra.