DEV Community

Cover image for MoonPay API Kullanımı: Fiat On-Ramp ve Off-Ramp Entegrasyonu
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

MoonPay API Kullanımı: Fiat On-Ramp ve Off-Ramp Entegrasyonu

Fiat'tan kriptoya geçiş ("on-ramp") geleneksel olarak haftalar süren uyumluluk süreçleri, banka entegrasyonları ve KYC sağlayıcılarıyla uğraşmak anlamına geliyordu. MoonPay API'si bu süreci tek entegrasyonla sadeleştiriyor: imzalı bir URL oluşturun, widget'ı uygulamanıza entegre edin ve MoonPay tüm kart işlemlerini, banka transferlerini, kimlik doğrulamasını ve cüzdan ödemelerini sizin yerinize yönetsin.

Apidog'u bugün deneyin

Bu rehberde MoonPay API'sini uçtan uca nasıl entegre edeceğinizi adım adım anlatıyoruz: iş ortağı hesabı açma, widget vs. doğrudan API farkları, imzalı URL üretimi, webhook doğrulama, satış akışı, NFT ödemeleri ve uyumluluk limitleri. Tüm örnekler MoonPay sandbox ortamında test edildi ve resmi MoonPay geliştirici portalında dokümante edildi. Geliştirme sırasında aynı çağrıları Apidog ile test edebilirsiniz.

Hala sağlayıcı karşılaştırması yapıyorsanız, MoonPay'in Transak, Ramp ve Stripe Crypto'ya karşı konumunu görmek için fiat on-ramp ve off-ramp API karşılaştırmamıza göz atabilirsiniz. Custody altyapısı arayanlar için, USDC işlemlerine özel Circle API entegrasyon rehberimizi inceleyin.

TL;DR

  • MoonPay, 160+ ülkede cüzdanlar, NFT pazarları ve borsalar tarafından kullanılan regüle bir fiat-kripto "on-ramp" ve "off-ramp" platformudur.
  • Entegrasyon iki şekilde yapılabilir: Ramps SDK/widget (en hızlı yol, barındırılan arayüz) veya doğrudan REST API (tam kontrol, kendi arayüzünüz).
  • Tüm widget URL'leri gizli anahtarınız ile HMAC-SHA256 ile imzalanmalı; imzasız çağrılar prod'da reddedilir.
  • KYC, kart ve banka işlemleri MoonPay sunucularında yönetilir; durumlar yine HMAC imzalı webhooks ile alınır.
  • Fiyatlandırma: İşlem ücreti (%3,5-%4,5 kart, banka transferinde daha düşük) + ağ ücreti. Kullanıcıya şeffaf yansıtılır.
  • Off-ramp (satış) akışı, satın alma akışına benzer: imzalı URL, kullanıcı kriptoyu adresine yollar, MoonPay fiat'ı bankaya gönderir.

MoonPay Nedir?

MoonPay, kullanıcılarınızın kart, banka transferi, Apple Pay, Google Pay, SEPA ve yerel ödeme yöntemleriyle kripto alıp satmasını sağlayan lisanslı bir ödeme şirketidir. ABD'de MSB, AB'de EMI lisansı ve İngiltere, Kanada, Avustralya'da kayıtlıdır. Böylece uygulamanızda kart kabul edip cüzdana ETH göndermek için ek bir lisans almanıza gerek kalmaz.

Platform, 40+ ağda (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) 110+ kripto para birimini ve NFT ödemelerini destekler. MetaMask, Trust Wallet ve OpenSea gibi büyük uygulamalarda "on-ramp" olarak kullanılmaktadır.

Kimlik Doğrulama ve Kurulum

moonpay.com/business adresinden iş ortağı hesabınız için başvurun. Onay sonrası iki anahtar setiniz olur: sandbox ve prod. Her sette public (pk_test_...) ve secret (sk_test_...) anahtar vardır. Secret anahtarınızı bir veritabanı şifresi gibi gizli tutun; tüm URL'leri imzalamak ve webhook doğrulamak için kullanılır.

