Fiat'tan kriptoya geçiş ("on-ramp") eskiden haftalarca süren uyumluluk evrakları, bankacılık ilişkileri ve koli bandıyla bir araya getirilmiş KYC satıcıları anlamına geliyordu. MoonPay API'si bu yığını tek bir entegrasyona dönüştürüyor: imzalı bir URL oluşturuyorsunuz, uygulamanıza bir widget yerleştiriyorsunuz ve MoonPay kart işlemlerini, banka transferlerini, kimlik doğrulamasını ve kullanıcının cüzdanına yapılan ödemeleri hallediyor.
Bu kılavuz, MoonPay API'sini baştan sona nasıl kullanacağınızı adım adım açıklıyor: iş ortağı hesabı kurulumu, widget ve doğrudan API karşılaştırması, imzalı URL oluşturma, webhook doğrulama, satış akışı, NFT ödemesi ve etrafında plan yapmanız gereken uyumluluk limitleri. Aşağıdaki her istek sandbox'a karşı test edildi ve resmi MoonPay geliştirici portalında belgelendi. Geliştirme yaparken Apidog içinde aynı çağrıları çalıştırabilirsiniz.
düğme
Hala sağlayıcıları karşılaştırıyorsanız, MoonPay'in Transak, Ramp ve Stripe Crypto'ya karşı nerede durduğunu görmek için en iyi fiat on-ramp ve off-ramp API'leri derlememize göz atın. Saklama altyapısını değerlendiren geliştiriciler, yığının USDC tarafına bir bakış açısı için Circle API'sini nasıl kullanacağınızı da okumalıdır.
TL;DR
- MoonPay, 160'tan fazla ülkede cüzdanlar, NFT pazar yerleri ve borsalar tarafından kullanılan, düzenlenmiş bir fiat'tan kriptoya "on-ramp" ve "off-ramp" platformudur.
- İki entegrasyon yolu: Ramps SDK/widget (en hızlı, MoonPay tarafından barındırılan kullanıcı arayüzü) veya doğrudan REST API (tam kontrol, kullanıcı arayüzünü siz oluşturursunuz).
- Tüm widget URL'leri gizli anahtarınız kullanılarak HMAC-SHA256 ile imzalanmalıdır; imzasız URL'ler üretimde reddedilir.
- KYC, kart işlemleri ve banka transferleri MoonPay tarafından sunucu tarafında yönetilir; durumu aynı HMAC deseniyle imzalanmış web kancaları (webhooks) aracılığıyla alırsınız.
- Fiyatlandırma, bir işlem ücreti (%3,5-%4,5 kart, banka transferi için daha düşük) artı temel ağ ücretinden oluşur ve kullanıcıya şeffaf bir şekilde yansıtılır.
- Off-ramp (satış) akışı, satın alma akışını yansıtır: imzalı URL, kullanıcı kriptoyu bir para yatırma adresine gönderir, MoonPay fiat'ı kullanıcının bankasına aktarır.
MoonPay Nedir?
MoonPay, kullanıcılarınızın kartlar, banka transferleri, Apple Pay, Google Pay, SEPA ve yerel ödeme yöntemleriyle kripto alıp satmasına olanak tanıyan lisanslı bir ödeme şirketidir. ABD'de para hizmetleri işletmesi olarak faaliyet göstermekte, AB'de bir EMI lisansına sahip olmakta ve Birleşik Krallık, Kanada ve Avustralya'da kayıtlara sahiptir. Pratik etkisi: kart kabul etmek ve bir kullanıcının cüzdanına ETH teslim etmek için bir para transferi kuruluşu olmanıza gerek kalmaz.
Platform, 40'tan fazla ağda (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) 110'dan fazla kripto para birimini ve ayrıca NFT ödeme seçeneğini kapsar. MetaMask, Trust Wallet ve OpenSea içinde bir "on-ramp" olarak hizmet verir.
Kimlik Doğrulama ve Kurulum
moonpay.com/business adresinden bir iş ortağı hesabı için kaydolun. Onaylandıktan sonra iki anahtar seti alırsınız: sandbox ve üretim. Her sette bir herkese açık anahtar (pk_test_...) ve bir gizli anahtar (sk_test_...) bulunur. Gizli anahtarı bir veritabanı şifresi gibi düşünün; her URL'yi imzalar ve her webhook'u doğrular.
Bunları ortamınızda 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, üretim ile aynı uç noktalara sahiptir ancak panoyu kullanarak durumlar arasında geçiş yapabileceğiniz test işlemleri döndürür. Tam "happy path" için bunu kullanın, ardından MoonPay ile uyumluluk incelemeniz tamamlandığında üretim anahtarlarına geçin.
Temel Uç Noktalar
MoonPay, en sık kullanacağınız birkaç uç nokta grubunu sunar: para birimleri, kotalar, işlemler ve web kancaları. Tam REST referansı her kaynağı listeler.
Desteklenen Para Birimlerini Listele
Bir seçici oluşturmadan önce, canlı listeyi çekin. Kullanılabilirlik ülkeye göre değişir, bu nedenle kullanıcının IP'si veya belirtilen konumu ile filtreleme yapmalısınız.
curl -X GET "https://api.moonpay.com/v3/currencies" \
-H "Authorization: Api-Key $MOONPAY_API_KEY"
Yanıt, code, name, type (kripto veya fiat), minBuyAmount, maxBuyAmount ve birden fazla zincirde bulunan token'lar için ağ başına meta verileri içeren bir dizi döndürür.
Gerçek Zamanlı Teklif Alın
Teklifler, kullanıcının işlemi onaylamadan önce tam olarak ne kadar kripto alacağını gösterir. Ücretler 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ıt olarak quoteCurrencyAmount, feeAmount, networkFeeAmount ve totalAmount alırsınız. Kullanıcının tıklaması için geçen birkaç saniye boyunca teklifi önbelleğe alın; MoonPay bunu yaklaşık 60 saniye boyunca geçerli tutar.
İmzalı Bir Satın Alma Widget URL'si Oluşturun (Node)
Satın alma widget'ı, çalışan bir entegrasyona giden en hızlı yoldur. Sorgu parametreleriyle bir URL oluşturur, gizli anahtarınızla imzalar ve kullanıcıyı yönlendirir veya bir iframe içinde yüklersiniz. İşte Node sürümü:
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, parametreleri hesabınıza bağlar, böylece kötü niyetli bir istemci walletAddress'i değiştiremez veya miktarı geçersiz kılmadan değiştiremez. Satın alma widget'ı hızlı başlangıç kılavuzu, desteklenen her parametreyi belgelemektedir.
Webhook İmzalarını Doğrulayın
MoonPay, uç noktanıza yaşam döngüsü olayları gönderir: transaction_created, transaction_updated, transaction_failed ve satış/NFT varyantları. Her istek, yükü güvenmeden önce doğrulamanız gereken bir Moonpay-Signature-V2 başlığı içerir.
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"),
);
}
Tekrar oynatma saldırılarını durdurmak için beş dakikadan eski tüm istekleri reddedin. Webhook referansı her olay türünü ve yük yapısını listeler.
Satış (off-ramp) akışı
Satış akışı, satın alma akışını yansıtır. sell.moonpay.com adresine işaret eden imzalı bir URL oluşturursunuz, kullanıcı bir kripto para ve miktar seçer, MoonPay bir para yatırma adresi oluşturur ve kullanıcı fonları cüzdanından gönderir. İşlem zincirde onaylandıktan sonra MoonPay, fiat'ı kullanıcının bağlantılı banka hesabına aktarı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()}`;
// sign the same way as the buy URL
```refundWalletAddress önemlidir: eğer kullanıcı yanlış varlık gönderirse veya işlem KYC'yi geçemezse, MoonPay fonları oraya iade eder.
NFT Ödeme
NFT ödeme, bir kullanıcının listelenmiş bir NFT'yi kartla satın almasına olanak tanır. Listelemeyi MoonPay'e kaydedersiniz (veya desteklenen bir pazar yeri entegrasyonu kullanırsınız), ardından contractAddress, tokenId ve listingId ile imzalı bir URL oluşturursunuz. MoonPay, fiat tarafını ve zincir üstü transferi tek bir akışta halleder, bu da yüksek değerli birincil satışlardaki düşüşü önemli ölçüde azaltır.
Sık Görülen Hatalar ve Oran Limitleri
Entegrasyon sorunlarının çoğu kısa bir listede toplanır:
400 invalid_signature, HMAC girdinizin sunucunun girdisiyle eşleşmediği anlamına gelir. En sık neden, istemciniz ile imzalayıcı arasındaki URL kodlama farklılıklarıdır. Gönderdiğiniz sorgu dizesini tam olarak imzalayın.403 geo_restricted, kullanıcının IP'sinin MoonPay'in o para birimi için hizmet vermediği bir ülkeye düştüğünü gösterir. Para birimi nesnesindekiisAllowedalanını render etmeden önce kontrol edin.422 transaction_limit_exceeded, kullanıcının günlük, haftalık veya aylık limitleri aştığı anlamına gelir. Kart limitleri genellikle kullanıcı gelişmiş KYC'yi tamamlayana kadar günlük 2.000 dolar ve aylık 10.000 dolardır.429 rate_limited, genel uç noktalarda API anahtarı başına dakikada yaklaşık 100 istekte tetiklenir. Para birimi listelerini ve kotaları agresif bir şekilde önbelleğe alın.
Durum için, kullanıcının tarayıcısına değil, web kancasına güvenin. Yönlendirmeden önce sekmeyi kapatan bir kullanıcının, status: completed ile transaction_updated olayı tetiklendiğinde yine de fonlanmış bir cüzdanı olur.
Çoklu cüzdan desteği oluşturuyorsanız, MetaMask API'sini nasıl kullanacağınız ve en iyi kripto cüzdanı API'leri hakkındaki kılavuzlarımız bu kılavuzla iyi gider. Uyumluluğun kimlik tarafı için, en iyi KYC API'leri derlememize bakın.
MoonPay Fiyatlandırması
MoonPay, widget içinde kullanıcıya gösterilen bir işlem ücreti artı ağ ücreti alır:
Kart satın alımları: Fiat miktarının %3,5-%4,5'i, minimum 3,99 dolar.Banka transferi (ACH, SEPA, Açık Bankacılık): %1-%1,9, büyük işlemler için çok daha ucuz.Ağ ücreti: maliyetine yansıtılır, zincire ve yoğunluğa göre değişir.Satış akışı: benzer yapıya sahiptir, ödeme ücretleri varış noktasına göre değişir.
İş ortakları için gelir paylaşımı, hacim arttığında ayrıca müzakere edilir. Yüksek hacimli entegrasyonlar genellikle özel fiyatlandırma ve özel bir uyumluluk iletişim kişisi alır.
Apidog ile MoonPay'i Test Etme
İmzalı URL'ler ve HMAC web kancaları, çoğu MoonPay entegrasyonunun bozulduğu iki yerdir ve her ikisi de uygulama kodundan ziyade uygun bir API istemcisinde hata ayıklamak için daha hızlıdır. Apidog, MoonPay OpenAPI spesifikasyonunu içe aktarmanıza, sandbox anahtarlarınızı ortam değişkenleri olarak saklamanıza ve arka ucunuza dokunmadan tam satın alma-teklif, işlem-durumu ve webhook-tekrar oynatma döngüsünü çalıştırmanıza olanak tanır.
Pratik bir iş akışı: sandbox için bir Apidog ortamı ve production için başka bir ortam oluşturun, yukarıdaki Node kripto kod parçacığını kullanarak imza oluşturmayı bir ön istek kancası olarak betikleyin ve örnek işlem ID'lerini değişken olarak kaydedin, böylece doğrudan createTransaction'dan getTransactionStatus'a geçebilirsiniz. Üretimde bir webhook geldiğinde, ham gövdeyi Apidog'un sahte sunucusuna kopyalayın ve doğrulayıcınız geçene kadar yerel uç noktanıza karşı tekrar oynatın. İmzalama kancalarını, sahte sunucuyu ve ortam değiştiriciyi tek bir yerde almak 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ürütür; uygulamanız hiçbir zaman bir kimlik belgesi görmez. Ürününüzün diğer kısımları için doğrulamayı önden yüklemek isterseniz, en iyi KYC API karşılaştırmamıza bakın.MoonPay'i markalı widget'ını göstermeden kullanabilir miyim? Evet, doğrudan API veya başsız Ramps SDK aracılığıyla, ancak ek bir uyumluluk incelemesine ihtiyacınız var çünkü markalı akış, gerekli ifşaların çoğunu otomatik olarak kapsar. Çoğu ekip önce widget'ı yayınlar ve hacim incelemeyi haklı çıkardığında geçiş yapar.MoonPay hangi ülkeleri destekliyor? Satın alma için 160'tan fazla ülke ve satış için daha küçük bir grup (yaklaşık 50), para birimi ve ödeme yöntemi kullanılabilirliği bölgeye göre değişir. Para birimleri uç noktası, kullanıcının konumuna göre mevcut matrisi döndürür.Bir işlem ne kadar sürer? Kart satın alımları, sorunsuz akışta kullanıcının cüzdanına beş dakikadan kısa sürede ulaşır. Banka transferleri, kripto serbest bırakılmadan önce fiat onayı için 1-3 iş günü sürer. Satış işlemleri, zincir üstü onaylardan sonra 1-3 gün içinde fiat'ı kullanıcının bankasına aktarır.Webhook teslimatı başarısız olursa ne olur? MoonPay, 24 saate kadar üstel geri çekilme (exponential backoff) ile yeniden dener. Yalnızca olayı kalıcı hale getirdikten sonra 2xx yanıtı döndürmelisiniz ve yeniden denemeler kopyalar oluşturabileceğindenidüzerinden tekilleştirme yapmalısınız.Sandbox üretimle eşdeğer mi? Yakın, ama aynı değil. Coğrafi kısıtlamalar gevşetilir, KYC test belgeleriyle atlanır ve işlemler pano kontrollerine göre durumlar arasında hareket eder. Anahtarlar düzenlendikten sonra her zaman son bir üretim "smoke test"i yapın.