Convert API

Convert API cho phép bạn hoán đổi giữa các loại tiền tệ có trong số dư cửa hàng theo giá thị trường hiện tại — cùng một engine đang vận hành tab Swap trong bảng điều khiển cửa hàng, giờ đây có thể gọi trực tiếp từ backend của bạn.

Lấy báo giá chuyển đổi

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Thực hiện chuyển đổi

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Lỗi

Khi thất bại, phản hồi có state: 1 và một error_code — dùng chung cho /v1/convert/price và /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Tự động chuyển đổi các khoản thanh toán đến

Tự động chuyển đổi là một cài đặt dự án cho hóa đơn đến và tín dụng ví tĩnh. Nó được cấu hình trong bảng điều khiển thương nhân, không phải bằng cách thêm các trường vào /v1/payment. Mỗi quy tắc chọn một hoặc nhiều loại tiền nguồn và một loại tiền đích.

Khi quá trình chuyển đổi hoàn tất, thông tin thanh toán và webhook của thương nhân có thể bao gồm:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Các miền số tiền được tách biệt có chủ ý:

• payment_amount — số tiền được phát hiện trên chuỗi theo loại tiền thanh toán nguồn;
• merchant_amount — số tiền ròng nguồn được tính cho thương nhân trước khi chuyển đổi;
• convert.amount — số tiền được ghi có vào convert.to_currency;
• convert.rate và convert.commission — kết quả chuyển đổi đã thực hiện, không phải là giá bạn nên tính toán lại tại chỗ.

Thất bại tự động chuyển đổi và quay về

Chuyển đổi xảy ra sau khi nhận thanh toán blockchain. Tính khả dụng của thị trường, kích thước lệnh tối thiểu, giới hạn độ chính xác, thời gian chờ trao đổi và khả năng thanh khoản không đủ có thể làm chậm hoặc ngăn cản việc chuyển đổi.

• Các khoản gửi dưới mức tối thiểu toàn cầu/dự án sẽ bỏ qua đường ống chuyển đổi và ghi có bằng đơn vị tiền tệ nguồn.
• Các lỗi tạm thời có thể được thử lại một cách bất đồng bộ.
• Các khoản tiền gửi lớn hoặc không thể giao dịch có thể quay lại việc ghi có theo tiền tệ nguồn sau khi chính sách thử lại đã được sử dụng hết.
• Do đó, một khoản thanh toán có thể hợp lệ ngay cả khi việc chuyển đổi sang tiền tệ mục tiêu mong muốn không xảy ra.

Tích hợp của bạn nên lưu trữ khoản thanh toán đã xác minh trước, sau đó đối chiếu số tiền thực tế đã được ghi có từ thông tin thanh toán, khối convert tùy chọn và số dư của nhà bán hàng. Không chặn việc xác nhận webhook thanh toán trong khi chờ hệ thống phân tích hoặc thông báo của riêng bạn.

Kiểm tra chấp nhận tự động chuyển đổi

Kiểm tra ít nhất: chuyển đổi trực tiếp thành công, chuyển đổi qua cầu/nhiều bước, lượng nhỏ dưới mức tối thiểu, thử lại tạm thời, quay về tiền tệ nguồn, thanh toán thiếu, thanh toán thừa, webhook trùng lặp, thiếu convert, và đối soát sau khi hết thời gian không rõ ràng.

Các trường hợp biên của chuyển đổi thủ công

• /v1/convert/price là bản xem trước chỉ mang tính tham khảo; biến động thị trường có thể thay đổi kết quả thực hiện.
• amount_type: from sửa yêu cầu bên nguồn, trong khi amount_type: to yêu cầu số tiền bên mục tiêu. Không hoán đổi ý nghĩa khi trình bày giao diện xác nhận.
• Một cặp không có thị trường trực tiếp có thể được định tuyến qua một đồng tiền trung gian. Nếu chỉ một chặng được thực hiện, partially_completed sẽ báo cáo tín dụng trung gian.
• Nếu một lệnh thực thi hết thời gian chờ, hãy đối chiếu trước khi thử lại. Một lệnh thị trường vẫn có thể được thực hiện ngay cả khi phản hồi HTTP của nó bị mất.
• Xử lý failed như một trạng thái để đối chiếu, không phải là quyền để áp dụng một mục cân bằng bù tại địa phương; nền tảng sở hữu kế toán ghi nợ/hoàn tiền.