Tek API, tek barındırılan akış
CryptoPayIn, siparişinizi seçtiğiniz gösterim para biriminde fiyatlandırır; doğrulanmış fiat/USD ve kripto/USD anlık kurlarını kilitler; özel bir yatırma adresi tahsis eder ve ödemeyi kendi blok zinciri düğümleriyle izler. İç muhasebe, ücretler ve bakiyeler her zaman USD cinsindendir. Arka uç sisteminiz anında bir ödeme sayfası URL'si, ardından da imzalı yaşam döngüsü olaylarını alır.
Bu canlı bir API'dir. Sandbox öneki yoktur. Her başarılı oluşturma işlemi gerçek bir zincir üzerinde adres tahsis eder. Uçtan uca testler için desteklenen bir para biriminde küçük bir tutar kullanın ve gizli anahtarları sunucunuzda tutun.
Entegrasyon parçaları nasıl bir araya geliyor
Panel -> Geliştiriciler bölümünde bir kez gizli anahtar oluşturun.
Sipariş para birimini, tutarı ve seçilen varlığı POST edin.
Müşteriyi döndürülen barındırılan URL'ye yönlendirin.
HMAC'i doğrulayın ve siparişinizi idempotent biçimde güncelleyin.
İlk ödemenizi oluşturun
Üye işyeri panelinde bir API anahtarı oluşturun, gizli anahtarı bir ortam değişkeninde saklayın, ardından arka ucunuzdan bir ödeme oluşturun. Örnekte, bir token ağı seçmeden test edilebilmesi için ETH kullanılmıştır.
curl --request POST https://cryptopayin.com/v1/payments \
--header "Authorization: Bearer $CPI_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: order_1042" \
--data '{
"amount": 49.99,
"currency": "USD",
"asset": "ETH",
"order_ref": "order_1042",
"redirect_url": "https://shop.example/orders/1042/paid"
}'
const response = await fetch("https://cryptopayin.com/v1/payments", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.CPI_SECRET_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "order_1042"
},
body: JSON.stringify({
amount: 49.99, currency: "USD", asset: "ETH",
order_ref: "order_1042",
redirect_url: "https://shop.example/orders/1042/paid"
})
});
if (!response.ok) throw new Error(await response.text());
const payment = await response.json();
$payload = json_encode([
'amount' => 49.99, 'currency' => 'USD', 'asset' => 'ETH',
'order_ref' => 'order_1042',
'redirect_url' => 'https://shop.example/orders/1042/paid',
]);
$ch = curl_init('https://cryptopayin.com/v1/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CPI_SECRET_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order_1042',
],
]);
$payment = json_decode(curl_exec($ch), true, flags: JSON_THROW_ON_ERROR);
import os, requests
response = requests.post(
"https://cryptopayin.com/v1/payments",
headers={
"Authorization": f"Bearer {os.environ['CPI_SECRET_KEY']}",
"Idempotency-Key": "order_1042",
},
json={
"amount": 49.99, "currency": "USD", "asset": "ETH",
"order_ref": "order_1042",
"redirect_url": "https://shop.example/orders/1042/paid",
}, timeout=15,
)
response.raise_for_status()
payment = response.json()Yanıtı kullanın
Ödeme id değerini siparişinizin yanında kalıcı olarak saklayın, ardından müşteriyi checkout_url adresine yönlendirin. Kripto tutarını veya yatırma adresini kendiniz hesaplamayın.
{
"id": "P-9F27C1E4KD",
"object": "payment",
"status": "created",
"amount": 49.99,
"amount_decimal": "49.99",
"amount_minor": 4999,
"currency": "USD",
"currency_minor_units": 2,
"amount_usd": 49.99,
"amount_usd_cents": 4999,
"fx_rate_usd": "1.000000000000",
"fx_source": "fixed:USD",
"fx_observed_at": "2026-07-17T13:00:00+00:00",
"fx_discrepancy_bps": 0,
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0",
"deposit_address": "0x71b8c3d4700000000000000000000000000084e2",
"exchange_rate": "3600.00000000",
"exchange_rate_currency": "USD",
"exchange_rate_source": "median:cb,cg,cl",
"exchange_rate_source_count": 3,
"exchange_rate_observed_at": "2026-07-17T13:00:00+00:00",
"exchange_rate_discrepancy_bps": 12,
"confirmations": 0,
"confirmations_required": 12,
"order_ref": "order_1042",
"checkout_url": "https://cryptopayin.com/i/P-9F27C1E4KD",
"expires_at": "2026-07-17T13:30:00+00:00",
"created_at": "2026-07-17T13:00:00+00:00",
"completed_at": null
}Kimlik doğrulama
Her API isteği, gizli anahtarı bir HTTP Bearer başlığında kullanır. Gizli anahtarlar csk_live_ ile başlar. Eşlik eden cpk_live_ değeri, panelinize özel genel bir tanımlayıcıdır ve Bearer kimlik bilgisi olarak kullanılmamalıdır.
Authorization: Bearer csk_live_...Her uç noktaHam gizli anahtar yalnızca anahtar oluşturulduğunda döndürülür. CryptoPayIn bir parola özeti ile indeksli bir SHA-256 arama değeri saklar, düz metin gizli anahtarı asla saklamaz.
Her uygulama veya ortam için ayrı anahtarlar oluşturun ve bunları birbirinden bağımsız olarak iptal edin. Bir hesap en fazla 50 aktif anahtar barındırabilir.
Bir csk_live_ değerini asla tarayıcı JavaScript'ine, bir mobil ikili dosyasına, genel bir depoya veya ödeme sayfasına koymayın.
Bir webhook uç noktası hesap genelinde olabilir veya tek bir API anahtarına bağlanabilir; bu sayede entegrasyonlar birbirinden izole tutulur.
Eksik, hatalı biçimlendirilmiş, iptal edilmiş veya bilinmeyen bir gizli anahtar 401 unauthorized döndürür. Askıya alınmış veya kapatılmış bir üye işyeri hesabı da aynı şekilde reddedilir. Geçerli bir anahtarın kendisine tanınan izinler dışında kullanılması 403 insufficient_scope döndürür.
Idempotency
Her ödeme oluşturma isteğinde benzersiz bir Idempotency-Key gönderin. Gönderim sonrasında bağlantınız kesilirse, aynı JSON'u aynı anahtarla yeniden deneyin: CryptoPayIn başka bir adres tahsis etmek yerine orijinal ödemeyi döndürür.
| Durum | Sonuç | HTTP |
|---|---|---|
| İlk kullanım | Yeni bir ödeme oluşturur ve döndürür. | 201 |
| Aynı anahtar + aynı JSON | Mevcut ödemeyi Idempotent-Replayed: true ile birlikte döndürür. | 200 |
| Aynı anahtar + farklı JSON | İsteği idempotency_conflict olarak reddeder. | 409 |
Anahtarlar API kimlik bilgisine özeldir ve 1-128 harf, rakam, nokta, alt çizgi, iki nokta üst üste veya tire içerebilir. Kalıcı bir sipariş UUID'si iyi bir seçimdir. Aynı mekanizma çekimleri de korur; böylece yeniden denenen bir çekim işlemi asla parayı iki kez hareket ettiremez.
API referansı
API; ödemeleri, ödeme bağlantılarını, mağazaları, ürünleri, bakiyeleri ve çekimleri kapsar. Yanıtlar HTTPS üzerinden UTF-8 JSON kullanır; her oluşturma veya güncelleme işlemi Content-Type: application/json gerektirir. Değişiklik işlemleri, çağıran anahtarın izinleri tarafından kısıtlanır. Kasıtlı olarak bir tarayıcı CORS akışı yoktur: çağrılar arka ucunuzda yapılmalıdır.
/v1/assetsKullanılabilir varlıkları keşfedin/v1/currenciesFiat gösterim para birimlerini keşfedin/v1/paymentsBir ödeme oluşturun/v1/paymentsÖdemeleri listeleyin ve filtreleyin/v1/payments/{id}Bir ödemeyi getirinSürüm 1, geriye dönük uyumlu alanlar ve uç noktalarla genişleyebilir. Sözleşmeyi bozan bir değişiklik, /v1 öğesini sessizce değiştirmek yerine yeni bir temel yol kullanacaktır.
Varlıkları listeleyin
/v1/assetsBearer kimlik doğrulaması gerekirBu uç noktayı, ödeme sayfası seçenekleri için tek doğruluk kaynağı olarak kullanın. Etkin katalog kayıtlarını, bağımsız olarak denetlenen güncel kurları, minimum USD karşılığı tutarları ve düğüm ile fiyat beslemesinin hazır olup olmadığını döndürür. Bir düğüm eşitleniyorken veya fiyatı doğrulanamıyorken bir kayıt available: false ile listelenmeye devam edebilir.
curl https://cryptopayin.com/v1/assets \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"data": [{
"asset": "USDT",
"network": "TRC20",
"type": "token",
"decimals": 6,
"minimum_amount": 1,
"currency": "USD",
"base_confirmations": 19,
"available": true,
"rate_usd": "1.00000000",
"rate_source": "median:cb,cg,cl",
"rate_source_count": 3,
"rate_discrepancy_bps": 4,
"rate_status": "healthy",
"rate_updated_at": "2026-07-17T13:00:00+00:00"
}]
}Katalog ve ağ tanımlayıcıları
| Varlık | Ağ değeri | Kısa gösterim | Temel onay sayısı |
|---|---|---|---|
| BTC | mainnet | BTC | 2 |
| ETH | mainnet | ETH | 6 |
| USDT | TRC20 / ERC20 | USDT.TRC20 | 19 / 6 |
| USDC | ERC20 | USDC.ERC20 | 6 |
| DAI | ERC20 | DAI | 6 |
| SHIB | ERC20 | SHIB | 6 |
| PEPE | ERC20 | PEPE | 6 |
| LTC | mainnet | LTC | 6 |
| TRX | mainnet | TRX | 19 |
| DOGE | mainnet | DOGE | 20 |
| XMR | mainnet | XMR | 10 |
| SOL | mainnet | SOL | 32 |
Kullanılabilirlik dinamiktir. Yukarıdaki tabloyu canlı bir izin listesi olarak sabit kodlamayın. USDT gibi çoklu ağ sembolleri için network değerini açıkça gönderin veya ASSET.NETWORK kısa gösterimini kullanın.
Fiat para birimlerini listeleyin
/v1/currenciesBearer kimlik doğrulaması gerekirEtkin gösterim para birimlerini, bunların ISO hassasiyetini ve güncel USD dönüşüm durumunu döndürür. Yalnızca available: true olan satırları sunun. USD kendiliğinden geçerlidir; diğer her para birimi güncel bir canlı kur ve bağımsız bir referans kontrolü gerektirir. minimum_amount, yapılandırılmış en düşük etkin-varlık tabanını o para birimine çevirir; seçilen varlık daha yüksek bir tutar gerektirebilir, bu yüzden her zaman GET /v1/assets değerini de okuyun.
curl https://cryptopayin.com/v1/currencies \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"accounting_currency": "USD",
"data": [{
"currency": "EUR",
"name": "Euro",
"symbol": "€",
"minor_units": 2,
"available": true,
"minimum_amount": "0.86",
"rate_usd": "1.160000000000",
"rate_source": "coinbase+ecb",
"rate_source_count": 2,
"rate_discrepancy_bps": 18,
"rate_updated_at": "2026-07-17T13:00:00+00:00",
"rate_reference_at": "2026-07-16T00:00:00+00:00"
}]
}POST /v1/payments üzerinde para biriminin atlanması, geriye dönük uyumluluk için hâlâ USD anlamına gelir. JPY gibi sıfır ondalıklı para birimleri kesirli tutarları reddeder. Katalog minimumlarını ve kurlarını her zaman canlı veri olarak ele alın, asla sabit kodlanmış sabitler olarak değil.
Ödeme oluşturma
/v1/paymentsanahtar başına dakikada 120 istekİstenen gösterim para biriminde bir fatura oluşturur, güncel doğrulanmış fiat/USD ve kripto/USD anlık kurlarını kilitler, tam kripto tutarını hesaplar ve özel bir zincir üzerinde yatırma adresi bağlar.
İstek gövdesi
| Alan | Tür | Zorunluluk | Açıklama |
|---|---|---|---|
| amount | sayı veya ondalık dize | zorunlu | currency cinsinden, ilgili para biriminin ISO hassasiyetine göre değer. Kilitlenmiş USD karşılığı $1,000,000.00 tutarını aşamaz; varlık minimumları da geçerlidir. |
| currency | dize | isteğe bağlı | GET /v1/currencies içinden etkin 3 harfli para birimi. Varsayılan değer USD. |
| asset | dize | zorunlu | ETH gibi bir sembol veya USDT.TRC20 gibi bir kısa gösterim. |
| network | dize | koşullu | Bir sembol birden fazla ağda bulunduğunda zorunludur. Örnek: ERC20. |
| order_ref | dize | isteğe bağlı | Sipariş tanımlayıcınız, en fazla 128 karakter. API yanıtlarında ve olaylarda döndürülür. |
| customer_email | dize | isteğe bağlı | Geçerli e-posta adresi, en fazla 190 karakter. Üye işyeri ödeme kaydıyla birlikte saklanır. |
| redirect_url | dize | isteğe bağlı | HTTPS URL'si, en fazla 255 karakter; başarılı ödeme sonrasında sunulur. |
Yanıt alanları
| Alan | Tür | Açıklama |
|---|---|---|
| id | dize | P- ile başlayan sabit ödeme tanımlayıcısı. |
| status | dize | Güncel yaşam döngüsü durumu. |
| amount / amount_decimal / amount_minor | sayı / dize / tam sayı | İstenen gösterim tutarının kullanışlı, tam ondalık ve ISO alt birim biçimlerindeki hâli. |
| currency / currency_minor_units | dize / tam sayı | Kilitlenmiş gösterim para birimi ve hassasiyeti. |
| amount_usd / amount_usd_cents | sayı / tam sayı | Değiştirilemez iç USD muhasebe değeri. |
| fx_rate_usd / fx_source / fx_observed_at | ondalık dize / dize / ISO 8601 | Kilitlenmiş gösterim-birimi-başına-USD anlık kuru ve buna ait denetim meta verisi. |
| asset / network | dize | Çözümlenmiş zincir üzerindeki varlık. |
| crypto_amount | ondalık dize | Müşterinin göndermesi gereken tam tutar. Kripto ondalıklarını asla ikili (binary) kayan noktalı sayı olarak ayrıştırmayın. |
| crypto_received | ondalık dize | Yatırma adresinde şu anda gözlemlenen toplam tutar. |
| deposit_address | dize | Bu ödeme için tahsis edilmiş özel adres. |
| exchange_rate | ondalık dize | crypto_amount değerini hesaplamak için kullanılan kilitlenmiş kripto/USD kuru; bu alan orijinal v1 anlamını korur. |
| exchange_rate_source / exchange_rate_observed_at | dize / ISO 8601 | Değiştirilemez kripto kur denetim anlık görüntüsü. |
| confirmations | tam sayı | Güncel ağ onay sayısı. |
| confirmations_required | tam sayı | Bu ödeme için gereken eşik değeri. Daha yüksek USD kademeleri ek onay gerektirebilir. |
| checkout_url | URL | Müşteriye gösterilecek barındırılan fatura. |
| expires_at | ISO 8601 | Ödenmemiş bir fatura için son tarih. |
| completed_at | ISO 8601 / null | Tamamlandığında nihai tahsilat zamanı. |
Her iki canlı dönüşüm de oluşturmadan önce güncellik, kaynak sayısı ve sapma açısından doğrulanır. Doğrulama başarısız olursa, oluşturma işlemi eski bir kur kullanmak yerine hata döndürür. Kripto tutarı, kullanışlı bir varlık hassasiyetinde yukarı yuvarlanır; böylece yuvarlama üye işyerini asla eksik bırakmaz.
Ödemeleri listeleme
/v1/paymentsanahtar başına dakikada 240 istekKimliği doğrulanmış üye işyeri hesabı için en yeni ödemeleri önce döndürür. Mutabakat için imleç tabanlı (cursor) sayfalama ve tüm geçmişi taramadan bir siparişi bulmak için kesin filtreler kullanın.
Sorgu parametreleri
| Parametre | Varsayılan | Açıklama |
|---|---|---|
| limit | 20 | 1 ile 100 arasında sayfa boyutu. |
| starting_after | — | Önceki sayfanın next_cursor alanı olarak döndürülen ödeme kimliği. |
| status | — | pending, completed veya expired gibi tam yaşam döngüsü durumu. |
| order_ref | — | Tam üye işyeri sipariş referansı, en fazla 128 karakter. |
curl "https://cryptopayin.com/v1/payments?status=completed&limit=20" \
--header "Authorization: Bearer $CPI_SECRET_KEY"{
"object": "list",
"data": [{
"id": "P-9F27C1E4KD",
"object": "payment",
"status": "completed",
"amount": 49.99,
"currency": "USD",
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0.01388612",
"order_ref": "order_1042",
"confirmations": 12,
"confirmations_required": 12,
"completed_at": "2026-07-17T13:12:42+00:00"
}],
"has_more": true,
"next_cursor": "P-9F27C1E4KD"
}has_more true olduğunda, next_cursor değerini değiştirmeden starting_after olarak iletin. Bilinmeyen veya tekrarlanan dizi tipi sorgu parametreleri yok sayılmak yerine reddedilir.
Bir ödemeyi getirme
/v1/payments/{id}anahtar başına dakikada 240 istekOluşturma sırasında döndürülenle aynı ödeme nesnesini, güncel durum, alınan tutar, işlem karması (hash) ve onaylarla birlikte döndürür. Bir anahtar yalnızca kendi üye işyeri hesabına ait ödemeleri getirebilir.
curl https://cryptopayin.com/v1/payments/P-9F27C1E4KD \
--header "Authorization: Bearer $CPI_SECRET_KEY"Normal sipariş güncellemeleri webhook'lar tarafından yönlendirilmelidir. Getirme işlemini bir zaman aşımından sonra mutabakat yapmak, bir olayı doğrulamak, bir arka uç durum sayfası oluşturmak veya kaçırılan teslimatları onarmak için kullanın.
Ödeme yaşam döngüsü
API durumunu her zaman yetkili kaynak olarak kabul edin. Tamamlanmayı bir tarayıcı yönlendirmesinden veya müşterinin ödeme yaptığını söylemesinden çıkarmayın.
| Durum | Anlamı | Üye işyeri eylemi |
|---|---|---|
| created | Fatura ve adres tahsis edildi; henüz fonlama tespit edilmedi. | Barındırılan ödeme sayfasını gösterin. |
| pending | Kullanılabilir bir zincir üzerinde ödeme bekleniyor. | Siparişi açık tutun. |
| underpaid | Gelen tutar, üye işyerinin tolerans sınırının altında kaldı. | Ödeyiciden görüntülenen kalan tutarı göndermesini isteyin. |
| confirming | Yeterli tutar tespit edildi; onaylar bekleniyor. | Henüz siparişi karşılamayın. |
| completed | Gereken tutara ve onay sayısına ulaşıldı. | Siparişi tam olarak bir kez karşılayın. |
| overpaid | Beklenenden fazlası onaylandı. | Siparişi karşılayın ve fazlalığı inceleyin. |
| expired | Süre dolmadan önce geçerli bir ödeme tespit edilmedi. | Yeni bir ödeme oluşturun. |
| failed | Adres tahsisi veya işleme başarısız oldu. | Hatayı kaydedin ve yeni bir ödeme oluşturun. |
Zincir üzerindeki transferler geri alınamaz ve CryptoPayIn'in bir iade mekanizması yoktur — onaylanmış bir ödeme nihaidir. İyi niyet gereği yapılacak herhangi bir iade, platform dışında doğrudan sizinle müşteriniz arasında halledilir.
Barındırılan ödeme sayfası
Her API ödemesi, duyarlı (responsive) bir checkout_url içerir. Bu sayfa; üye işyerini, istenen gösterim tutarını, ilgili olduğunda kilitlenmiş USD karşılığını, tam kripto tutarını, yatırma adresini, QR kodunu, ağ uyarısını, geri sayımı ve canlı onay ilerlemesini gösterir.
Müşteri, fatura penceresi için API tarafından döndürülen aynı crypto_amount değerini görür.
Ödeyici bir CryptoPayIn hesabı oluşturmaz veya kimlik bilgisi paylaşmaz.
Sayfa, ödemeyi güvenli biçimde sorgular ve bekleme durumundan onaylanmaya, oradan da ödendi durumuna geçer.
Başarı sonrasında bir HTTPS redirect_url sunulur; bu, ödemenin kanıtı değildir.
Sipariş teslimatını her zaman arka ucunuzda tutun. Tarayıcı yönlendirmesi terk edilebilir, tekrarlanabilir veya sahte biçimde üretilebilir; ödeme durumunu yalnızca doğrulanmış bir webhook veya kimliği doğrulanmış bir GET isteği kanıtlar.
İzinler & yetki kapsamları
Her API anahtarı, Panel → Geliştiriciler bölümünde oluşturulduğunda seçilen sabit bir izin kümesi taşır. Her uç nokta, herhangi bir işlem yapmadan önce anahtarın yetki kapsamlarını kontrol eder; bir anahtarın kendisine tanınan yetkinin dışında yapılan bir çağrı, eksik izni belirten bir X-Required-Scope başlığıyla birlikte 403 insufficient_scope döndürür. Yetki kapsamları yalnızca oluşturma sırasında bir kez ayarlanır ve sonradan genişletilemez — bunun yerine yeni bir anahtar oluşturun. Yetki kapsamları mevcut olmadan önce oluşturulan anahtarlar, orijinal yeteneklerini olduğu gibi korur: payments:read ve payments:write.
| Yetki kapsamı | Sağladıkları | Uç noktalar |
|---|---|---|
payments:read | Ödemeleri listeleyin ve getirin | GET /v1/payments, GET /v1/payments/{id} |
payments:write | Barındırılan ödemeler oluşturun | POST /v1/payments |
links:read | Ödeme bağlantılarını listeleyin ve getirin | GET /v1/links, GET /v1/links/{id} |
links:write | Ödeme bağlantıları oluşturun, düzenleyin, duraklatın ve silin | POST/PATCH/DELETE /v1/links |
shops:read | Mağazaları ve ürünlerini listeleyin ve getirin | GET /v1/shops, GET .../products |
shops:write | Mağazalar, ürünler ve varyantlar oluşturun ve düzenleyin | POST/PATCH/DELETE /v1/shops ve ürünler |
balance:read | Kripto bakiyelerini ve USD tahminlerini okuyun | GET /v1/balance |
payouts:read | Çekimleri listeleyin ve getirin | GET /v1/payouts, GET /v1/payouts/{id} |
payouts:write | Zincir üzerinde çekim talep edin | POST /v1/payouts |
payouts:write, fonları zincir üzerinde hareket ettirir ve geri alınamaz. Bunu yalnızca tamamen güvendiğiniz anahtarlara tanıyın, bu anahtarları sunucu tarafında tutun ve her otomatik süreç için ayrı bir anahtar tercih edin. GET /v1/account, çağıran anahtarın yetki kapsamlarını ve hesap limitlerinizi bildirir.
Ödeme bağlantıları
Bir müşterinin istediği kadar ödeme yapabileceği, yeniden kullanılabilir barındırılan bağlantılar. Bir bağlantı, panel bağlantı oluşturucusuyla aynı fiyatlandırma, varlık, teslimat ve ödeme sayfası soru mantığına sahiptir — API bunu yalnızca yönetir. Bir hesap en fazla 50 ödeme bağlantısı barındırabilir.
/v1/linkslinks:read/v1/linkslinks:write/v1/links/{id}links:read/v1/links/{id}links:write/v1/links/{id}links:writeİstek gövdesi
| Alan | Tür | Zorunluluk | Açıklama |
|---|---|---|---|
| title | dize | zorunlu | 3–120 karakter. |
| description | dize | isteğe bağlı | En fazla 2,000 karakter; ödeme sayfasında gösterilir. |
| template | dize | isteğe bağlı | Ödeme sayfası teması: signature (varsayılan), midnight, atelier, horizon, compact veya ledger. |
| public_label | dize | isteğe bağlı | Alıcılara gösterilen genel satıcı adı (2–80 karakter). Asla bir hesap kimliği olmamalıdır. |
| amount_type | dize | isteğe bağlı | fixed (varsayılan) veya open (müşteri min/max aralığında seçer). |
| currency | dize | isteğe bağlı | GET /v1/currencies içinden gösterim para birimi. Varsayılan olarak hesap para biriminiz kullanılır. |
| amount | sayı veya dize | koşullu | fixed için zorunludur. currency cinsinden, kendi ISO hassasiyetinde. |
| min / max | sayı veya dize | koşullu | open bağlantıları için sınırlar. Üst sınır olmaması için max değeri 0 olabilir veya atlanabilir. |
| accepted_assets | dize dizisi | isteğe bağlı | ["BTC","USDT.TRC20"] gibi varlık kodları. Kullanılabilir tüm varlıklar için atlayın. |
| max_uses | tam sayı | isteğe bağlı | Tamamlanan ödeme üst sınırı. 0 sınırsız anlamına gelir. |
| expires_at | ISO 8601 | isteğe bağlı | En az 5 dakika ileride, en fazla 12 ay sonrasında. UTC. |
| delivery_type | dize | isteğe bağlı | none, text, url veya keys — ödeme sonrasında teslim edilen dijital ürünler. |
| delivery_text / delivery_url | dize | koşullu | İlgili teslimat türü için içerik (≤50,000 karakter) veya bir https URL'si. |
| delivery_keys | dize dizisi | koşullu | keys teslimatı için her öğede bir anahtar. En fazla 10,000 adet, her biri ≤500 karakter. |
| checkout_fields | dizi | isteğe bağlı | En fazla 5 {label, type, required} nesnesi; tür text, email, textarea veya number olabilir. |
| success_message / redirect_url | dize | isteğe bağlı | Ödeme sonrası mesajı (≤500 karakter) ve bir https yönlendirmesi. |
| status | dize | isteğe bağlı | Yalnızca PATCH: active veya paused. |
curl -X POST https://cryptopayin.com/v1/links \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Pro license",
"amount": 49.99,
"currency": "EUR",
"accepted_assets": ["BTC", "ETH", "USDT.TRC20"],
"delivery_type": "keys",
"delivery_keys": ["ABC-1", "ABC-2", "ABC-3"]
}'{
"id": "PL-N5PKTYB7",
"object": "payment_link",
"url": "https://cryptopaylink.co/pay/PL-N5PKTYB7",
"status": "active",
"title": "Pro license",
"amount_type": "fixed",
"currency": "EUR",
"amount": 49.99,
"amount_decimal": "49.99",
"accepted_assets": [{"asset":"BTC","network":"mainnet"},{"asset":"ETH","network":"mainnet"},{"asset":"USDT","network":"TRC20"}],
"uses": {"started": 0, "completed": 0, "in_flight": 0},
"delivery": {"type": "keys", "keys_available": 3, "keys_total": 3},
"expires_at": null,
"created_at": "2026-07-19T19:00:00+00:00"
}PATCH, kısmi bir güncellemedir: yalnızca değiştirdiğiniz alanları gönderin, gerisi satılmamış lisans anahtarları dahil olmak üzere korunur. keys bağlantılar için delivery_keys gönderilmesi, satılmamış anahtar havuzunun yerini alır; zaten teslim edilmiş anahtarlara asla dokunulmaz. Ödemesi bulunan bir bağlantının silinmesi, geçmişi bozulmadan korunarak zımnen reddedilir.
Ajan ödemesi
Her etkin ödeme bağlantısı aynı zamanda makine tarafından okunabilir bir ödeme sayfasıdır: bir yapay zekâ ajanı veya herhangi bir betik, bir tarayıcı olmadan — ve hiçbir API anahtarı olmadan — bunu keşfedebilir, bir fatura oluşturabilir ve teslimatı okuyabilir; çünkü bunlar bağlantı alan adındaki genel alıcı uç noktalarıdır, üye işyeri uç noktaları değildir. Tam sözleşme ve uygulanmış örnek için: cryptopayin.com/agents.
https://cryptopaylink.co/pay/{link}.jsongenel · keşifDurumu, fiyatlandırmayı, kabul edilen varlıkları ve fatura çağrısı için tam girdi sözleşmesini (zorunlu alanlar, kargo şeması, varyantlar) döndürür.
https://cryptopaylink.co/pay/{link}/invoicegenel · Idempotency-Key desteklerFaturayı, barındırılan sayfayla aynı çekirdek, fiyatlandırma anlık görüntüsü ve kötüye kullanım karşıtı limitler üzerinden oluşturur; yatırma adresini, tam kripto tutarını, bir cüzdan URI'sini ve makbuz URL'sini döndürür. Ajan, ardından kontrol ettiği herhangi bir cüzdandan zincir üzerinde ödeme yapar.
https://cryptopaylink.co/pay/{link}/receipt?p={payment}genel · her 5–10 sn'de bir sorgulayınCanlı durum ve onaylar; ödeme tamamlandığında yanıt, teslimatı — metin içeriğinizi, özel URL'nizi veya o ödeme için ayrılmış bir lisans anahtarını — ayrıca başarı mesajınızı ve yönlendirme URL'nizi taşır.
Mağazalar aynı protokolü konuşur
Mağaza vitrinleri, kendi alan adlarında aynı akışı sunar: canlı stoklu katalog, ardından sepeti doğrulayan, stoğu ayıran ve faturayı döndüren tek bir çağrı.
https://shopycrypto.com/s/{shop}.jsongenel · kataloghttps://shopycrypto.com/s/{shop}/ordergenel · sepet → fatura, Idempotency-Key desteklerhttps://shopycrypto.com/s/{shop}/o/{order}/receipt?p={payment}genel · her 5–10 sn'de bir sorgulayınSatıcı kontrolleri
Ajan ödemesi varsayılan olarak açıktır ve aynı sabit %1 ücrete tabidir. Bunu hesap genelinde Panel → Ayarlar → Genel → Yapay zekâ & ajan ödemesi bölümünden kapatabilirsiniz: bu durumda bağlantı ve mağazalardaki makine uç noktaları 403 agents_disabled yanıtı verirken insan ödeme sayfalarınız çalışmaya devam eder. Ajanlar tarafından oluşturulan ödemeler özel bir işaret taşımaz — panelinizde, webhook'larınızda ve dışa aktarımlarınızda sıradan ödemeler olarak görünürler.
Mağazalar
Ürünleri tek bir markalı sayfa altında toplayan barındırılan bir mağaza vitrini. Bir hesap en fazla 10 mağaza barındırabilir. Ürünler, aşağıdaki iç içe ürün uç noktaları aracılığıyla yönetilir.
/v1/shopsshops:read/v1/shopsshops:write/v1/shops/{id}shops:read/v1/shops/{id}shops:write/v1/shops/{id}shops:writeİstek gövdesi
| Alan | Tür | Zorunluluk | Açıklama |
|---|---|---|---|
| name | dize | zorunlu | 2–80 karakter. |
| tagline | dize | isteğe bağlı | En fazla 160 karakter. |
| theme | dize | isteğe bağlı | light (varsayılan) veya dark. |
| accent | dize | isteğe bağlı | GET /v1/shops üzerinde accent_palette olarak döndürülen mağaza paletinden hex vurgu rengi. |
| accepted_assets | dize dizisi | isteğe bağlı | Mağazanın ürünleri için varsayılan varlıklar, örn. ["BTC","LTC","XMR"]. Değiştirildiğinde tüm ürünlere uygulanır. |
| status | dize | isteğe bağlı | Yalnızca PATCH: active veya paused. |
CryptoPayIn tarafından politika gerekçesiyle devre dışı bırakılan bir mağaza, API aracılığıyla yeniden etkinleştirilemez veya silinemez ve admin_disabled (403) döndürür. Bir mağazanın silinmesi, ürünlerini de kaldırır; geçmiş ödemeler etkilenmeden kalır.
Ürünler & varyantlar
Ürünler bir mağazanın içinde yer alır. Her mağaza en fazla 50 ürün barındırabilir. Bir ürün dijital (anında teslimatlı) veya fiziksel (kargo ülkeleriyle) olabilir ve 1–3 seçenek grubundan oluşan en fazla 30 varyant kombinasyonu sunabilir.
/v1/shops/{shop}/productsshops:read/v1/shops/{shop}/productsshops:write/v1/shops/{shop}/products/{id}shops:read/v1/shops/{shop}/products/{id}shops:write/v1/shops/{shop}/products/{id}shops:writeİstek gövdesi
| Alan | Tür | Zorunluluk | Açıklama |
|---|---|---|---|
| title | dize | zorunlu | 3–120 karakter. |
| description / blurb | dize | isteğe bağlı | Tam açıklama ve ≤200 karakterlik bir mağaza kartı satırı. |
| emoji | dize | isteğe bağlı | Ürün kartında gösterilen tek bir emoji. |
| featured | boole | isteğe bağlı | Mağaza başına en fazla bir öne çıkan ürün. |
| product_type | dize | isteğe bağlı | digital (varsayılan) veya physical. |
| shipping_countries | dize dizisi | koşullu | Yalnızca fiziksel: ["FR","BE"] gibi ISO kodları veya dünya genelinde geçerli olması için ["*"]. |
| amount_type / currency / amount / min / max | karma | koşullu | Temel fiyatlandırma, ödeme bağlantılarıyla aynı kurallar. Fiziksel ürünler fixed olmalıdır. |
| max_uses | tam sayı | isteğe bağlı | Toplam satış üst sınırı (0 = sınırsız). |
| delivery_type + delivery_text/url/keys | karma | isteğe bağlı | Temel ürün için dijital teslimat, ödeme bağlantılarıyla aynı yapılar. |
| variant_options | dizi | isteğe bağlı | 1–3 {name, values[]} grubu, her biri 2–10 değer. Kombinasyonlar 30'u aşmamalıdır. |
| variants | dizi | koşullu | Her kombinasyon için bir nesne (aşağıya bakın). variant_options mevcut olduğunda zorunlu ve eksiksiz olmalıdır. |
| status | dize | isteğe bağlı | Yalnızca PATCH: active veya paused. |
Varyant nesnesi
| Alan | Tür | Açıklama |
|---|---|---|
| options | dize dizisi | Grup sırasına göre her seçenek grubu için bir değer, örn. ["Pro","Lifetime"]. |
| price | sayı veya dize | Ürün para biriminde varyant fiyatı. |
| stock | tam sayı veya null | Kalan birim sayısı veya sınırsız için null. |
| delivery_type + delivery_text/url/keys | karma | İsteğe bağlı, varyant başına dijital teslimat geçersiz kılması (varsayılan olarak inherit). Anahtarlar, ürünün tamamında benzersiz olmalıdır. |
curl -X POST https://cryptopayin.com/v1/shops/SH-JYRK8TFJ/products \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Software license",
"amount": 30,
"currency": "USD",
"variant_options": [
{"name": "Edition", "values": ["Standard", "Pro"]},
{"name": "Term", "values": ["1 year", "Lifetime"]}
],
"variants": [
{"options": ["Standard","1 year"], "price": 30, "delivery_type": "keys", "delivery_keys": ["S1Y-1"]},
{"options": ["Standard","Lifetime"], "price": 79, "stock": 10, "delivery_type": "keys", "delivery_keys": ["SLT-1"]},
{"options": ["Pro","1 year"], "price": 59, "delivery_type": "keys", "delivery_keys": ["P1Y-1"]},
{"options": ["Pro","Lifetime"], "price": 149, "stock": 5, "delivery_type": "keys", "delivery_keys": ["PLT-1"]}
]
}'PATCH, mevcut siparişleri ve teslim edilmiş anahtarları korur. Fiyatları veya stoğu ayarlamak için ilgili variants dizisini yeniden gönderin; atladığınız kombinasyonlar, siparişleri varsa duraklatılır, yoksa kaldırılır. Bir ürün, temel hâli ve varyantları genelinde en fazla 10,000 aktif lisans anahtarı barındırabilir ve her anahtar ürün içinde benzersiz olmalıdır.
Bakiye
/v1/balancebalance:readHer varlık için tahsil edilmiş kripto bakiyelerinizi, mümkün olan en iyi USD tahminiyle ve bir çekim işleminde alınan ağ ücretiyle birlikte döndürür. İç muhasebe her zaman USD cinsindendir; bakiyeler, üye işyeri ücreti düşüldükten sonra tamamlanan ödemelerden birikir.
{
"object": "list",
"accounting_currency": "USD",
"minimum_payout_usd": 25,
"data": [{
"asset": "USDT",
"network": "TRC20",
"amount": "99.099",
"usd_estimate": 99.02,
"payout_network_fee": "2.445463"
}]
}Doğrulanmış canlı bir kur geçici olarak kullanılamadığında usd_estimate, null olur; alttaki bakiye yine de tam doğrudur. Bu değerleri çekim kararı vermek için kullanın, nihai muhasebe için değil.
Çekimler
Tahsil edilmiş kriptoyu harici bir cüzdana taşıyın. Çekimler geri alınamaz olduğundan, bu uç nokta panelin uyguladığı her güvenlik önlemini uygular: varlık için geçerli bir hedef, doğrulanmış canlı bir kur, hesap minimumu, ağ ücreti dahil yeterli bakiye ve hesabınızda 2FA etkinse iki faktörlü onay.
/v1/payoutspayouts:read/v1/payoutspayouts:write · anahtar başına dakikada 30 istek/v1/payouts/{id}payouts:readİstek gövdesi
| Alan | Tür | Zorunluluk | Açıklama |
|---|---|---|---|
| asset | dize | zorunlu | Sembol veya kısa gösterim, örn. LTC veya USDT.TRC20. |
| network | dize | koşullu | Sembol birden fazla ağda bulunduğunda zorunludur. |
| amount | sayı veya dize | zorunlu | Ağ ücreti hariç, gönderilecek tutar; varlığın hassasiyetinde. USD değeri hesap minimumunu karşılamalıdır. |
| address | dize | zorunlu | Varlığın zinciri için doğrulanmış hedef adres. |
| note | dize | isteğe bağlı | Kendi referansınız, en fazla 255 karakter. |
| totp_code | dize | koşullu | Güncel 6 haneli kod veya kurtarma kodu. Hesapta 2FA etkinse zorunludur. |
curl -X POST https://cryptopayin.com/v1/payouts \
-H "Authorization: Bearer $CPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: withdraw-2026-07-19-01" \
-d '{
"asset": "USDT.TRC20",
"amount": "50",
"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"note": "weekly settlement"
}'{
"id": "W-EM64ZCJB",
"object": "payout",
"status": "requested",
"asset": "USDT",
"network": "TRC20",
"amount": "50",
"fee": "2.445463",
"total_debited": "52.445463",
"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": null,
"confirmations": 0,
"created_at": "2026-07-19T19:10:00+00:00"
}Durum yaşam döngüsü
| Durum | Anlamı |
|---|---|
requested | Bakiyenizden ayrıldı; operatör incelemesi veya otomatik onay bekleniyor. |
approved / processing | Onaylandı ve yürütücü tarafından yayınlanmak üzere kuyruğa alındı. |
sent | Zincir üzerinde yayınlandı; txid dolduruldu. |
confirmed | Gereken onay sayısına ulaşıldı. Nihai. |
failed | Gönderilemedi; failure_message nedenini açıklar ve bakiye iade edilir. |
cancelled | Yayınlanmadan önce iptal edildi; ayrılan bakiye iade edilir. |
Bir ağ yeniden denemesinin asla ikinci bir çekim oluşturmaması için bir Idempotency-Key gönderin: aynı gövdeyle aynı anahtar, orijinal çekimi döndürür (Idempotent-Replayed: true); farklı bir gövdeyle aynı anahtar ise 409 idempotency_conflict döndürür. 2FA kodu, dönen bir kodun sahte bir çakışma tetiklememesi için idempotency parmak izinden kasıtlı olarak hariç tutulmuştur. Ayırma işlemi bakiyenizi anında borçlandırır; başarısız veya iptal edilen bir çekim bu tutarı iade eder.
Hesap
/v1/accountherhangi bir geçerli anahtarHesap profilinizi, çağıran anahtarın yetki kapsamlarını, platform ücretinizi ve tüm canlı limitleri döndürür — kendi kendini yapılandıran bir entegrasyon veya ön kontrol için yararlıdır.
{
"object": "account",
"id": "MC67T3PHQZ",
"fee_bps": 100,
"fee_percent": 1,
"default_currency": "USD",
"two_factor_enabled": false,
"api_key": {"label": "production", "scopes": ["payments:read","payments:write"]},
"limits": {
"shops": {"used": 1, "max": 10},
"payment_links": {"used": 0, "max": 50},
"products_per_shop_max": 50,
"variant_combinations_per_product_max": 30,
"license_keys_per_product_max": 10000,
"active_api_keys_max": 50,
"checkout_fields_per_link_max": 5
},
"minimum_payout_usd": 25
}Webhook'lar
Panel -> Geliştiriciler bölümünde en fazla 10 genel HTTPS uç noktası ekleyin. Her uç nokta, yalnızca bir kez gösterilen kendi whsec_... imzalama gizli anahtarını alır. Hesap genelinde dinleyebilir veya belirli bir aktif API anahtarına bağlanabilir; anahtara özel uç noktalar yalnızca o anahtarla oluşturulan ödemeleri alır.
Ayrıştırmadan önce doğrulayın
CryptoPayIn, tam ham istek gövdesini uç nokta gizli anahtarını kullanarak imzalar. Sürüm 1, timestamp + "." + raw_body imzalar. Olayı kabul etmeden önce eski zaman damgalarını reddedin.
import crypto from "node:crypto";
const timestamp = req.headers["x-cpi-timestamp"];
const signature = req.headers["x-cpi-signature"];
const rawBody = req.rawBody; // Buffer captured before JSON parsing
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error("stale webhook");
}
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.CPI_WEBHOOK_SECRET)
.update(Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]))
.digest("hex");
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
if (!valid) throw new Error("invalid webhook signature");
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_CPI_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_CPI_SIGNATURE'] ?? '';
if (!ctype_digit($timestamp) || abs(time() - (int)$timestamp) > 300) {
http_response_code(400); exit('stale webhook');
}
$expected = 'sha256=' . hash_hmac(
'sha256', $timestamp . '.' . $rawBody, getenv('CPI_WEBHOOK_SECRET')
);
if (!hash_equals($expected, $received)) {
http_response_code(401); exit('invalid signature');
}
$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
import hashlib, hmac, os, time
raw_body = request.get_data() # bytes, before JSON decoding
timestamp = request.headers.get("X-CPI-Timestamp", "")
received = request.headers.get("X-CPI-Signature", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
raise ValueError("stale webhook")
signed = timestamp.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(
os.environ["CPI_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, received):
raise ValueError("invalid signature")Teslimat başlıkları
| Başlık | Örnek | Amaç |
|---|---|---|
| Content-Type | application/json | UTF-8 JSON gövdesi. |
| X-CPI-Timestamp | 1784293200 | İmzalanan mesaja dahil edilen Unix saniyeleri. |
| X-CPI-Signature | sha256=... | Onaltılık (hex) HMAC-SHA256. |
| X-CPI-Signature-Version | v1 | İmzalama şeması sürümü. |
| X-CPI-Event-Id | evt_a12b... | Sabit mantıksal olay kimliği; yeniden denemeler arasında aynıdır. |
| X-CPI-Delivery-Id | 1842 | Sabit uç nokta teslimat kaydı kimliği. |
Ödeme yükü (payload)
{
"event_id": "evt_a12b34c56d78e90f12345678",
"event": "payment.completed",
"id": "P-9F27C1E4KD",
"status": "completed",
"order_ref": "order_1042",
"amount": 49.99,
"amount_decimal": "49.99",
"amount_minor": 4999,
"currency_minor_units": 2,
"currency": "USD",
"amount_usd": 49.99,
"amount_usd_cents": 4999,
"fx_rate_usd": "1.000000000000",
"fx_source": "fixed:USD",
"fx_observed_at": "2026-07-17T13:00:00Z",
"fx_discrepancy_bps": 0,
"exchange_rate": "3600.00000000",
"exchange_rate_currency": "USD",
"exchange_rate_source": "median:cb,cg,cl",
"exchange_rate_source_count": 3,
"exchange_rate_observed_at": "2026-07-17T13:00:00Z",
"exchange_rate_discrepancy_bps": 12,
"asset": "ETH",
"network": "mainnet",
"crypto_amount": "0.01388612",
"crypto_received": "0.01388612",
"txid": "0x9d81...75af",
"confirmations": 12,
"confirmations_required": 12,
"deposit_address": "0x71b8c3d4700000000000000000000000000084e2",
"sent_at": "2026-07-17T13:12:42Z"
}Yeniden denemeler ve uç nokta güvenliği
Bir teslimat, HTTP 200-299 aralığında başarılı sayılır. Maliyetli işleri asenkron yapın ve hızlı yanıt verin.
Tam gövde ve olay kimliği korunur; başarısızlıklar yaklaşık olarak 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat sonra yeniden denenir.
3xx yanıtları takip edilmez. Doğrudan nihai HTTPS URL'sini kaydedin.
Özel, loopback, link-local ve ayrılmış IP'ler engellenir; her DNS yanıtı doğrulanır ve bağlantı sabitlenir (pinned).
Teslimatlar en az bir kez gerçekleşir. İşleyicinizi, teslimattan önce event_id değerini benzersiz bir kısıt ile kaydederek idempotent hâle getirin. Beklenmeyen bir olayı mutabakat yaparken API nesnesini getirin.
Olay referansı
payment.completedBeklenen tutar onaylandı.payment.overpaidBeklenenden fazlası onaylandı.payment.underpaidTolerans altında fonlama tespit edildi.payment.expiredÖdenmemiş fatura penceresi kapandı.payment.failedÖdeme kurulumu veya işlemesi başarısız oldu.payout.sentÇekim zincir üzerinde yayınlandı.payout.confirmedÇekim gerekli onay sayısına ulaştı.payout.failedÇekim tamamlanamadı.webhook.testManuel bağlantı testi.Çekim olayı yapısı
{
"event_id": "evt_b98c76d54e32a10f87654321",
"event": "payout.sent",
"id": "W-8J2K7M4RQP",
"status": "sent",
"asset": "ETH",
"network": "mainnet",
"amount": "0.25",
"fee": "0.00081768",
"address": "0x84f2...9bc1",
"txid": "0xa1c4...07ee",
"confirmations": 0,
"note": "weekly treasury",
"sent_at": "2026-07-17T14:08:31Z"
}Hatalar ve hız limitleri
Hatalar her zaman tek bir JSON zarfı kullanır. error.type üzerinden dallanın; okunabilir mesaj, sürüm değişikliği olmadan iyileştirilebilir. Destekle iletişime geçerken error.request_id veya eşleşen X-Request-Id yanıt başlığını belirtin.
{
"error": {
"type": "ambiguous_asset",
"message": "specify network (e.g. USDT.ERC20 or USDT.TRC20)",
"request_id": "b942e21f8dca4b06b8672eb9"
}
}| HTTP | Tipik türler | Anlamı |
|---|---|---|
| 400 | invalid_request, unknown_parameter | Hatalı biçimlendirilmiş JSON, sorgu veya idempotency başlığı. |
| 401 | unauthorized | Eksik, geçersiz veya aktif olmayan kimlik bilgisi/hesap. |
| 403 | insufficient_scope, admin_disabled | Gereken izinden yoksun geçerli bir anahtar (bkz. X-Required-Scope) veya bir yönetici tarafından kilitlenmiş bir kaynak. |
| 404 | not_found | Bilinmeyen uç nokta veya bu üye işyeri hesabının dışındaki bir kaynak. |
| 405 | method_not_allowed | Allow başlığında gösterilen yöntemi kullanın. |
| 409 | idempotency_conflict | Anahtar, farklı bir JSON ile yeniden kullanıldı. |
| 413 | request_too_large | JSON gövdesi 64 KiB'yi aşıyor. |
| 415 | unsupported_media_type | POST gövdesi application/json olarak bildirilmemiş. |
| 422 | invalid, limit, invalid_amount, below_minimum, bad_address, 2fa_required, unsupported_asset | Doğru biçimlendirilmiş istek, deterministik doğrulamada başarısız oldu veya bir kaynak üst sınırına takıldı. |
| 429 | rate_limited | Retry-After için bekleyin. |
| 500 | server_error | Beklenmeyen hata; aynı idempotency anahtarıyla güvenle yeniden deneyin. |
| 503 | maintenance, temporarily_unavailable, asset_unavailable, no_rate, price_stale, fiat_rate_unavailable, fiat_rate_stale, derive_failed | Geçici platform, düğüm, fiyat veya adres tahsisi hatası. Eski bir dönüşüm asla yerine konmaz. |
Güncel limitler
| Kapsam | Limit | Pencere |
|---|---|---|
| Nginx IP başına güvenlik tavanı | saniyede 10 istek, patlama (burst) 30 | Sürekli |
| Kimliği doğrulanmamış IP tavanı | 300 istek | 60 saniye |
| POST /v1/payments, links, shops, products | API anahtarı başına 120 istek | 60 saniye |
| POST /v1/payouts | API anahtarı başına 30 istek | 60 saniye |
| GET uç noktaları | API anahtarı başına 240 istek | 60 saniye |
Hesap limitleri
| Kaynak | Üst sınır |
|---|---|
| Hesap başına mağaza | 10 |
| Hesap başına ödeme bağlantısı | 50 |
| Mağaza başına ürün | 50 |
| Ürün başına varyant kombinasyonu | 30 |
| Ürün / bağlantı başına lisans anahtarı | 10,000 |
| Bağlantı başına ödeme sayfası sorusu | 5 |
| Hesap başına aktif API anahtarı | 50 |
Bu üst sınırlara karşı canlı kullanımınızı GET /v1/account üzerinden okuyun.
Başarılı, uygulama düzeyinde sınırlanmış yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını sunar. 429, 500 ve 503 durumlarını üstel geri çekilme (exponential backoff) ve jitter ile yeniden deneyin. POST için her zaman orijinal Idempotency-Key değerini ve aynı JSON'u yeniden kullanın.
Entegrasyon güvenliği
Bunları çalışma zamanında yükleyin; tam değeri asla günlüğe kaydetmeyin veya kaynak kod kontrolüne göndermeyin.
Bir tarayıcı veya mobil istemci, bir üye işyeri gizli anahtarını güvenle tutamaz.
JSON ayrıştırmadan önce zaman damgası güncelliğini kontrol edin ve sabit zamanlı imza karşılaştırması kullanın.
İşlenen olayları/siparişleri işlemsel (transactional) olarak kaydedin, böylece yeniden denemeler asla iki kez gönderim yapmaz.
Bir olay beklenmedik olduğunda veya yerel durumunuz uyuşmadığında ödemeyi getirin.
Yerine geçecek bir anahtar oluşturun, dağıtın, trafiği doğrulayın, ardından eski anahtarı silin.
Hesap erişimi, kurtarılamayan 16 haneli bir üye işyeri anahtarıyla kontrol edilir ve isteğe bağlı olarak TOTP ile korunabilir. Hem üye işyeri erişimini hem de API gizli anahtarlarını, cüzdan kimlik bilgileriyle aynı özeni göstererek saklayın.
Canlıya geçiş kontrol listesi
Bir geliştiricinin kişisel kopyasını hizmetler arasında yeniden kullanmayın.
GET /v1/assets ve GET /v1/currencies kullanın; yalnızca mevcut ve available: true olan kayıtları görüntüleyin.
İmzalama gizli anahtarını bir kez kaydedin; zaman damgasını ve imzayı doğrulayın, ardından sabit olay kimliğini tekilleştirin.
Bir yinelenen yeniden deneme senaryosu çalıştırın ve yalnızca bir ödeme kimliğinin var olduğunu doğrulayın.
Sipariş durumunuz; eski fiat kurları, kullanılamayan varlıklar, gecikmeli onaylar ve her olumsuz senaryo boyunca güvenli kalmalıdır.
Siparişlerinizi API ödeme durumlarıyla, webhook günlükleriyle ve üye işyeri defteriyle karşılaştırın.
Entegre etmeye hazır mısınız?
Saniyeler içinde bir hesap oluşturun, bir anahtar üretin ve bu referansı kodunuzun yanında bulundurun.