CryptoPayIn
Geliştirici dokümantasyonu

Zincir üzerinde tahsil edilen ödemeler geliştirin.

Bir ödeme oluşturmak, müşteriyi barındırılan ödeme sayfasına yönlendirmek, onayları takip etmek ve üretim ortamında imzalı webhook'ları işlemek için gereken her şey.

API temel URL'siSürüm 1
https://cryptopayin.com/v1
ProtokolREST / JSON
Kimlik doğrulamaBearer gizli anahtarı
ModYalnızca canlı
Giriş

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.

Temel URL/v1
Fiat tutarlarıISO alt birimleri
Kripto değerleriOndalık dizeler
Varsayılan geçerlilik süresi30 dakika
!

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

1Bir anahtar oluşturun

Panel -> Geliştiriciler bölümünde bir kez gizli anahtar oluşturun.

2Ödeme oluşturun

Sipariş para birimini, tutarı ve seçilen varlığı POST edin.

3Ödeme sayfasını açın

Müşteriyi döndürülen barındırılan URL'ye yönlendirin.

4Olayı işleyin

HMAC'i doğrulayın ve siparişinizi idempotent biçimde güncelleyin.

Başlarken

İ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"
  }'

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 bilgileri

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.

AUTHAuthorization: Bearer csk_live_...Her uç nokta
Yalnızca bir kez gösterilir

Ham 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.

Bağımsız anahtarlar

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.

Yalnızca sunucu tarafında

Bir csk_live_ değerini asla tarayıcı JavaScript'ine, bir mobil ikili dosyasına, genel bir depoya veya ödeme sayfasına koymayın.

Webhook kapsamı

Bir webhook uç noktası hesap genelinde olabilir veya tek bir API anahtarına bağlanabilir; bu sayede entegrasyonlar birbirinden izole tutulur.

i

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.

Güvenli yeniden denemeler

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.

DurumSonuçHTTP
İlk kullanımYeni bir ödeme oluşturur ve döndürür.201
Aynı anahtar + aynı JSONMevcut ö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.

REST API

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.

GET/v1/assetsKullanılabilir varlıkları keşfedin
GET/v1/currenciesFiat gösterim para birimlerini keşfedin
POST/v1/paymentsBir ödeme oluşturun
GET/v1/paymentsÖdemeleri listeleyin ve filtreleyin
GET/v1/payments/{id}Bir ödemeyi getirin
i

Sü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.

API referansı

Varlıkları listeleyin

GET/v1/assetsBearer kimlik doğrulaması gerekir

Bu 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ıkAğ değeriKısa gösterimTemel onay sayısı
BTCmainnetBTC2
ETHmainnetETH6
USDTTRC20 / ERC20USDT.TRC2019 / 6
USDCERC20USDC.ERC206
DAIERC20DAI6
SHIBERC20SHIB6
PEPEERC20PEPE6
LTCmainnetLTC6
TRXmainnetTRX19
DOGEmainnetDOGE20
XMRmainnetXMR10
SOLmainnetSOL32
!

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.

API referansı

Fiat para birimlerini listeleyin

GET/v1/currenciesBearer kimlik doğrulaması gerekir

Etkin 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"
  }]
}
i

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.

API referansı

Ödeme oluşturma

POST/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

AlanTürZorunlulukAçıklama
amountsayı veya ondalık dizezorunlucurrency 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.
currencydizeisteğe bağlıGET /v1/currencies içinden etkin 3 harfli para birimi. Varsayılan değer USD.
assetdizezorunluETH gibi bir sembol veya USDT.TRC20 gibi bir kısa gösterim.
networkdizekoşulluBir sembol birden fazla ağda bulunduğunda zorunludur. Örnek: ERC20.
order_refdizeisteğ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_emaildizeisteğe bağlıGeçerli e-posta adresi, en fazla 190 karakter. Üye işyeri ödeme kaydıyla birlikte saklanır.
redirect_urldizeisteğe bağlıHTTPS URL'si, en fazla 255 karakter; başarılı ödeme sonrasında sunulur.

