วิธีใช้งาน MoonPay API: เชื่อมต่อระบบซื้อขายคริปโตด้วยเงินบาท

เดิมทีการแปลงเงินเฟียตเป็นคริปโต (fiat-to-crypto on-ramp) เคยหมายถึงการใช้เวลาหลายสัปดาห์ไปกับเอกสารด้านการปฏิบัติตามข้อกำหนด ความสัมพันธ์กับธนาคาร และผู้ให้บริการ KYC ที่ต้องเชื่อมโยงกันอย่างยุ่งยาก แต่ MoonPay API ได้รวมระบบเหล่านั้นให้เป็นหนึ่งเดียว: คุณเพียงแค่สร้าง URL ที่ลงนามแล้ว ใส่ widget ลงในแอปของคุณ และ MoonPay จะจัดการการประมวลผลบัตร การโอนเงินผ่านธนาคาร การยืนยันตัวตน และการชำระเงินเข้ากระเป๋าเงินของผู้ใช้

คู่มือนี้จะอธิบายวิธีการใช้ MoonPay API แบบครบวงจร ตั้งแต่การตั้งค่าบัญชีพันธมิตร การใช้งาน widget เทียบกับ API โดยตรง การสร้าง URL ที่ลงนาม การยืนยัน webhook กระบวนการขาย (sell flow) การชำระเงิน NFT และข้อจำกัดด้านการปฏิบัติตามข้อกำหนดที่คุณต้องวางแผนไว้ ทุกคำขอที่อยู่ด้านล่างนี้ได้รับการทดสอบกับสภาพแวดล้อม Sandbox และจัดทำเป็นเอกสารใน พอร์ทัลสำหรับนักพัฒนา MoonPay อย่างเป็นทางการ คุณสามารถเรียกใช้คำสั่งเดียวกันนี้ภายใน Apidog ในขณะที่คุณพัฒนาได้

หากคุณยังคงเปรียบเทียบผู้ให้บริการ ลองเริ่มต้นด้วยการรวบรวมข้อมูลเกี่ยวกับ API ที่ดีที่สุดสำหรับการแปลงเงินเฟียตเป็นคริปโต (on-ramp) และคริปโตเป็นเงินเฟียต (off-ramp) เพื่อดูว่า MoonPay แตกต่างจาก Transak, Ramp และ Stripe Crypto อย่างไร นักพัฒนาที่กำลังประเมินโครงสร้างพื้นฐานแบบ Custodial ควรอ่าน วิธีใช้ Circle API เพื่อทำความเข้าใจเกี่ยวกับฝั่ง USDC ของระบบ

สรุปโดยย่อ

• MoonPay เป็นบริการแปลงเงินเฟียตเป็นคริปโต (on-ramp) และคริปโตเป็นเงินเฟียต (off-ramp) ที่ได้รับการกำกับดูแล ซึ่งถูกใช้โดยกระเป๋าเงินดิจิทัล, ตลาด NFT และกระดานแลกเปลี่ยนในกว่า 160 ประเทศ
• มีสองช่องทางการเชื่อมต่อ: Ramps SDK/widget (เร็วที่สุด, UI โฮสต์โดย MoonPay) หรือ Direct REST API (ควบคุมได้อย่างสมบูรณ์, คุณสร้าง UI เอง)
• URL ของ widget ทั้งหมดจะต้องได้รับการลงนามด้วย HMAC-SHA256 โดยใช้คีย์ลับของคุณ; URL ที่ไม่ลงนามจะถูกปฏิเสธในการใช้งานจริง
• MoonPay จัดการ KYC, การประมวลผลบัตร และระบบธนาคารทางฝั่งเซิร์ฟเวอร์; คุณจะได้รับสถานะผ่าน webhooks ที่ลงนามด้วยรูปแบบ HMAC เดียวกัน
• ราคาประกอบด้วยค่าธรรมเนียมการประมวลผล (บัตร 3.5%-4.5%, การโอนเงินผ่านธนาคารถูกกว่า) บวกกับค่าธรรมเนียมเครือข่ายพื้นฐาน ซึ่งจะแสดงให้ผู้ใช้ทราบอย่างโปร่งใส
• กระบวนการ Off-ramp (ขาย) จะคล้ายกับกระบวนการซื้อ: URL ที่ลงนาม, ผู้ใช้ส่งคริปโตไปยังที่อยู่ฝาก, MoonPay จะโอนเงินเฟียตเข้าบัญชีธนาคารของผู้ใช้

