Cara Menggunakan MoonPay API: Integrasi On-Ramp dan Off-Ramp Fiat

Dulunya, jalur fiat-ke-kripto (on-ramp) berarti berminggu-minggu berurusan dengan dokumen kepatuhan, hubungan perbankan, dan vendor KYC yang disatukan seadanya. MoonPay API meruntuhkan tumpukan itu menjadi satu integrasi: Anda membuat URL yang ditandatangani, menempatkan widget ke dalam aplikasi Anda, dan MoonPay menangani pemrosesan kartu, transfer bank, verifikasi identitas, dan pembayaran ke dompet pengguna.

Panduan ini akan menjelaskan cara menggunakan MoonPay API secara menyeluruh: pengaturan akun mitra, widget vs. API langsung, konstruksi URL yang ditandatangani, verifikasi webhook, alur penjualan, pembayaran NFT, dan batas kepatuhan yang perlu Anda pertimbangkan. Setiap permintaan di bawah ini telah diuji terhadap sandbox dan didokumentasikan di portal pengembang resmi MoonPay. Anda dapat menjalankan panggilan yang sama di dalam Apidog saat Anda membangun.

tombol

Jika Anda masih membandingkan penyedia, mulailah dengan ringkasan kami tentang API on-ramp dan off-ramp fiat terbaik untuk melihat posisi MoonPay dibandingkan Transak, Ramp, dan Stripe Crypto. Pengembang yang mengevaluasi infrastruktur kustodial juga harus membaca cara menggunakan Circle API untuk melihat sisi USDC dari tumpukan.

Intinya

MoonPay adalah on-ramp dan off-ramp fiat-ke-kripto yang teregulasi, digunakan oleh dompet, pasar NFT, dan bursa di 160+ negara.
Dua jalur integrasi: SDK/widget Ramps (tercepat, UI yang dihosting MoonPay) atau REST API langsung (kontrol penuh, Anda membangun UI).
Semua URL widget harus ditandatangani dengan HMAC-SHA256 menggunakan kunci rahasia Anda; URL yang tidak ditandatangani akan ditolak dalam produksi.
KYC, pemrosesan kartu, dan jalur bank ditangani di sisi server oleh MoonPay; Anda menerima status melalui webhook yang ditandatangani dengan pola HMAC yang sama.
Harga adalah biaya pemrosesan (3,5%-4,5% untuk kartu, lebih rendah untuk transfer bank) ditambah biaya jaringan dasar, yang disampaikan secara transparan kepada pengguna.
Off-ramp (penjualan) mencerminkan alur pembelian: URL yang ditandatangani, pengguna mengirim kripto ke alamat deposit, MoonPay menyelesaikan fiat ke bank pengguna.

Apa itu MoonPay?

MoonPay adalah perusahaan pembayaran berlisensi yang memungkinkan pengguna Anda membeli dan menjual kripto dengan kartu, transfer bank, Apple Pay, Google Pay, SEPA, dan jalur lokal. MoonPay beroperasi sebagai bisnis layanan uang di AS, memiliki lisensi EMI di Uni Eropa, dan memegang registrasi di Inggris, Kanada, dan Australia. Efek praktisnya: Anda tidak perlu menjadi pengirim uang untuk menerima kartu dan mengirim ETH ke dompet pengguna.

Platform ini mencakup 110+ mata uang kripto di lebih dari 40 jaringan (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), ditambah pembayaran NFT. Ini adalah on-ramp di dalam MetaMask, Trust Wallet, dan OpenSea.

Autentikasi dan pengaturan

Daftar akun mitra di moonpay.com/business. Setelah persetujuan, Anda akan mendapatkan dua set kunci: sandbox dan produksi. Setiap set memiliki kunci yang dapat dipublikasikan (pk_test_...) dan kunci rahasia (sk_test_...). Perlakukan kunci rahasia seperti kata sandi basis data; kunci ini menandatangani setiap URL dan memverifikasi setiap webhook.

Tetapkan dalam lingkungan Anda:

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

Sandbox memiliki endpoint yang sama dengan produksi tetapi mengembalikan transaksi uji yang dapat Anda alihkan antar status menggunakan dasbor. Gunakan ini untuk seluruh alur yang sukses, lalu beralih ke kunci produksi setelah tinjauan kepatuhan Anda dengan MoonPay selesai.

Endpoint inti

MoonPay mengekspos beberapa grup endpoint yang paling sering Anda gunakan: mata uang, penawaran, transaksi, dan webhook. Referensi REST lengkap mencantumkan setiap sumber daya.

