Dùng nó mà không cần nút mua
Nút mua là một lớp tiện ích. Bên dưới, Coin Moebius là một webhook được thuê cộng với vài endpoint JSON. Nếu bạn muốn tự dựng giao diện của mình, chạy luồng thanh toán của riêng bạn, hoặc cắm Coin Moebius vào một thứ mà cái nút không xử lý được (gói đăng ký Square hoặc Authorize.Net, một biểu mẫu thanh toán tùy chỉnh, một script phía máy chủ, một ứng dụng di động), mọi endpoint mà cái nút dùng cũng có thể được gọi từ bất cứ thứ gì. Không thay đổi mã ở phía chúng tôi.
Xác thực các lệnh gọi từ máy chủ
Các lệnh gọi bạn thực hiện từ máy chủ của riêng mình có thể mang theo khóa API của dự án dưới dạng bearer token. Tạo một khóa trong bảng điều khiển, dưới mục khóa API của dự án (nó bắt đầu bằng cmk_), và gửi nó trong header Authorization:
Authorization: Bearer cmk_live_xxxxxxxxxxxxxxxxxxxxxxxxKhóa được gắn với một dự án, và các lệnh gọi đã xác thực có giới hạn tốc độ cao hơn so với ẩn danh. Bản thân nút mua là công khai và không cần khóa. Giữ khóa của bạn trên máy chủ. Không bao giờ đặt nó trong mã trình duyệt hay mã phía client khác.
Tất cả các endpoint này nằm dưới URL dự án của bạn. Trong môi trường sản xuất, địa chỉ cơ sở đó là https://api.coinmoebius.com. URL đầy đủ cho mỗi cái được hiển thị bên dưới (thay các phần {…} bằng giá trị của riêng bạn).
| Endpoint | Nó làm gì |
|---|---|
POST https://api.coinmoebius.com/api/checkout/{provider}/{projectId} | Bắt đầu một khâu thanh toán. POST { productId, metadata }; nhận lại bất cứ thứ gì nhà cung cấp cần (một URL chuyển hướng cho Stripe, một URL phê duyệt cho PayPal, một token cho Authorize.Net Accept Hosted). Hiển thị nó theo cách bạn muốn. |
POST https://api.coinmoebius.com/webhook/{provider}/{projectId} | Nhà cung cấp gửi đến đây. Chúng tôi xác minh chữ ký, chuẩn hóa sự kiện, lưu nó, đếm hạn mức. Trỏ webhook của nhà cung cấp về URL này dù khâu thanh toán gốc đến từ nút của chúng tôi hay tích hợp của riêng bạn. |
GET https://api.coinmoebius.com/status/{projectId}/{txId} | Truy vấn trạng thái hiện tại của một khoản thanh toán hay gói đăng ký. Trả về cùng dạng đã chuẩn hóa mà nút mua nhận được. |
POST https://api.coinmoebius.com/api/subscriptions/{projectId}/{subscriptionId}/portal-url | Tạo một URL cổng được lưu trữ bởi nhà cung cấp để người mua quản lý gói đăng ký của họ. Hoạt động với bất kỳ nhà cung cấp nào có cổng. |
Nhận diện người mua trong hệ thống của riêng bạn bằng cách truyền metadata.customerRef trên lệnh gọi thanh toán. Nó luồn qua nhà cung cấp và quay lại trên mọi sự kiện webhook, nên bạn có thể nối hồ sơ của Coin Moebius với cơ sở dữ liệu người dùng của riêng bạn mà chúng tôi không lưu bất cứ thứ gì về người mua.
Vì sao ai đó dùng con đường này: một người dựng trang tĩnh muốn tự viết nút của mình để khớp thiết kế trang và chỉ cần webhook được xử lý. Một lập trình viên muốn bỏ qua cái nút hoàn toàn và gọi API từ máy chủ của riêng mình. Một người bán muốn chạy gói đăng ký Square hoặc Authorize.Net và sẵn lòng tự nối khâu thu thẻ. Cái nút là một điểm khởi đầu. API mới là sản phẩm thực sự.
Lắng nghe các sự kiện của người mua
Phần tử kích hoạt ba sự kiện trình duyệt. Lắng nghe bằng addEventListener trên phần tử (hoặc trên document, các sự kiện sẽ nổi lên). Mọi sự kiện đều có thể hủy, gọi event.preventDefault() sẽ dừng luồng mặc định.
| Sự kiện | Khi nào nó kích hoạt | Payload chi tiết |
|---|---|---|
cm-load-providers | Cửa sổ bộ chọn sắp hỏi API về danh sách nhà cung cấp đã cấu hình trên dự án này. | Rỗng. |
cm-checkout-started | Người mua đã chọn một nhà cung cấp và Coin Moebius sắp tạo một phiên thanh toán (Stripe / NOWPayments) hoặc tạo một mã tham chiếu (thủ công). | { provider: 'stripe' | 'nowpayments' | 'manual', ... } |
cm-error | Một thứ gì đó thất bại: lỗi mạng, lỗi chữ ký, không có nhà cung cấp nào được cấu hình. | { error: Error } |
document.addEventListener('cm-error', (event) => {
console.error('Coin Moebius:', event.detail.error);
// Show your own error UI, send to your analytics, etc.
});Không có sự kiện cm-success nào trong trình duyệt của người mua. Đến lúc khoản thanh toán thực sự hoàn tất, người mua đã được chuyển hướng đến khâu thanh toán được lưu trữ của nhà cung cấp (Stripe Checkout, trang hóa đơn NOWPayments). Họ quay lại trang của bạn qua success_url bạn đã cấu hình (xem mục tiếp theo), và máy chủ của bạn biết về khoản thanh toán qua bảng điều khiển hoặc bằng cách truy vấn endpoint /status.
Truy vấn từ máy chủ của bạn
Để có một nguồn sự thật phía máy chủ, hãy truy vấn GET /status/:projectId/:txId từ máy chủ của bạn. Dạng phản hồi:
{
"status": "succeeded",
"amount": 29.99,
"currency": "USD",
"isTest": false,
"createdAt": "2026-05-14T01:04:21.000Z",
"updatedAt": "2026-05-14T01:04:21.000Z"
}Các giá trị trạng thái theo cùng enum như bảng điều khiển (xem Các trạng thái giao dịch). Endpoint không yêu cầu xác thực nhưng bị giới hạn ở 60 yêu cầu / phút trên mỗi IP. Id giao dịch bạn truyền là bất cứ thứ gì mà SDK trả về trong sự kiện cm-checkout-started hoặc thứ hiển thị trong cột Tham chiếu của bảng điều khiển.
Một mẫu điển hình: khi trang success_url của bạn tải, khởi động một tác vụ phía máy chủ truy vấn /status/:projectId/:txId mỗi 15 giây cho đến khi nó thấy succeeded (hoặc failed / một lần hết giờ), rồi xử lý đơn hàng.