MoonPay คืออะไร?

MoonPay เป็นบริษัทผู้ให้บริการชำระเงินที่ได้รับใบอนุญาต ซึ่งช่วยให้ผู้ใช้ของคุณสามารถซื้อและขายคริปโตด้วยบัตร โอนเงินผ่านธนาคาร Apple Pay, Google Pay, SEPA และระบบการชำระเงินในท้องถิ่น MoonPay ดำเนินงานในฐานะธุรกิจบริการทางการเงินในสหรัฐอเมริกา มีใบอนุญาต EMI ในสหภาพยุโรป และจดทะเบียนในสหราชอาณาจักร แคนาดา และออสเตรเลีย ผลลัพธ์ในทางปฏิบัติคือ: คุณไม่จำเป็นต้องเป็นผู้โอนเงินเพื่อที่จะรับบัตรและส่ง ETH ไปยังกระเป๋าเงินของผู้ใช้

แพลตฟอร์มนี้รองรับสกุลเงินดิจิทัลกว่า 110 สกุล ในกว่า 40 เครือข่าย (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) รวมถึงการชำระเงิน NFT MoonPay เป็นบริการ on-ramp ที่ฝังอยู่ใน MetaMask, Trust Wallet และ OpenSea

การยืนยันตัวตนและการตั้งค่า

สมัครบัญชีพันธมิตรได้ที่ moonpay.com/business หลังจากได้รับการอนุมัติ คุณจะได้รับคีย์สองชุด: สำหรับ Sandbox และ Production แต่ละชุดประกอบด้วย publishable key (pk_test_...) และ secret key (sk_test_...) ให้ปฏิบัติต่อ secret key เหมือนรหัสผ่านฐานข้อมูล; มันใช้สำหรับลงนามทุก URL และยืนยันทุก webhook

ตั้งค่าในสภาพแวดล้อมของคุณ:

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

Sandbox มี endpoint เดียวกันกับ Production แต่จะส่งคืนธุรกรรมทดสอบที่คุณสามารถเปลี่ยนสถานะได้โดยใช้แดชบอร์ด ใช้สำหรับทดสอบกระบวนการทั้งหมด จากนั้นเปลี่ยนไปใช้คีย์ Production เมื่อการตรวจสอบการปฏิบัติตามข้อกำหนดกับ MoonPay เสร็จสมบูรณ์

เอนด์พอยต์หลัก

MoonPay มีกลุ่มเอนด์พอยต์ที่คุณจะใช้บ่อยที่สุดได้แก่: สกุลเงิน, ราคา, ธุรกรรม และ webhooks เอกสารอ้างอิง REST ฉบับเต็ม แสดงรายการทรัพยากรทั้งหมด

รายการสกุลเงินที่รองรับ

ก่อนที่คุณจะสร้างตัวเลือก ให้ดึงรายการสด ความพร้อมใช้งานจะแตกต่างกันไปตามประเทศ ดังนั้นคุณควรกรองตาม IP ของผู้ใช้หรือตำแหน่งที่ระบุ

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

การตอบกลับจะส่งคืนอาร์เรย์ที่มี code, name, type (crypto หรือ fiat), minBuyAmount, maxBuyAmount และข้อมูลเมตาต่อเครือข่ายสำหรับโทเค็นที่อยู่บนหลายเชน

รับใบเสนอราคาแบบเรียลไทม์

ใบเสนอราคาจะแจ้งให้ผู้ใช้ทราบว่าพวกเขาจะได้รับคริปโตจำนวนเท่าใดอย่างแม่นยำก่อนที่จะยืนยัน มีค่าธรรมเนียมรวมอยู่ด้วย

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"

คุณจะได้รับ quoteCurrencyAmount, feeAmount, networkFeeAmount และ totalAmount กลับมา แคชใบเสนอราคาไว้สักสองสามวินาทีในขณะที่ผู้ใช้คลิกผ่าน; MoonPay จะให้เกียรติใบเสนอราคานั้นประมาณ 60 วินาที