Daftar mata uang yang didukung

Sebelum Anda membuat pemilih, ambil daftar langsungnya. Ketersediaan bervariasi berdasarkan negara, jadi Anda harus memfilter dengan IP pengguna atau lokasi yang dideklarasikan.

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

Respons mengembalikan array dengan code, name, type (crypto atau fiat), minBuyAmount, maxBuyAmount, dan metadata per jaringan untuk token yang berada di beberapa rantai.

Dapatkan penawaran real-time

Penawaran memberi tahu pengguna dengan tepat berapa banyak kripto yang akan mereka terima sebelum mereka berkomitmen. Biaya sudah termasuk.

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"

Anda akan mendapatkan kembali quoteCurrencyAmount, feeAmount, networkFeeAmount, dan totalAmount. Simpan penawaran tersebut dalam cache selama beberapa detik yang dibutuhkan pengguna untuk mengeklik; MoonPay akan menghormatinya selama kurang lebih 60 detik.

Widget pembelian adalah jalur tercepat menuju integrasi yang berfungsi. Anda membuat URL dengan parameter kueri, menandatanganinya dengan rahasia Anda, dan kemudian mengarahkan ulang pengguna atau memuatnya dalam iframe. Berikut adalah versi 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)}`;
}

Berikan URL ini kepada pengguna. Tanda tangan mengikat parameter ke akun Anda, sehingga klien berbahaya tidak dapat menukar walletAddress atau mengubah jumlah tanpa membatalkannya. Panduan cepat widget pembelian mendokumentasikan setiap parameter yang didukung.

Verifikasi tanda tangan webhook

MoonPay mengirimkan peristiwa siklus hidup ke endpoint Anda: transaction_created, transaction_updated, transaction_failed, dan varian jual/NFT. Setiap permintaan menyertakan header Moonpay-Signature-V2 yang harus Anda verifikasi sebelum mempercayai 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"),
  );
}

Tolak setiap permintaan yang lebih lama dari lima menit untuk menghentikan serangan pemutaran ulang. Referensi webhook mencantumkan setiap jenis acara dan bentuk payload.

Alur penjualan (off-ramp)

Alur penjualan mencerminkan pembelian. Anda membuat URL yang ditandatangani yang mengarah ke sell.moonpay.com, pengguna memilih kripto dan jumlah, MoonPay menghasilkan alamat deposit, dan pengguna mengirim dana dari dompet mereka. Setelah transaksi dikonfirmasi di rantai, MoonPay menyelesaikan fiat ke rekening bank pengguna yang terhubung.

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 penting: jika pengguna mengirim aset yang salah atau transaksi gagal KYC, MoonPay akan mengembalikan dana ke alamat tersebut.

Pembayaran NFT

Pembayaran NFT memungkinkan pengguna membeli NFT yang terdaftar dengan kartu. Anda mendaftarkan daftar tersebut dengan MoonPay (atau menggunakan integrasi pasar yang didukung), lalu membuat URL yang ditandatangani dengan contractAddress, tokenId, dan listingId. MoonPay menangani bagian fiat dan transfer on-chain dalam satu alur, yang secara dramatis mengurangi penurunan pada penjualan primer bernilai tinggi.

Kesalahan umum dan batas laju

Sebagian besar masalah integrasi masuk dalam daftar singkat:

400 invalid_signature berarti input HMAC Anda tidak cocok dengan server. Penyebab paling sering adalah perbedaan pengkodean URL antara klien Anda dan penanda tangan. Tandatangani string kueri yang persis sama dengan yang Anda kirim.
403 geo_restricted menandakan IP pengguna berada di negara yang tidak dilayani MoonPay untuk mata uang tersebut. Periksa bidang isAllowed pada objek mata uang sebelum menampilkannya.
422 transaction_limit_exceeded berarti pengguna telah mencapai batas harian, mingguan, atau bulanan. Batas kartu biasanya $2.000/hari dan $10.000/bulan hingga pengguna menyelesaikan KYC yang ditingkatkan.
429 rate_limited terpicu pada sekitar 100 permintaan per menit per kunci API pada endpoint publik. Cache daftar mata uang dan penawaran secara agresif.

Untuk status, percayai webhook, bukan peramban pengguna. Pengguna yang menutup tab sebelum pengalihan masih memiliki dompet yang didanai setelah peristiwa transaction_updated terpicu dengan status: completed.

Jika Anda membangun dukungan multi-dompet, panduan kami tentang cara menggunakan MetaMask API dan API dompet kripto terbaik sangat cocok dengan yang ini. Untuk sisi identitas kepatuhan, lihat ringkasan API KYC terbaik kami.

Harga MoonPay

MoonPay membebankan biaya pemrosesan ditambah biaya jaringan, keduanya ditampilkan kepada pengguna di dalam widget:

Pembelian kartu: 3,5%-4,5% dari jumlah fiat, dengan minimum $3,99.
Transfer bank (ACH, SEPA, Open Banking): 1%-1,9%, jauh lebih murah untuk tiket besar.
Biaya jaringan: diteruskan sesuai biaya, bervariasi berdasarkan rantai dan kemacetan.
Alur penjualan: struktur serupa, dengan biaya pembayaran tergantung pada jalur tujuan.

Pembagian pendapatan untuk mitra dinegosiasikan secara terpisah setelah volume meningkat. Integrasi volume tinggi biasanya mendapatkan harga khusus ditambah kontak kepatuhan khusus.

Menguji MoonPay dengan Apidog

URL yang ditandatangani dan webhook HMAC adalah dua tempat di mana sebagian besar integrasi MoonPay rusak, dan keduanya lebih cepat untuk di-debug di klien API yang tepat daripada di kode aplikasi. Apidog memungkinkan Anda mengimpor spesifikasi OpenAPI MoonPay, menyimpan kunci sandbox Anda sebagai variabel lingkungan, dan menjalankan siklus buy-quote, transaction-status, dan webhook-replay penuh tanpa menyentuh backend Anda.

Antarmuka Apidog yang menunjukkan permintaan API MoonPay

Alur kerja praktis: buat lingkungan Apidog untuk sandbox dan satu lagi untuk production, skripkan pembuatan tanda tangan sebagai hook pra-permintaan menggunakan cuplikan kripto Node di atas, dan simpan ID transaksi sampel sebagai variabel sehingga Anda dapat langsung melompat dari createTransaction ke getTransactionStatus. Ketika webhook tiba di produksi, salin badan mentah ke server mock Apidog dan putar ulang terhadap endpoint lokal Anda sampai verifier Anda lulus. Unduh Apidog untuk mendapatkan hook penandatanganan, server mock, dan pengalih lingkungan di satu tempat.

FAQ

Apakah saya memerlukan vendor KYC sendiri di atas MoonPay?Tidak. MoonPay menjalankan verifikasi identitas di sisi server; aplikasi Anda tidak pernah melihat dokumen ID. Jika Anda ingin melakukan verifikasi awal untuk bagian lain dari produk Anda, lihat perbandingan API KYC terbaik kami.

Bisakah saya menggunakan MoonPay tanpa menampilkan widget bermerek mereka?Ya, melalui API langsung atau SDK Ramps tanpa kepala, tetapi Anda memerlukan tinjauan kepatuhan tambahan karena alur bermerek secara otomatis mencakup banyak pengungkapan yang diperlukan. Sebagian besar tim mengirimkan widget terlebih dahulu dan bermigrasi setelah volume membenarkan tinjauan tersebut.

Negara mana saja yang didukung MoonPay?160+ negara untuk pembelian dan set yang lebih kecil (sekitar 50) untuk penjualan, dengan ketersediaan mata uang dan metode pembayaran bervariasi berdasarkan wilayah. Endpoint mata uang mengembalikan matriks saat ini per lokasi pengguna.

Berapa lama waktu yang dibutuhkan transaksi?Pembelian kartu diselesaikan ke dompet pengguna dalam waktu kurang dari lima menit dalam alur yang sukses. Transfer bank membutuhkan 1-3 hari kerja untuk penyelesaian fiat sebelum kripto dilepaskan. Transaksi penjualan menyelesaikan fiat ke bank pengguna dalam 1-3 hari setelah konfirmasi on-chain.

Apa yang terjadi jika pengiriman webhook gagal?MoonPay mencoba lagi dengan penundaan eksponensial hingga 24 jam. Anda harus mengembalikan respons 2xx hanya setelah Anda mempertahankan peristiwa tersebut, dan melakukan deduplikasi pada id karena percobaan ulang dapat menghasilkan duplikat.

Apakah sandbox setara dengan produksi?Dekat, tapi tidak identik. Pembatasan geografis dilonggarkan, KYC dilewati dengan dokumen uji, dan transaksi bergerak melalui status berdasarkan kontrol dasbor. Selalu jalankan uji asap produksi akhir setelah kunci dikeluarkan.