Yanıt alanları

AlanTürAçıklama
iddizeP- ile başlayan sabit ödeme tanımlayıcısı.
statusdizeGüncel yaşam döngüsü durumu.
amount / amount_decimal / amount_minorsayı / 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_unitsdize / tam sayıKilitlenmiş gösterim para birimi ve hassasiyeti.
amount_usd / amount_usd_centssayı / tam sayıDeğiştirilemez iç USD muhasebe değeri.
fx_rate_usd / fx_source / fx_observed_atondalık dize / dize / ISO 8601Kilitlenmiş gösterim-birimi-başına-USD anlık kuru ve buna ait denetim meta verisi.
asset / networkdizeÇözümlenmiş zincir üzerindeki varlık.
crypto_amountondalık dizeMüşterinin göndermesi gereken tam tutar. Kripto ondalıklarını asla ikili (binary) kayan noktalı sayı olarak ayrıştırmayın.
crypto_receivedondalık dizeYatırma adresinde şu anda gözlemlenen toplam tutar.
deposit_addressdizeBu ödeme için tahsis edilmiş özel adres.
exchange_rateondalık dizecrypto_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_atdize / ISO 8601Değiştirilemez kripto kur denetim anlık görüntüsü.
confirmationstam sayıGüncel ağ onay sayısı.
confirmations_requiredtam sayıBu ödeme için gereken eşik değeri. Daha yüksek USD kademeleri ek onay gerektirebilir.
checkout_urlURLMüşteriye gösterilecek barındırılan fatura.
expires_atISO 8601Ödenmemiş bir fatura için son tarih.
completed_atISO 8601 / nullTamamlandığı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.

API referansı

Ödemeleri listeleme

GET/v1/paymentsanahtar başına dakikada 240 istek

Kimliğ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

ParametreVarsayılanAçıklama
limit201 ile 100 arasında sayfa boyutu.
starting_afterÖnceki sayfanın next_cursor alanı olarak döndürülen ödeme kimliği.
statuspending, completed veya expired gibi tam yaşam döngüsü durumu.
order_refTam ü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"
}
i

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.

API referansı

Bir ödemeyi getirme

GET/v1/payments/{id}anahtar başına dakikada 240 istek

Oluş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"
i

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.

Durum modeli

Ö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.

created->pending->underpaidveyaconfirming->completed/overpaid
DurumAnlamıÜye işyeri eylemi
createdFatura ve adres tahsis edildi; henüz fonlama tespit edilmedi.Barındırılan ödeme sayfasını gösterin.
pendingKullanılabilir bir zincir üzerinde ödeme bekleniyor.Siparişi açık tutun.
underpaidGelen tutar, üye işyerinin tolerans sınırının altında kaldı.Ödeyiciden görüntülenen kalan tutarı göndermesini isteyin.
confirmingYeterli tutar tespit edildi; onaylar bekleniyor.Henüz siparişi karşılamayın.
completedGereken tutara ve onay sayısına ulaşıldı.Siparişi tam olarak bir kez karşılayın.
overpaidBeklenenden fazlası onaylandı.Siparişi karşılayın ve fazlalığı inceleyin.
expiredSüre dolmadan önce geçerli bir ödeme tespit edilmedi.Yeni bir ödeme oluşturun.
failedAdres 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.

Müşteri deneyimi

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.

Kur kilitlendi

Müşteri, fatura penceresi için API tarafından döndürülen aynı crypto_amount değerini görür.

Müşteri hesabı yok

Ödeyici bir CryptoPayIn hesabı oluşturmaz veya kimlik bilgisi paylaşmaz.

Canlı durum

Sayfa, ödemeyi güvenli biçimde sorgular ve bekleme durumundan onaylanmaya, oradan da ödendi durumuna geçer.

Üye işyeri yönlendirmesi

Başarı sonrasında bir HTTPS redirect_url sunulur; bu, ödemenin kanıtı değildir.

i

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.

Kimlik bilgileri