สร้าง URL ของ widget ซื้อที่ลงนามแล้ว (Node)

widget ซื้อเป็นวิธีที่เร็วที่สุดในการเชื่อมต่อระบบที่ใช้งานได้ คุณสร้าง URL ด้วยพารามิเตอร์แบบสอบถาม ลงนามด้วยคีย์ลับของคุณ และเลือกที่จะเปลี่ยนเส้นทางผู้ใช้หรือโหลดลงใน iframe นี่คือเวอร์ชัน 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)}`;
}

ส่ง URL นี้ให้ผู้ใช้ ลายเซ็นจะผูกพารามิเตอร์เข้ากับบัญชีของคุณ เพื่อให้ไคลเอนต์ที่เป็นอันตรายไม่สามารถสลับ walletAddress หรือเปลี่ยนจำนวนเงินโดยไม่ทำให้ลายเซ็นไม่ถูกต้อง คู่มือเริ่มต้นใช้งาน widget ซื้อ มีเอกสารพารามิเตอร์ที่รองรับทั้งหมด

ยืนยันลายเซ็น webhook

MoonPay ส่งเหตุการณ์วงจรชีวิตไปยังเอนด์พอยต์ของคุณ: transaction_created, transaction_updated, transaction_failed และรูปแบบการขาย/NFT ทุกคำขอจะรวมเฮดเดอร์ Moonpay-Signature-V2 ซึ่งคุณต้องตรวจสอบก่อนที่จะเชื่อถือเพย์โหลด

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

ปฏิเสธคำขอที่เก่ากว่าห้านาทีเพื่อหยุดการโจมตีแบบ replay เอกสารอ้างอิง webhook แสดงรายการประเภทเหตุการณ์และรูปร่างเพย์โหลดทั้งหมด

กระบวนการขาย (off-ramp)

กระบวนการขายจะคล้ายกับกระบวนการซื้อ คุณสร้าง URL ที่ลงนามแล้วซึ่งชี้ไปยัง sell.moonpay.com ผู้ใช้เลือกคริปโตและจำนวนเงิน MoonPay จะสร้างที่อยู่สำหรับฝากเงิน และผู้ใช้จะส่งเงินจากกระเป๋าเงินของตน เมื่อธุรกรรมได้รับการยืนยันบนเชน MoonPay จะโอนเงินเฟียตไปยังบัญชีธนาคารที่เชื่อมโยงของผู้ใช้

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()}`;
// ลงนามด้วยวิธีเดียวกับ URL สำหรับการซื้อ

refundWalletAddress มีความสำคัญ: หากผู้ใช้ส่งสินทรัพย์ผิดประเภท หรือธุรกรรม KYC ล้มเหลว MoonPay จะส่งเงินคืนไปยังที่อยู่นั้น

การชำระเงิน NFT

การชำระเงิน NFT ช่วยให้ผู้ใช้สามารถซื้อ NFT ที่ลงรายการไว้ด้วยบัตร คุณลงทะเบียนรายการกับ MoonPay (หรือใช้การเชื่อมต่อตลาดที่รองรับ) จากนั้นสร้าง URL ที่ลงนามพร้อมกับ contractAddress, tokenId และ listingId MoonPay จัดการส่วนที่เป็นเงินเฟียตและการโอนบนเชนในกระบวนการเดียว ซึ่งช่วยลดอัตราการละทิ้งการซื้อในยอดขายหลักที่มีมูลค่าสูงได้อย่างมาก

ข้อผิดพลาดที่พบบ่อยและข้อจำกัดการเรียกใช้ (Rate Limits)

ปัญหาการเชื่อมต่อส่วนใหญ่มีดังต่อไปนี้:

• 400 invalid_signature หมายความว่าอินพุต HMAC ของคุณไม่ตรงกับของเซิร์ฟเวอร์ สาเหตุที่พบบ่อยที่สุดคือความแตกต่างในการเข้ารหัส URL ระหว่างไคลเอนต์ของคุณกับผู้ลงนาม ลงนามสตริงคำขอที่คุณส่งไปอย่างแม่นยำ
• 403 geo_restricted แสดงว่า IP ของผู้ใช้อยู่ในประเทศที่ MoonPay ไม่ได้ให้บริการสำหรับสกุลเงินนั้น ตรวจสอบฟิลด์ isAllowed ในออบเจกต์สกุลเงินก่อนที่จะแสดงผล
• 422 transaction_limit_exceeded หมายความว่าผู้ใช้ถึงขีดจำกัดรายวัน รายสัปดาห์ หรือรายเดือน ขีดจำกัดของบัตรโดยทั่วไปคือ $2,000/วัน และ $10,000/เดือน จนกว่าผู้ใช้จะดำเนินการ KYC ขั้นสูง
• 429 rate_limited จะถูกเรียกใช้เมื่อมีคำขอประมาณ 100 ครั้งต่อนาทีต่อ API key บนเอนด์พอยต์สาธารณะ แคชรายการสกุลเงินและใบเสนอราคาอย่างจริงจัง

สำหรับสถานะ ให้เชื่อถือ webhook ไม่ใช่เบราว์เซอร์ของผู้ใช้ ผู้ใช้ที่ปิดแท็บก่อนการเปลี่ยนเส้นทาง ก็ยังคงมีกระเป๋าเงินที่มีเงินอยู่เมื่อเหตุการณ์ transaction_updated ถูกเรียกใช้พร้อมกับ status: completed

หากคุณกำลังสร้างการรองรับกระเป๋าเงินหลายประเภท คู่มือของเราเกี่ยวกับ วิธีใช้ MetaMask API และ API กระเป๋าเงินคริปโตที่ดีที่สุด จะเข้ากันได้ดีกับบทความนี้ สำหรับด้านการระบุตัวตนของการปฏิบัติตามข้อกำหนด โปรดดูการรวบรวมข้อมูล API KYC ที่ดีที่สุด ของเรา

ราคาของ MoonPay

MoonPay คิดค่าธรรมเนียมการประมวลผลบวกกับค่าธรรมเนียมเครือข่าย ซึ่งทั้งสองอย่างจะแสดงให้ผู้ใช้เห็นภายใน widget:

• การซื้อด้วยบัตร: 3.5%-4.5% ของจำนวนเงินเฟียต โดยมีขั้นต่ำ $3.99
• การโอนเงินผ่านธนาคาร (ACH, SEPA, Open Banking): 1%-1.9% ซึ่งถูกกว่ามากสำหรับการทำธุรกรรมขนาดใหญ่
• ค่าธรรมเนียมเครือข่าย: ส่งผ่านตามต้นทุน แตกต่างกันไปตามเชนและปริมาณการใช้งาน
• กระบวนการขาย: โครงสร้างคล้ายกัน โดยมีค่าธรรมเนียมการจ่ายเงินขึ้นอยู่กับช่องทางการปลายทาง

ส่วนแบ่งรายได้สำหรับพันธมิตรจะถูกเจรจาแยกต่างหากเมื่อมีปริมาณการใช้งานเพิ่มขึ้น การเชื่อมต่อที่มีปริมาณการใช้งานสูงมักจะได้รับราคาพิเศษพร้อมกับผู้ติดต่อด้านการปฏิบัติตามข้อกำหนดโดยเฉพาะ

การทดสอบ MoonPay ด้วย Apidog

URL ที่ลงนามและ HMAC webhooks เป็นสองจุดที่การเชื่อมต่อ MoonPay ส่วนใหญ่มีปัญหา และทั้งสองส่วนสามารถแก้ไขข้อผิดพลาดได้เร็วขึ้นในไคลเอนต์ API ที่เหมาะสมมากกว่าในโค้ดแอปพลิเคชัน Apidog ช่วยให้คุณสามารถนำเข้า MoonPay OpenAPI spec, จัดเก็บ sandbox keys ของคุณเป็นตัวแปรสภาพแวดล้อม และเรียกใช้กระบวนการซื้อ-ใบเสนอราคา, สถานะธุรกรรม และการเล่นซ้ำ webhook ได้อย่างเต็มรูปแบบโดยไม่ต้องแตะต้อง backend ของคุณ

