Sebastian Petrus

Posted on Apr 23 • Originally published at apidog.com

Cách sử dụng MoonPay API (Tích hợp On-Ramp và Off-Ramp Fiat)

#web3 #blockchain #api #tutorial

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) truyền thống yêu cầu rất nhiều thủ tục giấy tờ tuân thủ, thiết lập quan hệ ngân hàng và tích hợp KYC phức tạp. MoonPay API giúp đơn giản hóa toàn bộ quy trình: bạn chỉ cần tạo một URL đã ký, nhúng widget vào ứng dụng, còn lại MoonPay sẽ lo việc thanh toán, xác minh danh tính và giải ngân vào ví người dùng.

Hãy dùng thử Apidog ngay hôm nay

Bài viết này hướng dẫn triển khai MoonPay API từ A đến Z: tạo tài khoản đối tác, so sánh widget và API trực tiếp, ký URL, xác minh webhook, quy trình bán (off-ramp), thanh toán NFT và các giới hạn tuân thủ cần lưu ý. Tất cả yêu cầu bên dưới đã được kiểm thử trên sandbox và bám sát MoonPay Dev Portal. Bạn có thể chạy các request này ngay trong Apidog để tăng tốc phát triển.

Nếu bạn đang đánh giá nhiều nhà cung cấp, hãy xem bảng tổng hợp API fiat on-ramp/off-ramp tốt nhất để so sánh MoonPay với Transak, Ramp, Stripe Crypto. Nếu bạn quan tâm đến lưu ký hoặc stablecoin, đọc thêm về Circle API và hệ thống USDC.

TL;DR

MoonPay là nền tảng chuyển đổi tiền pháp định sang tiền điện tử (on-ramp/off-ramp) có giấy phép, dùng bởi nhiều ví, sàn NFT, sàn giao dịch ở hơn 160 quốc gia.
Có 2 cách tích hợp: Ramps SDK/widget (nhanh, giao diện do MoonPay lưu trữ) hoặc REST API (toàn quyền kiểm soát UI).
Mọi URL widget đều cần ký HMAC-SHA256 bằng secret key; URL không ký sẽ bị từ chối trên môi trường production.
MoonPay xử lý KYC, thanh toán, ngân hàng ở backend; bạn nhận trạng thái qua webhook (cũng ký HMAC).
Phí: 3.5%-4.5% cho thẻ, thấp hơn với chuyển khoản, hiển thị minh bạch với người dùng.
Quy trình bán (off-ramp) giống mua: URL đã ký, user gửi crypto, MoonPay chuyển tiền pháp định về ngân hàng.

MoonPay là gì?

MoonPay là công ty thanh toán có giấy phép, giúp user mua/bán crypto bằng thẻ, chuyển khoản, Apple Pay, Google Pay, SEPA... Công ty này được cấp phép MSB ở Mỹ, có license EMI ở EU, đăng ký ở Anh, Canada, Úc. Nhờ đó, bạn không cần trở thành tổ chức chuyển tiền để chấp nhận thẻ và chuyển ETH vào ví user.

Hỗ trợ hơn 110 loại crypto trên 40+ mạng (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), hỗ trợ cả thanh toán NFT. Đã được tích hợp trong MetaMask, Trust Wallet, 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 duyệt, bạn nhận được 2 bộ key: sandbox và production (mỗi bộ có pk_test_... và sk_test_...).
Thiết lập biến môi trường:

export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"

Sandbox và production có cùng endpoint, nhưng sandbox chỉ trả về giao dịch test, cho phép bạn chuyển trạng thái bằng dashboard.
Dùng sandbox cho toàn bộ quy trình thử nghiệm, chỉ chuyển sang khóa production sau khi qua kiểm duyệt tuân thủ.

Các endpoint chính

MoonPay cung cấp nhiều nhóm endpoint, nhưng bạn sẽ dùng thường xuyên nhất:

Tiền tệ (currencies)
Báo giá (quotes)
Giao dịch (transactions)
Webhook

Tham khảo REST đầy đủ: MoonPay API Reference.

Liệt kê loại tiền tệ hỗ trợ

Lấy danh sách token/tiền tệ khả dụng (nên lọc theo vị trí user):

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

Kết quả trả về mảng gồm code, name, type (crypto hoặc fiat), minBuyAmount, maxBuyAmount, các metadata mạng blockchain.

Nhận báo giá thời gian thực

Cung cấp cho user số crypto họ nhận được trước khi xác nhận. Phí đã gồm trong quote.

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"

Trả về: quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount. Nên cache quote này trong 60 giây (MoonPay giữ giá trong 60s).

Xây dựng URL widget mua đã ký (Node.js)

Widget là cách tích hợp nhanh nhất. Tạo URL với query param, ký bằng secret key, redirect user hoặc nhúng iframe.

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 user. Chữ ký giúp bảo vệ các tham số (không ai đổi được số tiền, ví). Tham khảo thêm hướng dẫn widget MoonPay.

Xác minh chữ ký webhook

MoonPay gửi event lifecycle đến endpoint của bạn: transaction_created, transaction_updated, transaction_failed... Mỗi request có header Moonpay-Signature-V2 cần xác minh HMAC:

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"),
  );
}