İ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 getirinGET /v1/payments, GET /v1/payments/{id}
payments:writeBarındırılan ödemeler oluşturunPOST /v1/payments
links:readÖdeme bağlantılarını listeleyin ve getirinGET /v1/links, GET /v1/links/{id}
links:writeÖdeme bağlantıları oluşturun, düzenleyin, duraklatın ve silinPOST/PATCH/DELETE /v1/links
shops:readMağazaları ve ürünlerini listeleyin ve getirinGET /v1/shops, GET .../products
shops:writeMağazalar, ürünler ve varyantlar oluşturun ve düzenleyinPOST/PATCH/DELETE /v1/shops ve ürünler
balance:readKripto bakiyelerini ve USD tahminlerini okuyunGET /v1/balance
payouts:readÇekimleri listeleyin ve getirinGET /v1/payouts, GET /v1/payouts/{id}
payouts:writeZincir üzerinde çekim talep edinPOST /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.

Makine alıcılar

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.

GEThttps://cryptopaylink.co/pay/{link}.jsongenel · keşif

Durumu, 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.

POSThttps://cryptopaylink.co/pay/{link}/invoicegenel · Idempotency-Key destekler

Faturayı, 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.

GEThttps://cryptopaylink.co/pay/{link}/receipt?p={payment}genel · her 5–10 sn'de bir sorgulayın

Canlı 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ı.

GEThttps://shopycrypto.com/s/{shop}.jsongenel · katalog
POSThttps://shopycrypto.com/s/{shop}/ordergenel · sepet → fatura, Idempotency-Key destekler
GEThttps://shopycrypto.com/s/{shop}/o/{order}/receipt?p={payment}genel · her 5–10 sn'de bir sorgulayın

Satı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.

Üye işyeri kaynakları

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.

GET/v1/shopsshops:read
POST/v1/shopsshops:write
GET/v1/shops/{id}shops:read
PATCH/v1/shops/{id}shops:write
DELETE/v1/shops/{id}shops:write

İstek gövdesi

AlanTürZorunlulukAçıklama
namedizezorunlu2–80 karakter.
taglinedizeisteğe bağlıEn fazla 160 karakter.
themedizeisteğe bağlılight (varsayılan) veya dark.
accentdizeisteğe bağlıGET /v1/shops üzerinde accent_palette olarak döndürülen mağaza paletinden hex vurgu rengi.
accepted_assetsdize dizisiisteğ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.
statusdizeisteğe bağlıYalnızca PATCH: active veya paused.
i

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.

Üye işyeri kaynakları

Ü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.

GET/v1/shops/{shop}/productsshops:read
POST/v1/shops/{shop}/productsshops:write
GET/v1/shops/{shop}/products/{id}shops:read
PATCH/v1/shops/{shop}/products/{id}shops:write
DELETE/v1/shops/{shop}/products/{id}shops:write

İstek gövdesi

AlanTürZorunlulukAçıklama
titledizezorunlu3–120 karakter.
description / blurbdizeisteğe bağlıTam açıklama ve ≤200 karakterlik bir mağaza kartı satırı.
emojidizeisteğe bağlıÜrün kartında gösterilen tek bir emoji.
featuredbooleisteğe bağlıMağaza başına en fazla bir öne çıkan ürün.
product_typedizeisteğe bağlıdigital (varsayılan) veya physical.
shipping_countriesdize dizisikoşulluYalnızca fiziksel: ["FR","BE"] gibi ISO kodları veya dünya genelinde geçerli olması için ["*"].
amount_type / currency / amount / min / maxkarmakoşulluTemel fiyatlandırma, ödeme bağlantılarıyla aynı kurallar. Fiziksel ürünler fixed olmalıdır.
max_usestam sayıisteğe bağlıToplam satış üst sınırı (0 = sınırsız).
delivery_type + delivery_text/url/keyskarmaisteğe bağlıTemel ürün için dijital teslimat, ödeme bağlantılarıyla aynı yapılar.
variant_optionsdiziisteğe bağlı1–3 {name, values[]} grubu, her biri 2–10 değer. Kombinasyonlar 30'u aşmamalıdır.
variantsdizikoşulluHer kombinasyon için bir nesne (aşağıya bakın). variant_options mevcut olduğunda zorunlu ve eksiksiz olmalıdır.
statusdizeisteğe bağlıYalnızca PATCH: active veya paused.