Ortam değişkenlerini şöyle ayarlayın:

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

Sandbox ortamı prod ile aynı uç noktalara sahiptir ve test işlemleri döndürür. Geliştirme ve entegrasyon için sandbox'ı kullanın, uyumluluk onayından sonra prod anahtarlarına geçin.

Temel Uç Noktalar

MoonPay'de sık kullanacağınız bazı API uç noktaları:

  • Para birimleri
  • Kotalar
  • İşlemler
  • Webhooks

REST API referansı tüm kaynakları listeler.

Desteklenen Para Birimlerini Listele

Canlı para birimi listesini çekmek için aşağıdaki sorguyu kullanın. Kullanılabilirlik ülkeye göre değişir; IP veya kullanıcının belirttiği ülkeye göre filtre uygulayın.

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

Yanıt; code, name, type (crypto veya fiat), minBuyAmount, maxBuyAmount ve token'lar için ağ bazlı meta veriler içerir.

Gerçek Zamanlı Teklif Alın

Kullanıcıya net fiyat göstermek için teklif alın. Ücretler ve ağ maliyeti dahildir.

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"

Yanıtta quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount döner. Kullanıcı onaylamadan önce maksimum 60 saniye önbelleğe alınabilir.

İmzalı Satın Alma Widget URL'si Oluşturun (Node)

Satın alma widget'ı, hızlı ve risksiz bir entegrasyon sağlar. Parametrelerle URL oluşturun, gizli anahtarla imzalayın, kullanıcıya yönlendirin veya iframe'de gösterin.

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

Bu URL'yi kullanıcıya iletin. İmza, parametrelerin hesabınıza ait olduğunu kanıtlar; kötü niyetli istemciler parametreleri değiştiremez. Widget hızlı başlangıç kılavuzu tüm parametreleri açıklar.

Webhook İmzalarını Doğrulayın

MoonPay, işlem olaylarını uç noktanıza gönderir: transaction_created, transaction_updated, transaction_failed ve satış/NFT varyantları. Her isteğin Moonpay-Signature-V2 başlığını doğrulamanız gerekir.

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 saldırılarını engellemek için 5 dakikadan eski istekleri reddedin. Webhook referansı olay tipleri ve yük yapısını açıklar.

Satış (off-ramp) akışı

