Các giải pháp chuyển đổi tiền pháp định sang tiền điện tử (fiat-to-crypto on-ramp) trước đây đòi hỏi hàng tuần làm giấy tờ tuân thủ, thiết lập quan hệ ngân hàng và các nhà cung cấp KYC được kết nối một cách tạm bợ. MoonPay API đã tích hợp tất cả các bước đó vào một quy trình duy nhất: bạn tạo một URL đã ký, đặt một widget vào ứng dụng của mình, và MoonPay sẽ xử lý việc thanh toán thẻ, chuyển khoản ngân hàng, xác minh danh tính và thanh toán vào ví của người dùng.
Hướng dẫn này sẽ trình bày cách sử dụng MoonPay API từ đầu đến cuối: thiết lập tài khoản đối tác, widget so với API trực tiếp, cấu trúc URL đã ký, xác minh webhook, quy trình bán, thanh toán NFT và các giới hạn tuân thủ mà bạn cần lên kế hoạch. Mọi yêu cầu dưới đây đã được kiểm tra trên môi trường sandbox và được ghi lại trong cổng thông tin nhà phát triển chính thức của MoonPay. Bạn có thể chạy các lệnh tương tự trong Apidog trong quá trình xây dựng.
nút
Nếu bạn vẫn đang so sánh các nhà cung cấp, hãy bắt đầu với tổng hợp các API chuyển đổi tiền pháp định sang tiền điện tử (fiat on-ramp và off-ramp) tốt nhất của chúng tôi để xem MoonPay phù hợp như thế nào so với Transak, Ramp và Stripe Crypto. Các nhà phát triển đang đánh giá cơ sở hạ tầng lưu ký cũng nên đọc cách sử dụng Circle API để có cái nhìn về phía USDC của hệ thống.
TL;DR
- MoonPay là một nền tảng chuyển đổi tiền pháp định sang tiền điện tử (on-ramp và off-ramp) được quản lý, được sử dụng bởi các ví, sàn giao dịch NFT và sàn giao dịch ở hơn 160 quốc gia.
- Hai phương thức tích hợp: Ramps SDK/widget (nhanh nhất, giao diện người dùng do MoonPay lưu trữ) hoặc REST API trực tiếp (kiểm soát hoàn toàn, bạn tự xây dựng giao diện người dùng).
- Tất cả các URL widget phải được ký bằng HMAC-SHA256 sử dụng khóa bí mật của bạn; các URL không có chữ ký sẽ bị từ chối trong môi trường sản phẩm.
- KYC, xử lý thẻ và hạ tầng ngân hàng được MoonPay xử lý ở phía máy chủ; bạn nhận trạng thái qua webhooks được ký bằng mẫu HMAC tương tự.
- Giá cả là phí xử lý (3.5%-4.5% cho thẻ, thấp hơn cho chuyển khoản ngân hàng) cộng với phí mạng cơ bản, được hiển thị minh bạch cho người dùng.
- Quy trình bán (off-ramp) tương tự quy trình mua: URL đã ký, người dùng gửi tiền điện tử đến địa chỉ nạp, MoonPay thanh toán tiền pháp định vào tài khoản ngân hàng của người dùng.
MoonPay là gì?
MoonPay là một công ty thanh toán có giấy phép cho phép người dùng của bạn mua và bán tiền điện tử bằng thẻ, chuyển khoản ngân hàng, Apple Pay, Google Pay, SEPA và các kênh thanh toán địa phương. Công ty này hoạt động như một doanh nghiệp dịch vụ tiền tệ tại Hoa Kỳ, có giấy phép EMI ở EU và có đăng ký tại Vương quốc Anh, Canada và Úc. Hiệu quả thực tế: bạn không cần phải trở thành một tổ chức chuyển tiền để chấp nhận thẻ và chuyển ETH vào ví của người dùng.
Nền tảng này hỗ trợ hơn 110 loại tiền điện tử trên hơn 40 mạng (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), cộng với thanh toán NFT. Đây là giải pháp on-ramp được tích hợp trong MetaMask, Trust Wallet và OpenSea.
Xác thực và thiết lập
Đăng ký tài khoản đối tác tại moonpay.com/business. Sau khi được chấp thuận, bạn sẽ nhận được hai bộ khóa: sandbox và production. Mỗi bộ có một khóa công khai (pk_test_...) và một khóa bí mật (sk_test_...). Hãy coi khóa bí mật như mật khẩu cơ sở dữ liệu; nó được dùng để ký mọi URL và xác minh mọi webhook.
Thiết lập chúng trong môi trường của bạn:
export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"
Môi trường sandbox có cùng các điểm cuối (endpoints) với môi trường production nhưng trả về các giao dịch thử nghiệm mà bạn có thể chuyển đổi trạng thái bằng bảng điều khiển. Sử dụng nó cho toàn bộ quy trình hoàn chỉnh, sau đó chuyển sang khóa production sau khi quá trình xem xét tuân thủ với MoonPay của bạn được thông qua.
Các điểm cuối chính
MoonPay cung cấp một vài nhóm điểm cuối mà bạn sẽ thường xuyên sử dụng nhất: tiền tệ, báo giá, giao dịch và webhook. Tham chiếu REST đầy đủ liệt kê mọi tài nguyên.
Liệt kê các loại tiền tệ được hỗ trợ
Trước khi bạn xây dựng bộ chọn, hãy lấy danh sách trực tiếp. Khả dụng thay đổi theo quốc gia, vì vậy bạn nên lọc bằng IP hoặc vị trí khai báo của người dùng.
curl -X GET "https://api.moonpay.com/v3/currencies" \
-H "Authorization: Api-Key $MOONPAY_API_KEY"
Phản hồi trả về một mảng với code, name, type (crypto hoặc fiat), minBuyAmount, maxBuyAmount và siêu dữ liệu cho từng mạng đối với các token tồn tại trên nhiều chuỗi.
Nhận báo giá thời gian thực
Báo giá cho người dùng biết chính xác số tiền điện tử họ sẽ nhận được trước khi họ cam kết. Phí đã được bao gồm.
curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
-H "Content-Type: application/json"
Bạn sẽ nhận được quoteCurrencyAmount, feeAmount, networkFeeAmount và totalAmount. Lưu trữ báo giá trong vài giây mà người dùng cần để nhấp qua; MoonPay sẽ duy trì báo giá đó trong khoảng 60 giây.
Xây dựng URL widget mua đã ký (Node)
Widget mua là cách nhanh nhất để tích hợp hoạt động. Bạn xây dựng một URL với các tham số truy vấn, ký nó bằng khóa bí mật của bạn và sau đó chuyển hướng người dùng hoặc tải nó trong một iframe. Đây là phiên bản Node:
import crypto from "node:crypto";
function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
const params = new URLSearchParams({
apiKey: process.env.MOONPAY_API_KEY,
currencyCode,
walletAddress,
baseCurrencyCode: "usd",
baseCurrencyAmount: String(baseAmount),
email,
redirectURL: "https://yourapp.com/moonpay/complete",
});
const originalUrl = `https://buy.moonpay.com?${params.toString()}`;
const signature = crypto
.createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
.update(new URL(originalUrl).search)
.digest("base64");
return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}
Chuyển URL này cho người dùng. Chữ ký liên kết các tham số với tài khoản của bạn, vì vậy một client độc hại không thể hoán đổi walletAddress hoặc thay đổi số tiền mà không làm mất hiệu lực của chữ ký. Hướng dẫn nhanh widget mua ghi lại mọi tham số được hỗ trợ.
Xác minh chữ ký webhook
MoonPay gửi các sự kiện vòng đời đến điểm cuối của bạn: transaction_created, transaction_updated, transaction_failed và các biến thể bán/NFT. Mỗi yêu cầu bao gồm một tiêu đề Moonpay-Signature-V2 mà bạn phải xác minh trước khi tin tưởng tải trọng (payload).
import crypto from "node:crypto";
export function verifyMoonPayWebhook(rawBody, header, secret) {
const [tPart, sPart] = header.split(",");
const timestamp = tPart.split("=")[1];
const signature = sPart.split("=")[1];
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expected, "hex"),
Buffer.from(signature, "hex"),
);
}
Từ chối mọi yêu cầu cũ hơn năm phút để ngăn chặn các cuộc tấn công phát lại. Tham chiếu webhook liệt kê mọi loại sự kiện và hình dạng tải trọng.
Quy trình bán (off-ramp)
Quy trình bán tương tự quy trình mua. Bạn xây dựng một URL đã ký trỏ đến sell.moonpay.com, người dùng chọn một loại tiền điện tử và số lượng, MoonPay tạo ra một địa chỉ nạp, và người dùng gửi tiền từ ví của họ. Khi giao dịch được xác nhận trên chuỗi, MoonPay sẽ thanh toán tiền pháp định vào tài khoản ngân hàng liên kết của người dùng.
const sellParams = new URLSearchParams({
apiKey: process.env.MOONPAY_API_KEY,
baseCurrencyCode: "eth",
baseCurrencyAmount: "0.5",
quoteCurrencyCode: "usd",
refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});
const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// sign the same way as the buy URL
refundWalletAddress rất quan trọng: nếu người dùng gửi sai tài sản hoặc giao dịch thất bại KYC, MoonPay sẽ hoàn lại tiền về địa chỉ đó.
Thanh toán NFT
Thanh toán NFT cho phép người dùng mua một NFT được niêm yết bằng thẻ. Bạn đăng ký niêm yết với MoonPay (hoặc sử dụng tích hợp thị trường được hỗ trợ), sau đó tạo một URL đã ký với contractAddress, tokenId và listingId. MoonPay xử lý bước chuyển đổi tiền pháp định và chuyển khoản on-chain trong một quy trình duy nhất, điều này làm giảm đáng kể tỷ lệ bỏ ngang trong các đợt bán chính có giá trị cao.
Các lỗi thường gặp và giới hạn tốc độ
Hầu hết các vấn đề tích hợp đều nằm trong một danh sách ngắn:
400 invalid_signaturecó nghĩa là đầu vào HMAC của bạn không khớp với máy chủ. Nguyên nhân thường xuyên nhất là sự khác biệt trong mã hóa URL giữa client và bộ ký của bạn. Hãy ký chuỗi truy vấn chính xác mà bạn gửi.403 geo_restrictedbáo hiệu IP của người dùng nằm ở một quốc gia mà MoonPay không phục vụ cho loại tiền tệ đó. Kiểm tra trườngisAllowedtrên đối tượng tiền tệ trước khi hiển thị.422 transaction_limit_exceededcó nghĩa là người dùng đã đạt giới hạn hàng ngày, hàng tuần hoặc hàng tháng. Giới hạn thẻ thường là $2.000/ngày và $10.000/tháng cho đến khi người dùng hoàn tất KYC nâng cao.429 rate_limitedkích hoạt ở khoảng 100 yêu cầu mỗi phút cho mỗi khóa API trên các điểm cuối công khai. Lưu trữ danh sách tiền tệ và báo giá một cách tích cực.
Đối với trạng thái, hãy tin tưởng webhook, không phải trình duyệt của người dùng. Một người dùng đóng tab trước khi chuyển hướng vẫn có ví được nạp tiền khi sự kiện transaction_updated kích hoạt với status: completed.
Nếu bạn đang xây dựng hỗ trợ đa ví, các hướng dẫn của chúng tôi về cách sử dụng MetaMask API và các API ví tiền điện tử tốt nhất rất phù hợp với hướng dẫn này. Đối với khía cạnh danh tính của việc tuân thủ, hãy xem tổng hợp API KYC tốt nhất của chúng tôi.
Giá của MoonPay
MoonPay tính phí xử lý cộng với phí mạng, cả hai đều được hiển thị cho người dùng trong widget:
- Mua bằng thẻ: 3,5%-4,5% số tiền pháp định, với mức tối thiểu $3,99.
- Chuyển khoản ngân hàng (ACH, SEPA, Open Banking): 1%-1,9%, rẻ hơn nhiều đối với các giao dịch lớn.
- Phí mạng: được chuyển trực tiếp theo chi phí, thay đổi tùy theo chuỗi và tắc nghẽn.
- Quy trình bán: cấu trúc tương tự, với phí thanh toán tùy thuộc vào kênh đích.
Phần chia sẻ doanh thu cho các đối tác được đàm phán riêng khi khối lượng giao dịch tăng lên. Các tích hợp có khối lượng lớn thường nhận được mức giá tùy chỉnh cộng với một liên hệ tuân thủ chuyên trách.
Kiểm thử MoonPay với Apidog
URL đã ký và webhook HMAC là hai điểm mà hầu hết các tích hợp MoonPay thường gặp lỗi, và cả hai đều nhanh hơn để gỡ lỗi trong một công cụ API phù hợp hơn là trong mã ứng dụng. Apidog cho phép bạn nhập thông số kỹ thuật OpenAPI của MoonPay, lưu trữ các khóa sandbox của bạn dưới dạng biến môi trường và chạy chu trình báo giá mua, trạng thái giao dịch và phát lại webhook mà không cần chạm vào backend của bạn.
Một quy trình làm việc thực tế: tạo một môi trường Apidog cho sandbox và một môi trường khác cho production, viết script tạo chữ ký như một hook tiền yêu cầu sử dụng đoạn mã Node crypto ở trên, và lưu các ID giao dịch mẫu dưới dạng biến để bạn có thể chuyển thẳng từ createTransaction đến getTransactionStatus. Khi một webhook đến trong môi trường production, hãy sao chép phần thân thô vào máy chủ ảo của Apidog và phát lại nó đối với điểm cuối cục bộ của bạn cho đến khi trình xác minh của bạn vượt qua. Tải xuống Apidog để có các hook ký, máy chủ ảo và bộ chuyển đổi môi trường ở cùng một nơi.
Câu hỏi thường gặp
Tôi có cần nhà cung cấp KYC riêng ngoài MoonPay không?Không. MoonPay thực hiện xác minh danh tính ở phía máy chủ; ứng dụng của bạn không bao giờ nhìn thấy tài liệu ID. Nếu bạn muốn xác minh trước cho các phần khác của sản phẩm, hãy xem so sánh API KYC tốt nhất của chúng tôi.
Tôi có thể sử dụng MoonPay mà không hiển thị widget có thương hiệu của họ không?Có, thông qua API trực tiếp hoặc Ramps SDK không giao diện, nhưng bạn cần một đánh giá tuân thủ bổ sung vì luồng có thương hiệu tự động bao gồm nhiều thông tin tiết lộ bắt buộc. Hầu hết các nhóm sẽ triển khai widget trước và di chuyển sau khi khối lượng đủ lớn để biện minh cho việc xem xét.
MoonPay hỗ trợ những quốc gia nào?Hơn 160 quốc gia cho việc mua và một tập hợp nhỏ hơn (khoảng 50) cho việc bán, với sự sẵn có của tiền tệ và phương thức thanh toán thay đổi theo khu vực. Điểm cuối tiền tệ trả về ma trận hiện tại theo vị trí người dùng.
Một giao dịch mất bao lâu?Mua bằng thẻ sẽ được thanh toán vào ví của người dùng trong vòng dưới năm phút trong trường hợp thuận lợi. Chuyển khoản ngân hàng mất 1-3 ngày làm việc để thanh toán tiền pháp định trước khi tiền điện tử được phát hành. Giao dịch bán sẽ thanh toán tiền pháp định vào ngân hàng của người dùng trong 1-3 ngày sau khi xác nhận on-chain.
Điều gì xảy ra nếu việc gửi webhook thất bại?MoonPay thử lại với thời gian chờ tăng dần trong tối đa 24 giờ. Bạn nên trả về phản hồi 2xx chỉ sau khi bạn đã lưu trữ sự kiện và loại bỏ trùng lặp theo id vì việc thử lại có thể tạo ra các bản sao.
Môi trường sandbox có tương đương với môi trường production không?Gần giống, nhưng không hoàn toàn giống. Các giới hạn địa lý được nới lỏng, KYC được bỏ qua bằng các tài liệu thử nghiệm và các giao dịch di chuyển qua các trạng thái dựa trên các điều khiển của bảng điều khiển. Luôn chạy một kiểm tra khói sản phẩm cuối cùng sau khi các khóa đã được cấp.