Varyant nesnesi

AlanTürAçıklama
optionsdize dizisiGrup sırasına göre her seçenek grubu için bir değer, örn. ["Pro","Lifetime"].
pricesayı veya dizeÜrün para biriminde varyant fiyatı.
stocktam sayı veya nullKalan birim sayısı veya sınırsız için null.
delivery_type + delivery_text/url/keyskarmaİ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"]}
    ]
  }'
i

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.

Üye işyeri kaynakları

Bakiye

GET/v1/balancebalance:read

Her 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"
  }]
}
i

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.

Üye işyeri kaynakları

Ç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.

GET/v1/payoutspayouts:read
POST/v1/payoutspayouts:write · anahtar başına dakikada 30 istek
GET/v1/payouts/{id}payouts:read

İstek gövdesi

AlanTürZorunlulukAçıklama
assetdizezorunluSembol veya kısa gösterim, örn. LTC veya USDT.TRC20.
networkdizekoşulluSembol birden fazla ağda bulunduğunda zorunludur.
amountsayı veya dizezorunluAğ ücreti hariç, gönderilecek tutar; varlığın hassasiyetinde. USD değeri hesap minimumunu karşılamalıdır.
addressdizezorunluVarlığın zinciri için doğrulanmış hedef adres.
notedizeisteğe bağlıKendi referansınız, en fazla 255 karakter.
totp_codedizekoşulluGü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ü

DurumAnlamı
requestedBakiyenizden ayrıldı; operatör incelemesi veya otomatik onay bekleniyor.
approved / processingOnaylandı ve yürütücü tarafından yayınlanmak üzere kuyruğa alındı.
sentZincir üzerinde yayınlandı; txid dolduruldu.
confirmedGereken onay sayısına ulaşıldı. Nihai.
failedGönderilemedi; failure_message nedenini açıklar ve bakiye iade edilir.
cancelledYayı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.

Üye işyeri kaynakları

Hesap

GET/v1/accountherhangi bir geçerli anahtar

Hesap 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
}
Sunucudan sunucuya olaylar

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");

Teslimat başlıkları

BaşlıkÖrnekAmaç
Content-Typeapplication/jsonUTF-8 JSON gövdesi.
X-CPI-Timestamp1784293200İmzalanan mesaja dahil edilen Unix saniyeleri.
X-CPI-Signaturesha256=...Onaltılık (hex) HMAC-SHA256.
X-CPI-Signature-Versionv1İmzalama şeması sürümü.
X-CPI-Event-Idevt_a12b...Sabit mantıksal olay kimliği; yeniden denemeler arasında aynıdır.
X-CPI-Delivery-Id1842Sabit 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

Herhangi bir 2xx döndürün

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.

Toplam altı deneme

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.

Yönlendirme yok

3xx yanıtları takip edilmez. Doğrudan nihai HTTPS URL'sini kaydedin.

Yalnızca genel hedefler

Ö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.