Luôn từ chối request cũ hơn 5 phút (ngăn replay attack). Tham khảo webhook docs.

Quy trình bán (off-ramp)

Tương tự mua: tạo URL ký trỏ đến sell.moonpay.com, user chọn coin và số lượng, MoonPay tạo địa chỉ nạp, user gửi crypto, MoonPay giải ngân tiền pháp định về ngân hà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()}`;
// Ký giống như URL mua

refundWalletAddress rất quan trọng: nếu user gửi sai coin hoặc fail KYC, MoonPay hoàn lại về đây.

Thanh toán NFT

Cho phép user mua NFT bằng thẻ. Đăng ký listing với MoonPay hoặc dùng marketplace đã tích hợp, tạo URL gồm contractAddress, tokenId, listingId. MoonPay xử lý toàn bộ chuyển đổi và chuyển khoản on-chain.

Lỗi thường gặp & giới hạn tốc độ

Một số lỗi phổ biến:

400 invalid_signature: HMAC của bạn không đúng. Thường do khác biệt encode query string. Ký chính xác chuỗi query đã gửi.
403 geo_restricted: IP user ở quốc gia không hỗ trợ. Kiểm tra field isAllowed trên currency trước khi hiển thị.
422 transaction_limit_exceeded: User vượt hạn mức ngày/tuần/tháng. Thẻ thường $2,000/ngày, $10,000/tháng đến khi KYC nâng cao.
429 rate_limited: Khoảng 100 request/phút mỗi API key ở endpoint public. Nên cache danh sách tiền tệ/quote.

Luôn tin tưởng webhook, không phải trạng thái UI. Dù user đóng tab, ví vẫn sẽ được nạp nếu event webhook trả về status: completed.

Nếu cần hỗ trợ đa ví, xem thêm MetaMask API và API ví crypto tốt nhất. Về KYC, tham khảo API KYC tốt nhất.

Giá của MoonPay

Mua bằng thẻ: 3,5%-4,5% (tối thiểu $3.99).
Chuyển khoản ngân hàng (ACH, SEPA, Open Banking): 1%-1,9% (rẻ hơn cho giao dịch lớn).
Phí mạng: chuyển thẳng theo chi phí, thay đổi theo chain.
Bán (off-ramp): cấu trúc tương tự, phí tùy kênh thanh toán.

Doanh thu chia sẻ với đối tác sẽ thương lượng riêng nếu khối lượng lớn. Tích hợp lớn có thể nhận giá đặc biệt và hỗ trợ compliance chuyên biệt.

Kiểm thử MoonPay với Apidog

URL ký và webhook là nơi dễ lỗi nhất khi tích hợp MoonPay. Dùng Apidog để nhập OpenAPI spec của MoonPay, lưu khóa sandbox dưới dạng biến môi trường, chạy chu trình quote-mua, kiểm tra trạng thái giao dịch, và phát lại webhook mà không cần code backend.

Quy trình thực tế:

Tạo 2 môi trường Apidog: sandbox và production
Viết script ký HMAC như pre-request hook bằng Node crypto
Lưu transaction ID mẫu làm biến để chuyển thẳng từ createTransaction sang getTransactionStatus
Khi nhận webhook thật, copy raw body vào mock server của Apidog, replay vào endpoint local cho tới khi xác minh thành công

Tải xuống Apidog để có môi trường ký, mock server và chuyển đổi môi trường nhanh chóng.

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 cần. MoonPay lo toàn bộ KYC phía server; app của bạn không xử lý tài liệu ID. Nếu cần xác minh trước cho phần khác, xem API KYC tốt nhất.

Có thể dùng MoonPay không cần widget họ không?

Có, dùng API trực tiếp hoặc Ramps SDK không UI, nhưng cần review tuân thủ bổ sung. Đa số team nên bắt đầu bằng widget, chuyển sang API khi đạt khối lượng lớn.

MoonPay hỗ trợ những quốc gia nào?

Hơn 160 quốc gia cho mua, khoảng 50 cho bán. Tiền tệ và phương thức thanh toán thay đổi theo vùng. Endpoint currencies trả về matrix hiện hành.

Thời gian hoàn thành giao dịch?

Mua bằng thẻ: tiền crypto vào ví trong ~5 phút nếu thuận lợi.
Chuyển khoản ngân hàng: 1-3 ngày làm việc để nhận tiền pháp định, sau đó mới gửi crypto.
Bán: tiền pháp định về tài khoản user sau 1-3 ngày từ lúc xác nhận on-chain.

Webhook gửi thất bại thì sao?

MoonPay tự retry với backoff trong 24h. Bạn nên trả về mã 2xx chỉ sau khi lưu sự kiện và loại trùng lặp theo id (retry có thể tạo bản sao).

Môi trường sandbox giống production không?

Gần giống nhưng vẫn khác biệt: sandbox nới lỏng geo-limit, bỏ qua KYC với giấy tờ test, trạng thái giao dịch điều khiển qua dashboard. Luôn kiểm thử thực tế sau khi nhận khóa production.

DEV Community