Walse

Posted on Apr 23 • Originally published at apidog.com

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

Dulunya, integrasi fiat-ke-kripto (on-ramp) membutuhkan proses rumit: dokumen kepatuhan, koordinasi perbankan, dan vendor KYC terpisah. Kini, MoonPay API menyederhanakan semuanya jadi satu integrasi: Anda cukup membuat URL bertanda tangan, embed widget MoonPay ke aplikasi Anda, dan MoonPay mengurus proses pembayaran kartu, transfer bank, KYC, serta pengiriman dana ke dompet pengguna.

Coba Apidog hari ini

Panduan ini membahas langkah implementasi MoonPay API: mulai dari pembuatan akun mitra, perbedaan widget vs. API langsung, cara membangun URL bertanda tangan, verifikasi webhook, alur penjualan/off-ramp, pembayaran NFT, dan batas kepatuhan yang wajib diperhatikan. Semua request berikut sudah diuji di sandbox dan terdokumentasi di portal developer resmi MoonPay. Anda bisa menjalankan request yang sama di Apidog saat proses development.

Jika Anda masih membandingkan layanan, cek ringkasan API on-ramp dan off-ramp fiat terbaik untuk melihat perbandingan MoonPay dengan Transak, Ramp, dan Stripe Crypto. Pengembang yang ingin evaluasi infrastruktur kustodial bisa pelajari cara menggunakan Circle API untuk aspek USDC.

Intinya

MoonPay adalah layanan on-ramp dan off-ramp fiat-kripto teregulasi, digunakan oleh wallet, marketplace NFT, dan exchange di 160+ negara.
Dua opsi integrasi: SDK/widget Ramps (cepat, UI MoonPay) atau REST API langsung (full control, Anda yang membangun UI).
Semua URL widget wajib ditandatangani dengan HMAC-SHA256 menggunakan secret key Anda; URL tanpa signature akan ditolak di production.
KYC, proses kartu, dan transfer bank ditangani di server MoonPay; status diterima melalui webhook bertanda tangan (HMAC sama).
Harga: fee 3,5%-4,5% (kartu), lebih rendah untuk transfer bank, plus network fee, semuanya transparan ke user.
Off-ramp (jual kripto) mirip pembelian: URL bertanda tangan, user kirim kripto ke alamat deposit, MoonPay transfer fiat ke bank user.

Apa itu MoonPay?

MoonPay adalah payment gateway berlisensi yang memungkinkan user membeli/menjual kripto dengan kartu, transfer bank, Apple Pay, Google Pay, SEPA, dan jalur lokal. MoonPay punya lisensi MSB di AS, EMI di Eropa, dan registrasi di Inggris, Kanada, Australia. Artinya, Anda tak perlu jadi money transmitter untuk menerima pembayaran atau mengirim ETH ke dompet user.

Platform ini mendukung 110+ aset kripto di 40+ chain (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), serta pembayaran NFT. Digunakan di MetaMask, Trust Wallet, dan OpenSea.

Autentikasi dan Pengaturan

Buat akun mitra di moonpay.com/business. Setelah disetujui, Anda dapat dua set API key: sandbox dan production. Tiap set punya public key (pk_test_...) dan secret key (sk_test_...). Jaga secret key seperti password database; digunakan untuk sign URL dan validasi 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 sama dengan production, tapi hanya berisi transaksi test yang statusnya bisa Anda ubah lewat dashboard. Jalankan semua flow di sandbox, lalu switch ke production setelah audit compliance oleh MoonPay selesai.

Endpoint Inti

MoonPay menyediakan beberapa grup endpoint utama: currencies, quotes, transactions, dan webhook. Referensi REST lengkap mencakup seluruh resource.

Daftar Mata Uang yang Didukung

Untuk membuat currency selector, ambil list supported currencies. Ketersediaan tergantung negara; filter berdasarkan IP/lokasi user.

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

Output: array berisi code, name, type (crypto/fiat), minBuyAmount, maxBuyAmount, dan metadata jaringan untuk token multi-chain.

Dapatkan Penawaran Real-time

Quotes memberi user estimasi berapa kripto yang akan diterima, fee 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"

Hasil: quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount. Cache quote ini selama beberapa detik; MoonPay akan menghormati quote sekitar 60 detik.

