Ödeme bağlantıları API'si ve API anahtarları

Sunucu isteği hazır bir bağlantı döndürür#

POST /api/v1/payments ve /api/v1/payment-links aynı fatura türünü oluşturur. Payments rotasının adı bir tahsilat anlamına gelmez: sonuç, kalıcı fatura koşulları ve müşteri için bir checkoutUrl'dir.

Authorization: Bearer <key>, Content-Type: application/json ve Idempotency-Key gönderin. Idempotency anahtarları 16–100 harf, rakam, tire veya alt çizgi içerir. Her mantıksal sipariş oluşturma için bir anahtar saklayın.

curl 'https://kevmi.maxeevmax1.chatgpt.site/api/v1/payments' \
  -H "Authorization: Bearer $KEVMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-create-v1' \
  --data '{"title":"Design project · order 1042","description":"One-time payment for the agreed design work","amountMinor":500,"currency":"USD","methods":["card","alipay"],"vatCustomerPercent":100,"feeCustomerPercent":0,"orderId":"order-1042","metadata":{"campaign":"autumn"}}'

API anahtarı kapsamları ve süresi#

Doğrulanmış satıcı hesabınızda /account#keys adresinde bir anahtar oluşturun. Tam değeri yalnızca bir kez görünür; yalnızca bir karması saklanır. Anahtarlar varsayılan olarak 90 gün geçerlidir; izin verilen ömür 1–365 gündür ve hesap başına en fazla on aktif anahtar bulunabilir.

Yalnızca gerekli kapsamları verin. İptal veya süre dolumu erişimi durdurur. Bir anahtar, hesap ayarları, uç nokta yönetimi, uygulamalar veya moderasyon için tarayıcı oturumunun yerini tutmaz. Widget'larda, URL'lerde, genel depolar ve destek mesajlarında bulundurmayın.

Web sitesi, oturum çerezi, tam Origin ve X-CSRF-Token ile /api/payment-links kullanır. Bu rotalar aynı sahipli faturalar üzerinde çalışır.

Herhangi biri ve somut API yöntemleri#

Herhangi biri bir arayüz seçim modudur. Yeni faturalar yöntemleri kabul eder: USD için ["card", "alipay"] veya boş olmayan bir alt küme; RUB için ["sbp"]; USDT için ["crypto"]. herhangi biri değeri bir API ödeme yöntemi değildir.

Arayüzdeki yeni bir fatura için USD, kartları ve Alipay'ı sunar; RUB, SBP'yi sunar; USDT, kriptoyu sunar. API, uyumluluk için USD + kripto kaydedebilir, ancak canlı kripto ödemesi crypto_requires_usdt ile engellenir. USD ve USDT farklıdır; otomatik dönüştürme veya varsayılan 1:1 oran yoktur. Kripto ödemesi ayrı bir USDT faturası gerektirir.

Yeni bir canlı kart veya Alipay ödemesi için mevcut ağ geçidi yalnızca feeCustomerPercent=0 ve vatCustomerPercent=100'ü destekler: satıcı tüm işlem ücretini karşılar ve KDV müşteri için tam olarak eklenir. Diğer paylar bir faturada kaydedilip hesaplanabilir, ancak yürütme unsupported_allocation ile engellenir. Sunucu kaydedilmiş koşulları sessizce asla değiştirmez. SBP ve USDT kripto ödemeleri tüm işlem ücreti paylarını destekler ve KDV içermez.

Alanlar ve kalıcı koşullar#

Fatura satıcı adını, fiyatı, para birimini, yöntemleri, her iki maliyet payını ve hesaplanan teklifleri kaydeder. Üst veri sahibine ve sunucu olaylarında döndürülür, ancak genel ödeme sayfası üzerinden döndürülmez. İçinde ödeme sırları saklamayın.

Paylar atlanırsa, satıcı ücreti karşılar; KDV vatPayer veya hesap ayarından miras alır. Kısmi bir dağıtım vatPayer=shared döndürebilir. Başlık, orderId ve açıklama geneldir.

Ağ hatasından sonra yeniden deneyin#

İlk oluşturma 201 ve replayed=false döndürür. Aynı anahtar ve kurallı gövde 200, orijinal checkoutUrl ve replayed=true döndürür. Bu anahtar altında farklı bir istek 409 IDEMPOTENCY_CONFLICT döndürür.

Zaman aşımından sonra başka bir anahtar üretmeyin. Orijinal isteği aynı alanlarla tekrarlayın. Atlanan değerler değiştirilmiş ayarları yeniden miras almaz. orderId bir siparişi ilişkilendirmeye yardımcı olur ancak Idempotency-Key'in yerini tutmaz ve depolamada benzersiz olması gerekmez.

Okuma ve sayfalandırma#

GET /api/v1/payments linkler ve nextCursor döndürür; GET /api/v1/payments/{id} sahip olunan bir bağlantı döndürür. invoices:read gereklidir. Varsayılan sayfa boyutu 30'dur; limit 1–100 kabul eder.

GET listesi ve ayrıntı yanıtları link.payment içerir: ilgili işlemin bir özeti veya işlem yoksa null. POST/PATCH yanıtları bunu atlayabilir; özete ihtiyacınız olduğunda faturayı yeniden okuyun. Bağlantı durumu ayrıca yeni bir ödemenin başlayıp başlayamayacağını açıklar. Kart alanları ve özel anahtarlar asla dahil edilmez.