Webhook'lar

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"
}
Güvenilirlik

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"
  }
}
HTTPTipik türlerAnlamı
400invalid_request, unknown_parameterHatalı biçimlendirilmiş JSON, sorgu veya idempotency başlığı.
401unauthorizedEksik, geçersiz veya aktif olmayan kimlik bilgisi/hesap.
403insufficient_scope, admin_disabledGereken izinden yoksun geçerli bir anahtar (bkz. X-Required-Scope) veya bir yönetici tarafından kilitlenmiş bir kaynak.
404not_foundBilinmeyen uç nokta veya bu üye işyeri hesabının dışındaki bir kaynak.
405method_not_allowedAllow başlığında gösterilen yöntemi kullanın.
409idempotency_conflictAnahtar, farklı bir JSON ile yeniden kullanıldı.
413request_too_largeJSON gövdesi 64 KiB'yi aşıyor.
415unsupported_media_typePOST gövdesi application/json olarak bildirilmemiş.
422invalid, limit, invalid_amount, below_minimum, bad_address, 2fa_required, unsupported_assetDoğru biçimlendirilmiş istek, deterministik doğrulamada başarısız oldu veya bir kaynak üst sınırına takıldı.
429rate_limitedRetry-After için bekleyin.
500server_errorBeklenmeyen hata; aynı idempotency anahtarıyla güvenle yeniden deneyin.
503maintenance, temporarily_unavailable, asset_unavailable, no_rate, price_stale, fiat_rate_unavailable, fiat_rate_stale, derive_failedGeçici platform, düğüm, fiyat veya adres tahsisi hatası. Eski bir dönüşüm asla yerine konmaz.

Güncel limitler

KapsamLimitPencere
Nginx IP başına güvenlik tavanısaniyede 10 istek, patlama (burst) 30Sürekli
Kimliği doğrulanmamış IP tavanı300 istek60 saniye
POST /v1/payments, links, shops, productsAPI anahtarı başına 120 istek60 saniye
POST /v1/payoutsAPI anahtarı başına 30 istek60 saniye
GET uç noktalarıAPI anahtarı başına 240 istek60 saniye

Hesap limitleri

KaynakÜst sınır
Hesap başına mağaza10
Hesap başına ödeme bağlantısı50
Mağaza başına ürün50
Ürün başına varyant kombinasyonu30
Ürün / bağlantı başına lisans anahtarı10,000
Bağlantı başına ödeme sayfası sorusu5
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.

Üretim ortamı güvenliği

Entegrasyon güvenliği

API gizli anahtarlarını bir gizli anahtar yöneticisinde saklayın

Bunları çalışma zamanında yükleyin; tam değeri asla günlüğe kaydetmeyin veya kaynak kod kontrolüne göndermeyin.

API'yi arka ucunuzdan çağırın

Bir tarayıcı veya mobil istemci, bir üye işyeri gizli anahtarını güvenle tutamaz.

Ham webhook gövdesini doğrulayın

JSON ayrıştırmadan önce zaman damgası güncelliğini kontrol edin ve sabit zamanlı imza karşılaştırması kullanın.

Sipariş teslimatını idempotent hale getirin

İşlenen olayları/siparişleri işlemsel (transactional) olarak kaydedin, böylece yeniden denemeler asla iki kez gönderim yapmaz.

Yönlendirmelere değil, nihai API durumuna güvenin

Bir olay beklenmedik olduğunda veya yerel durumunuz uyuşmadığında ödemeyi getirin.

Örtüşmeli olarak döndürün (rotate)

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ş

Canlıya geçiş kontrol listesi

1
Üretime özel bir API anahtarı oluşturun

Bir geliştiricinin kişisel kopyasını hizmetler arasında yeniden kullanmayın.

2
Her iki canlı katalogu da sorgulayın

GET /v1/assets ve GET /v1/currencies kullanın; yalnızca mevcut ve available: true olan kayıtları görüntüleyin.

3
Webhook uç noktanızı ekleyin ve test edin

İmzalama gizli anahtarını bir kez kaydedin; zaman damgasını ve imzayı doğrulayın, ardından sabit olay kimliğini tekilleştirin.

4
Her sipariş için bir idempotency anahtarı kullanın

Bir yinelenen yeniden deneme senaryosu çalıştırın ve yalnızca bir ödeme kimliğinin var olduğunu doğrulayın.

5
Kur kesintilerini, eksik ödemeyi ve süre dolumunu test edin

Sipariş durumunuz; eski fiat kurları, kullanılamayan varlıklar, gecikmeli onaylar ve her olumsuz senaryo boyunca güvenli kalmalıdır.

6
Günlük mutabakat yapın

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.

Hesap oluştur