Widget pembelian adalah cara tercepat integrasi. Bangun URL dengan query params, sign dengan secret, lalu redirect user/iframe. Contoh implementasi Node.js:

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)}`;
}

Kirim URL ini ke user. Signature mengikat param ke akun Anda, sehingga walletAddress/jumlah tidak bisa diubah malicious client. Dokumentasi widget buy menjelaskan semua param.

Verifikasi Tanda Tangan Webhook

MoonPay mengirim event ke endpoint Anda: transaction_created, transaction_updated, transaction_failed, termasuk jual/NFT. Tiap request punya header Moonpay-Signature-V2 yang wajib diverifikasi.

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 request lebih dari lima menit untuk mencegah replay attack. Referensi webhook memuat semua event dan payload.

Alur Penjualan (Off-ramp)

Jual kripto mirip pembelian. Buat URL bertanda tangan ke sell.moonpay.com, user pilih kripto/jumlah, MoonPay generate deposit address, user kirim dana. Setelah on-chain confirmed, MoonPay transfer fiat ke rekening bank user.

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()}`;
// signature sama seperti URL pembelian

refundWalletAddress penting: jika user kirim aset salah/gagal KYC, dana dikembalikan ke alamat ini.

Pembayaran NFT

User bisa beli NFT dengan kartu. Daftarkan listing ke MoonPay (atau via marketplace support), lalu buat URL bertanda tangan dengan contractAddress, tokenId, listingId. MoonPay handle pembayaran fiat dan transfer on-chain sekaligus, sangat cocok untuk penjualan NFT bernilai tinggi.

Kesalahan Umum & Rate Limit

400 invalid_signature: HMAC tidak cocok, biasanya karena perbedaan encoding URL. Sign query string persis sama dengan yang dikirim.
403 geo_restricted: User IP di negara yang tidak didukung. Periksa isAllowed pada objek currency sebelum display.
422 transaction_limit_exceeded: Batas transaksi user tercapai (harian/mingguan/bulanan). Limit kartu: $2.000/hari, $10.000/bulan sebelum KYC advance.
429 rate_limited: Limit 100 request/menit per API key di endpoint publik. Aggressively cache currency list & quote.

Untuk status, andalkan webhook, bukan browser user. Meskipun user menutup tab sebelum redirect, dompet tetap terisi setelah transaction_updated berstatus completed.

Butuh multi-wallet support? Lihat cara menggunakan MetaMask API dan API dompet kripto terbaik. Untuk KYC, cek API KYC terbaik.

Harga MoonPay

Fee MoonPay transparan di widget:

Kartu: 3,5%-4,5% dari jumlah fiat, min. $3,99.
Transfer bank (ACH, SEPA, Open Banking): 1%-1,9%, biasanya lebih murah untuk nominal besar.
Network fee: sesuai biaya chain, tergantung kemacetan.
Off-ramp: struktur sama, fee payout tergantung metode tujuan.

Pembagian revenue untuk mitra bisa dinegosiasikan setelah volume tinggi. Integrasi high-volume biasanya dapat harga khusus dan kontak compliance khusus.

Menguji MoonPay dengan Apidog

Signature URL & webhook HMAC adalah titik rawan error pada integrasi MoonPay. Debug proses ini lebih cepat di API client. Apidog bisa import OpenAPI MoonPay, simpan sandbox key sebagai environment variable, dan jalankan siklus buy-quote, transaction-status, hingga webhook replay tanpa backend langsung.

Praktis: buat environment sandbox dan production di Apidog, skrip tanda tangan HMAC di pre-request hook (pakai snippet Node di atas), simpan sample transaction ID sebagai variable untuk testing langsung dari createTransaction ke getTransactionStatus. Untuk webhook production, copy raw body ke mock server Apidog dan replay ke endpoint lokal sampai verifikasi Anda lolos. Unduh Apidog untuk fitur signing hook, mock server, dan environment switch.

FAQ

Apakah saya butuh vendor KYC terpisah di atas MoonPay? Tidak. MoonPay handle KYC di server side; app Anda tidak menerima dokumen ID. Jika perlu KYC tambahan, cek API KYC terbaik.

Bisa pakai MoonPay tanpa widget bermerek? Bisa, lewat API langsung atau SDK Ramps headless, tapi perlu compliance review tambahan. Sebagian besar tim mulai dari widget, migrasi ke API jika volume sudah cukup tinggi.

Negara mana saja yang didukung MoonPay? 160+ negara untuk pembelian; sekitar 50 negara untuk penjualan. Ketersediaan currency/method tergantung lokasi. Endpoint currency mengembalikan matrix per negara user.

Berapa lama transaksi selesai? Kartu: <5 menit. Transfer bank: 1-3 hari kerja untuk release kripto. Off-ramp: fiat ke bank user dalam 1-3 hari setelah on-chain confirmed.

Apa yang terjadi kalau webhook gagal dikirim? MoonPay retry dengan exponential backoff sampai 24 jam. Return 2xx response hanya setelah event diproses, deduplicate pakai id di payload karena retry bisa menduplikasi event.

Apakah sandbox identik dengan production? Hampir, tapi tidak sama. Sandbox: geo restriction longgar, KYC pakai dokumen test, transaksi bisa diubah status lewat dashboard. Selalu jalankan smoke test di production setelah API key production didapat.

DEV Community