เวิร์กโฟลว์ที่ใช้งานได้จริง: สร้างสภาพแวดล้อม Apidog สำหรับ sandbox และอีกอันสำหรับ production, สคริปต์การสร้างลายเซ็นเป็น pre-request hook โดยใช้โค้ด Node crypto snippet ด้านบน, และบันทึก ID ธุรกรรมตัวอย่างเป็นตัวแปร เพื่อให้คุณสามารถข้ามจาก createTransaction ไปยัง getTransactionStatus ได้ทันที เมื่อ webhook มาถึงใน Production ให้คัดลอก raw body ไปยัง mock server ของ Apidog และเล่นซ้ำกับเอนด์พอยต์ในเครื่องของคุณจนกว่าตัวตรวจสอบของคุณจะผ่าน ดาวน์โหลด Apidog เพื่อรับ signing hooks, mock server และ environment switcher ไว้ในที่เดียว

คำถามที่พบบ่อย

• ฉันจำเป็นต้องมีผู้ให้บริการ KYC ของตนเองนอกเหนือจาก MoonPay หรือไม่?ไม่ MoonPay ดำเนินการยืนยันตัวตนทางฝั่งเซิร์ฟเวอร์; แอปของคุณจะไม่เห็นเอกสารประจำตัว หากคุณต้องการดำเนินการยืนยันล่วงหน้าสำหรับส่วนอื่นๆ ของผลิตภัณฑ์ โปรดดูการเปรียบเทียบ API KYC ที่ดีที่สุด ของเรา
• ฉันสามารถใช้ MoonPay โดยไม่แสดง widget ที่มีแบรนด์ของพวกเขาได้หรือไม่?ได้ โดยผ่าน Direct API หรือ headless Ramps SDK แต่คุณจะต้องมีการตรวจสอบการปฏิบัติตามข้อกำหนดเพิ่มเติม เนื่องจากกระบวนการที่มีแบรนด์จะครอบคลุมการเปิดเผยข้อมูลที่จำเป็นหลายอย่างโดยอัตโนมัติ ทีมส่วนใหญ่จะปล่อย widget ออกมาก่อน และจะย้ายไปใช้เมื่อปริมาณการใช้งานถึงระดับที่เหมาะสมกับการตรวจสอบ
• MoonPay รองรับประเทศใดบ้าง?กว่า 160 ประเทศสำหรับการซื้อ และกลุ่มประเทศที่เล็กลง (ประมาณ 50 ประเทศ) สำหรับการขาย โดยมีความพร้อมใช้งานของสกุลเงินและวิธีการชำระเงินที่แตกต่างกันไปตามภูมิภาค เอนด์พอยต์สกุลเงินจะส่งคืนข้อมูลปัจจุบันตามตำแหน่งของผู้ใช้
• การทำธุรกรรมใช้เวลานานเท่าใด?การซื้อด้วยบัตรจะเข้าสู่กระเป๋าเงินของผู้ใช้ภายในห้านาทีในกรณีปกติ การโอนเงินผ่านธนาคารใช้เวลา 1-3 วันทำการสำหรับการเคลียร์เงินเฟียตก่อนที่จะปล่อยคริปโต ธุรกรรมการขายจะโอนเงินเฟียตเข้าธนาคารของผู้ใช้ภายใน 1-3 วันหลังจากได้รับการยืนยันบนเชน
• จะเกิดอะไรขึ้นหากการส่ง webhook ล้มเหลว?MoonPay จะพยายามส่งซ้ำด้วย exponential backoff เป็นเวลาสูงสุด 24 ชั่วโมง คุณควรส่งคืนการตอบกลับ 2xx หลังจากที่คุณได้บันทึกเหตุการณ์แล้วเท่านั้น และทำการ dedupe ตาม id เนื่องจากความพยายามส่งซ้ำอาจทำให้เกิดรายการซ้ำได้
• Sandbox เหมือนกับ Production หรือไม่?ใกล้เคียง แต่ไม่เหมือนกันทุกประการ ข้อจำกัดทางภูมิศาสตร์จะผ่อนคลาย, KYC จะถูกข้ามด้วยเอกสารทดสอบ และธุรกรรมจะเปลี่ยนสถานะตามการควบคุมในแดชบอร์ด ควรทำการทดสอบ smoke test สุดท้ายใน Production เสมอหลังจากออกคีย์แล้ว