Para sözleşmesi ve 1.0 geçişi
1.0 sözleşmesi kırıcı bir değişikliktir: API tüketicilerini, ödeme formlarını, SDK’ları ve entegrasyonları birlikte yükseltin. Node.js/Go için 1.0.0, PHP/Java/.NET/Ruby/Elixir için 1.0.1, Python/Rust için 1.0.2 kullanın. Yerel entegrasyon sürümleri ve kurulum kanalları SDK kataloğundadır. Metin sözleşmesinin yanında sayısal tutar kabul edilmez.
İstek, yanıt ve webhook para alanları, para biriminin minor biriminde kanonik ondalık tabanlı tam sayı metni taşır. Alan adları değişmez: kök ödeme amount, sepet price, bakiye, prim, ücret, mutabakat tutarı ve Minor ile biten para alanları bu kurala uyar. Oran, yüzde, baz puan, adet, miktar ve zaman damgalarının türleri korunur.
{
"amount": "9007199254740993",
"currency": "TRY",
"basketItems": [
{ "id": "item-1", "name": "Örnek", "itemType": "PHYSICAL", "price": "9007199254740993" }
]
}Bu örnek kayıpsızlık kontrolüdür; sağlayıcının bu işlem büyüklüğünü kabul ettiği anlamına gelmez. Ürün, sağlayıcı ve mevcut depolama sınırları geçerlidir.
| Alan türü | Kanonik yazım |
|---|---|
| Pozitif ödeme / capture / iade | "1", "10050" |
| Sıfıra izin verilen toplam | "0", "10050" |
| İşaretli bakiye ve fark | "-10050", "0", "10050" |
Küçük olsalar bile JSON sayıları reddedilir. Ondalık metin, boşluk, başta artı, gereksiz baştaki sıfırlar, "-0", üs gösterimi, NaN ve Infinity geçersizdir. Fiat için işaretli 64 bit depolama aralığı "-9223372036854775808"–"9223372036854775807" olur; alanın kendi işaret ve alt/üst sınırı ayrıca korunur. Kripto alanları daha büyük kesinlik kullanabilir; tüm para alanlarına genel 19 basamak sınırı uygulanmaz.
İsteğe bağlı tahsilat/iade tutarında uygun kalan tutarın kullanılması için alanı atlayın. Açık "0" ve JSON null geçerli parasal istek değerleri değildir. SDK’nın belgelenen argüman atlama yolunu veya özel kalan-tutar işlemini (örneğin PHP captureRemaining / refundRemaining) kullanın; zorunlu string argümana null vermeyin. Mevcut işlem ve idempotency anahtarı korunur.
Ondalık metinden dönüşüm
Gerçek ve desteklenen para biriminin basamağını kullanın. Eksik para birimini TRY varsaymayın; kayan noktalı tutarı 100 ile çarpmayın; yanıt tutarını Number, parseFloat veya eşdeğeriyle sayıya çevirmeyin.
| Para birimi | Basamak | Ondalık metin | Minor metin |
|---|---|---|---|
| JPY | 0 | "1500" | "1500" |
| TRY | 2 | "15.00" | "1500" |
| KWD | 3 | "1.500" | "1500" |
Basamakları doğrudan kesin tamsayı/ondalık kütüphanesiyle dönüştürün. Hesabı bigint veya eşdeğeriyle yapıp .toString() ile serileştirin; bigint doğrudan JSON değeri değildir. Excel gibi kaynaklarda tutarı baştan metin hücresinde tutun. Yalnız aynı para birimindeki tutarları toplayın.
Geçiş adımları
- Kalıcı sipariş görüntülerini, istek tiplerini ve yanıt okuyucularını metne geçirin; onaylı tutarı ve özgün para birimini koruyun.
- Tüm ödeme yöntemlerini, split bacaklarını, iadeleri, capture, sabit ücret, ödeme/mutabakat, cüzdan, link, abonelik, sigorta ve Fiziksel POS tüketicilerini güncelleyin.
- Yeni JSON gövdesinin tam baytlarını imzalayın. Webhook imzasını parse etmeden önce özgün ham baytlarla doğrulayın; imza öncesinde tutarı yeniden yazmayın.
- Merchant/ortam sahipliğini, idempotency anahtarlarını ve kalıcı deneme gövdelerini koruyun. Belirsiz eski denemeyi uzlaştırın; gövdeyi değiştirip yeni anahtar üretmek geçiş yöntemi değildir.
"9007199254740993", JPY/TRY/KWD, işaretli bakiye, sayısal girdi reddi ve atlanan/sıfır capture-iade ayrımını test edin. Sağlayıcının teknik sınırlarını ayrıca sınayın.
Public API sayısal uyumluluk yolu içermez. İç tarihsel olay/yapılandırma okuyucuları yalnız bilinen sürümsüz kalıcı kayıtların güvenli tamsayı alanlarıyla sınırlıdır; yeni public girdide kullanılamaz. Önceden yuvarlanmış güvensiz sayıyı metne çevirerek onarmayın.
Parasal analitik toplamları açık para birimi ister veya para birimine göre ayrı gruplar döner. Backtest dosyaları ana birimde ondalık metin ve dosya başına tek açık desteklenen para birimi içerir; normalize işlemler ve rapor tutarları minor metindir. Sayısal Excel tutar hücreleri reddedilir.
Fiziksel POS
Fiziksel POS'ta amountMinor, kalem fiyatları ve vergileri, ters işlem toplamları, rapor toplamları ve gün sonu tutarları aynı dize sözleşmesini kullanır. SDK istek modellerini ve doğrudan HTTP gövdelerini birlikte güncelleyin. quantityMilli, adetler, rateBp ve rowVersion sayı olarak kalır; henüz bulunmayan yanıt tutarları belgelenmiş alanlarda null olabilir.
İşleme özgü kurallar devam eder: tutar bazlı REFUND ve PREAUTH_CLOSE pozitif tutar dizesi ister. Kalemli iadede isteğe bağlı toplam veya satır tutarı gönderilmezse sunucu hesaplar; açık null reddedilir. VOID ve PREAUTH_CANCEL tutar alanı gönderilmeden tanımlı tam tutarı kullanır. Ayrıntılar: Fiziksel POS ödemeleri ve kalem bazlı iade.