nextCursor'ı URLSearchParams üzerinden değiştirmeden iletin. null sonu işaretler; bilinmeyen ve diğer satıcıların kimlikleri 404 döndürür.

GET /api/v1/payments?limit=30
Authorization: Bearer <server-side key>

Duraklat, sürdür ve iptal et#

PATCH /api/v1/payments/{id} invoices:write ile yalnızca {"status":"active"}, {"status":"paused"} veya {"status":"cancelled"} kabul eder. İptal kesindir. expired süre bitiş zamanından türetilir; süresi dolmuş bir fatura uzatılamaz.

Fiyat, maliyet payları, açıklama, orderId, üst veri ve süre değişmezdir. Farklı koşullar için başka bir fatura oluşturun. Kullanılabilirliği değiştirmek invoice.updated olayını yayınlar, başarılı ödeme olayını değil.

Müşteri yanıtı#

GET /api/checkout/{token}?method=card genel faturayı, teklifi, yöntem kullanılabilirliğini ve mevcut işlemi döndürür. Sahip üst verisi, sırlar ve bakiyeler açığa çıkarılmaz.

POST /api/checkout/{token}/pay Site Origin ve somut bir yöntem gerektirir. Kart verileri yalnızca mühürlü olarak kabul edilir: {intent,jwe}, tarayıcı /card-intent aldıktan sonra. Banka kodları şifrelenir ve /code üzerinden gönderilir. Kripto, kayıtlı bir USDT faturası ve kullanılabilir bir coin/ağ çifti kullanır.

Yeni bir ödeme ve kart niyeti, satıcının en son web sitesi inceleme başvurusunun onaylanmasını gerektirir. Onay tek başına ödeme ağ geçidini bağlamaz. İnceleme gönderimden sonra değişirse, mevcut işlem durum okumaları, mutabakat ve talep edilen banka kodu için kullanılabilir kalır.

Eksik canlı bağlantı GATEWAY_NOT_CONNECTED döndürür; uyumsuz bir dağıtım asla başka bir hesaplamayla değiştirilmez. Durum ve mutabakat, yinelenen bir tahsilat olmadan orijinal işlemi okur.

Birden fazla mağaza ve tek USD taban fiyat#

Toplu analiz ve işlemler için Tüm mağazaları seçin veya kendi kayıtları için bir mağaza seçin. Her mağazanın ayrı bir storeId'si, adı, varsayılan KDV'si, faturaları, API anahtarları, webhook uç noktaları, olay geçmişi ve web sitesi uygulaması vardır. Bildirimler ve destek talepleri hesaba aittir. Bir hesap en fazla 100 mağaza oluşturabilir. Mevcut kayıtlar ilk mağazasında kalır.

Yeni çalışma alanı faturaları pricingMode="universal" ve USD taban fiyat kullanır. Any, kart, alipay, sbp ve kriptoyu içerir; bir satıcı bir alt küme seçebilir. Kartlar ve Alipay USD tahsil eder. SBP, Rusya Merkez Bankası USD/RUB referans kurunu kullanarak RUB tahsil eder. Kripto, açık fatura kuralı 1 USD = 1 USDT kapsamında USDT tahsil eder. Bu bir fatura dönüştürme kuralıdır, piyasa USDT kotasyonu değildir. Ağ geçidi, transferden önce seçilen coin'in kurunu, tam transfer tutarını ve talimatlarını sağlar.

Referans kuru ve her iki tutar oluşturma sırasında dondurulur. RUB dönüştürmesi içeren faturalar 24 saat içinde sona erer. Referans kuru alınamazsa, oluşturma FX_UNAVAILABLE ile başarısız olur; uydurulmuş veya bayat yedek kur kullanılmaz. Sahip yanıt tutarı ve kotasyonlar USD muhasebe para birimini kullanır. quotes[method].settlement, yerel tahsil kotasyonunu içerir. Genel ödeme sayfası, seçilen tahsil para birimini currency içinde, orijinal fiyatı baseAmountMinor/baseCurrency içinde ve referans kurunu fx içinde gösterir. Bir ödeme gönderildikten sonra yöntemi değiştirilemez; bir faturanın tek ağ geçidi işlemi vardır.

Amaçlanan mağaza içinde bir API anahtarı oluşturun ve sunucunuzdan Authorization: Bearer <key> gönderin. Mağaza bağlaması değişmezdir; X-Kevmi-Store, anahtara başka bir mağazaya erişim izni veremez. Tarayıcı oturumları X-Kevmi-Store: <storeId> seçer; atlanırsa ilk mağaza seçilir. all değeri yalnızca GET /api/account/dashboard ve GET /api/payment-links tarafından kabul edilir. Değişiklikler seçili bir mağaza, Origin ve X-CSRF-Token gerektirir. Hesap kimlikleri ve mağaza kimlikleri farklı tanımlayıcılardır.

Uyumluluk için, pricingMode="universal" içermeyen API istekleri yerel fiyatlandırmayı ve orijinal para birimi kısıtlamalarını korur. Mevcut faturalar asla yeniden hesaplanmaz. Analizlerdeki onaylanmış tahsilatlar, doğrulanmış ödemelerden kaydedilmiş fatura giderlerinin düşülmesiyle elde edilir; bunlar çekilebilir bakiye değildir. Eski fatura para birimleri ayrı kalır ve ödemeler destek ile düzenlenir. Bir siparişi yalnızca sunucu API'si, olay geçmişi veya imzalı bir webhook üzerinden payment.fulfillmentReady=true ve payment.status="succeeded" durumunu kontrol ettikten sonra yerine getirin.