Satış akışı, satın alma ile aynıdır: sell.moonpay.com'a imzalı URL üretin, kullanıcı kripto ve miktarı seçsin, MoonPay bir para yatırma adresi oluşturur ve kullanıcı fonları gönderir. İşlem onaylanınca fiat banka hesabına aktarılır.

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()}`;
// Satın alma URL'sinde olduğu gibi imzalayın

refundWalletAddress parametresi zorunludur: yanlış varlık gönderilirse veya işlem KYC'yi geçmezse, iade buraya yapılır.

NFT Ödeme

Kullanıcıların listelenmiş bir NFT'yi kartla almasını sağlamak için; NFT'yi MoonPay'e kaydedin (veya desteklenen pazar yeri entegrasyonu kullanın), contractAddress, tokenId ve listingId ile imzalı bir URL oluşturun. MoonPay, fiat ve zincir üstü transferi aynı akışta tamamlar, yüksek değerli işlemlerde kullanıcı düşüşünü azaltır.

Sık Görülen Hatalar ve Oran Limitleri

  • 400 invalid_signature: HMAC imzanız sunucu ile eşleşmiyor. En yaygın sebep, istemci ile imzalayan kodun URL encode farkıdır. Sorgu dizesini birebir imzalayın.
  • 403 geo_restricted: Kullanıcının IP'si desteklenmeyen ülkede. Para birimi nesnesindeki isAllowed'a önceden bakın.
  • 422 transaction_limit_exceeded: Kullanıcı günlük, haftalık veya aylık limiti aştı. KYC tamamlanana kadar günlük $2000, aylık $10.000 limit geçerlidir.
  • 429 rate_limited: Genel uç noktalarda API anahtarı başına dakikada ~100 istek. Para birimi ve kota yanıtlarını önbelleğe alın.

İşlem durumu için webhooks'a güvenin, kullanıcı tarayıcıyı kapatsa bile transaction_updated ile status: completed geldiğinde fon cüzdana ulaşmıştır.

Çoklu cüzdan desteği ekliyorsanız, MetaMask API rehberi ve kripto cüzdan API karşılaştırması işinize yarar. Kimlik uyumluluğu için KYC API derlememiz faydalı olabilir.

MoonPay Fiyatlandırması

  • Kart işlemleri: Fiat tutarın %3,5-%4,5'i, minimum $3,99.
  • Banka transferi (ACH, SEPA, Açık Bankacılık): %1-%1,9, yüksek hacimde daha ucuz.
  • Ağ ücreti: Zincir ve yoğunluğa göre değişir, maliyetine yansır.
  • Satış akışı: Benzer ücret yapısı, ödeme ülkesine göre değişir.

İş ortakları için gelir paylaşımı ve yüksek hacimlerde özel fiyatlandırma müzakere edilebilir.

Apidog ile MoonPay'i Test Etme

İmzalı URL ve HMAC webhook'ları, entegrasyonların en sık takıldığı yerlerdir ve uygulama kodundan çok iyi bir API istemcisinde hata ayıklanır. Apidog, MoonPay OpenAPI dosyasını içe aktarmanıza, sandbox anahtarlarınızı ortam değişkeni olarak tanımlamanıza ve arka ucu değiştirmeden uçtan uca akışları test etmenize olanak tanır.

Pratik iş akışı: sandbox ve production için ayrı Apidog ortamları oluşturun, yukarıdaki Node.js HMAC imza kodunu bir ön istek hook'u olarak ekleyin, işlem ID'lerini değişken olarak kaydedin ve doğrudan createTransaction'dan getTransactionStatus'a geçin. Prod webhook geldiğinde, ham gövdeyi Apidog'un sahte sunucusuna gönderin ve doğrulayıcı kodunuzu test edin. Tüm imzalama scriptlerini, sahte sunucuyu ve ortam değiştiriciyi tek yerde yönetmek için Apidog'u indirin.

Sıkça Sorulan Sorular

  • MoonPay'e ek olarak kendi KYC sağlayıcıma ihtiyacım var mı? Hayır. MoonPay kimlik doğrulamasını sunucu tarafında yönetir; uygulamanız asla kimlik belgesi görmez. Ek doğrulama gereksinimleriniz için KYC API karşılaştırmamıza bakın.
  • MoonPay'i markalı widget olmadan kullanabilir miyim? Evet, doğrudan API veya başsız SDK ile mümkün; fakat ek uyumluluk incelemesi gerekebilir. Çoğu ekip önce widget ile başlar, hacim artınca API'ye geçer.
  • MoonPay hangi ülkeleri destekliyor? Satın alma için 160+ ülke, satış için yaklaşık 50 ülke. Para birimi ve ödeme yöntemi erişimi ülkeye göre değişir. Para birimi API'si kullanıcının konumuna göre mevcut seçenekleri döndürür.
  • Bir işlem ne kadar sürer? Kartla alım genellikle 5 dakikadan kısa sürede cüzdana ulaşır. Banka transferleri 1-3 iş günü sürer. Satış işlemleri de 1-3 gün içinde fiat banka hesabına aktarılır.
  • Webhook teslimatı başarısız olursa? MoonPay, teslim başarısızsa 24 saate kadar üstel geri çekilme ile tekrar dener. Olayları id bazında tekilleştirin, kopya tetiklemeleri önleyin.
  • Sandbox üretimle aynı mı? Çok yakın ama birebir değil: coğrafi kısıtlar gevşek, KYC test belgeleriyle atlanır, işlemler durumlar arasında pano ile hareket eder. Prod anahtarları ile mutlaka son bir "smoke test" yapın.

Top comments (0)