POST /api/v2/server-side-api/vc/transactions/

Sanal para birimi işlemi oluştur

Tek bir atomik işlemde bir profil için bir veya daha fazla sanal para birimini alacaklandırır veya borçlandırır. Alacaklandırmak (vermek) için pozitif amount, borçlandırmak (harcamak) için negatif amount kullanın. Tüm öğeler birlikte uygulanır — herhangi bir öğe başarısız olursa, hiçbiri uygulanmaz.

Her para birimi kodu istek başına yalnızca bir kez görünebilir. Bu uç nokta aracılığıyla yapılan bir alacaklandırma her zaman süresi dolmayan bir bakiye oluşturur.

İşlemi sanal para birimi analizlerinde kullanılabilir hale getirmek için operation ve feature ile etiketleyin. Tüm etiketleme alanları isteğe bağlıdır: yalnızca items ve metadata içeren bir istek operation: null ile kaydedilir.

Header parameters

adapty-customer-user-idstring

Sisteminizdeki müşterinin benzersiz kimliği. adapty-customer-user-id veya adapty-profile-id'den biri zorunludur.

adapty-profile-idstring

Sisteminizdeki profilin benzersiz kimliği. Anonim profillerle çalışıyorsanız en iyi seçeneğinizdir. adapty-customer-user-id veya adapty-profile-id'den biri zorunludur.

Idempotency-Keystring · uuid

İsteği idempotent yapan bir UUID v4. Aynı anahtarla bir isteği yeniden denerseniz, Adapty bakiyeleri tekrar değiştirmeden orijinal işlemin sonucunu döndürür. Geçerli bir UUID v4 olmalıdır.

Anahtarlar tek bir profile kapsamlı olarak bir saate kadar hatırlanır. Bu süre dolduktan sonra, aynı anahtara sahip bir istek yeni bir işlem olarak uygulanır — dolayısıyla anahtarı bir çağrıyı güvenli şekilde yeniden denemek için kullanın, uzun vadede bir vermeyi tekilleştirmek için değil.

Request body

Sanal para birimi işlemi oluşturmak için istek gövdesi.

itemsarray of objectrequired

Atomik olarak uygulanacak bakiye düzenlemeleri. Her para birimi kodu yalnızca bir kez görünebilir.

currency_codestringrequired

Düzenlenecek sanal para birimi kodu.

amountintegerrequired

Uygulanacak miktar. Pozitif bir değer para birimini alacaklandırır (ekler); negatif bir değer ise borçlandırır (harcar). Sıfır olamaz.

metadataobject

İşlemle birlikte saklanan isteğe bağlı anahtar-değer çiftleri. En fazla 5 anahtar. Her anahtar ^[a-z0-9_]{1,30}$ kalıbıyla eşleşmeli, her değer en fazla 200 karakter olmalıdır.

operationstring

İşlemin ne anlama geldiği. Çoğu entegrasyon dört değere ihtiyaç duyar: spend, spend_reversal, reward, reward_reversal. Belirtilmezse işlem kaydedilir ve operation: null ile döndürülür. Değerler: top_up — bir satın alma, abonelik veya deneme için yüklenen jetonlar; refund — para iade edildiği için geri alınan jetonlar; spend — bir özellik veya içerik için harcanan jetonlar; spend_reversal — başarısız bir işlem (örneğin başarısız bir üretim) nedeniyle iade edilen jetonlar; reward — bonus, ödül veya destek tazminatı; reward_reversal — geri alınan bir ödül; exchange — tek bir işlemde zıt işaretli kalemlerle para birimleri arasında dönüşüm; expiry — süresi dolan jetonlar; migration — kendi sisteminizden taşınan bakiyeler; adjustment — uygulama içi ekonominin dışında teknik bir bakiye düzeltmesi.

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

Jetonların ne için harcandığı veya ne karşılığında verildiği. Bir kelime, isteğe bağlı olarak noktalı bir alt tür içerebilir: ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$ kalıbıyla eşleşmelidir. Gönderildiği şekilde saklanır, büyük/küçük harf duyarlıdır. Fiyat, katman, sürüm veya varyant kodlamayın. Örnek: power_up.extra_life.

customer_placement_idstring

Uygulamanızda işlemin gerçekleştiği ekran veya placement'ın kimliği. Bu sizin kendi kimliğinizdir, bir Adapty placement kimliği değildir. ^[a-zA-Z0-9_.-]{1,128}$ kalıbıyla eşleşmelidir. Gönderildiği şekilde saklanır. Örnek: onboarding-step-3.

reference_idstring

Sisteminizdeki ilgili nesnenin kimliği; örneğin bir üretim, ödül veya destek talebi. 1–128 karakter; kontrol, BIDI ve sıfır genişlikli karakterler reddedilir. Buraya kişisel veri koymayın. Örnek: ticket_48213.

is_sandboxboolean

Test sırasında verdiğiniz jetonlar için true olarak ayarlayın.

storestring

Bu işlemin atıfta bulunduğu satın almanın mağazası: app_store, play_store, stripe, paddle veya uygulamada yapılandırılmış özel bir mağazanın kimliği. En fazla 30 karakter. Satın alma mağazada iade edilirse, bu referansla yüklenen jetonlar geri alınır. store_transaction_id ile birlikte gönderin.

store_transaction_idstring

İlgili satın almanın mağaza işlem kimliği. En fazla 50 karakter. Yalnızca bir referanstır: Adapty bunun var olup olmadığını veya benzersiz olup olmadığını kontrol etmez. store ile birlikte gönderin.

Responses

İşlem oluşturuldu. Gövde, işlem geçmişinin bir öğesiyle aynı biçimde oluşturulan işlemi ve işlem sonrası bakiyeleri içerir.

Schema

Oluşturulan işlem, işlem geçmişinin bir öğesiyle aynı biçimde, artı işlem sonrası bakiyeler.

transaction_idstring

İşlemin benzersiz kimliği.

transaction_typestring

İşlemin kaynağı. store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund veya expiry değerlerinden biri.

itemsarray of object

Bu işlemde kaydedilen para birimi başına bakiye değişiklikleri.

currency_codestringrequired

Sanal para birimi kodu.

amountintegerrequired

Bakiyeye uygulanan işaretli değişim. Pozitif bir değer alacak, negatif bir değer borçtur.

balance_afterintegerrequired

Bu işlem uygulandıktan sonraki para birimi bakiyesi.

metadataobject

İşlemle birlikte saklanan anahtar-değer çiftleri (varsa).

operationstring

İşlemin ne anlama geldiği. Adapty bunu kendi işlemlerinde otomatik olarak belirler: store_purchase, subscription_renewal ve trial_start için top_up, refund için refund, expiry için expiry atanır. Bir dashboard_transaction söz konusu olduğunda, bir ekip üyesinin Adapty Kontrol Paneli'nde bakiyeyi ayarlarken seçtiği işlemdir. Bir api_transaction söz konusu olduğunda ise sizin gönderdiğiniz değerdir; hiçbir değer göndermemişseniz null olur.

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

Coinlerin ne için harcandığı veya ne karşılığında verildiği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.

customer_placement_idstring

Uygulamanızdaki ekran veya placement kimliği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.

reference_idstring

Kendi sisteminizdeki ilgili nesnenin kimliği; sizin gönderdiğiniz değerdir. Adapty tarafından oluşturulan işlemlerde null olur.

is_sandboxboolean

İşlemin test işlemi olup olmadığı. Adapty tarafından oluşturulan işlemlerde mağaza satın alımının ortamını izler. Bir api_transaction söz konusu olduğunda ise sizin gönderdiğiniz değerdir; varsayılan olarak false kabul edilir.

storestring

İlgili satın alımın mağazası. Adapty tarafından mağaza olaylarından (satın alma, yenileme, deneme, iade) oluşturulan işlemlerde ve bir satın alma referansıyla gönderilen api_transaction işlemlerinde doldurulur.

store_transaction_idstring

İlgili satın alımın mağaza işlem kimliği. store ile aynı işlemlerde doldurulur.

created_atstring

İşlemin kaydedildiği zaman.

response_created_atinteger

Yanıtın oluşturulduğu zaman, milisaniye cinsinden Unix zaman damgası olarak.

balancesarray of object

Bu istek tarafından etkilenen her para birimi için işlem sonrası bakiye (items içindeki her öğe için bir giriş). Profil için tam bakiye listesini okumak üzere GET /api/v2/server-side-api/vc/balances/ kullanın.

codestringrequired

Sanal para birimi kodu.

namestringrequired

Sanal para biriminin görünen adı.

balanceintegerrequired

Şu anda beklemede tutulan miktarlar dahil toplam bakiye.

heldintegerrequired

Tüm aktif beklemelerin toplamı (rezerve edilmiş miktarlar). Şu anda her zaman 0'dır.

availableintegerrequired

Harcanabilir bakiye; balance - held olarak hesaplanır.

Example
{
  "transaction_id": "019a7c3e-5b2a-7c1d-9e4f-0a1b2c3d4e5f",
  "transaction_type": "api_transaction",
  "items": [
    {
      "currency_code": "COINS",
      "amount": -10,
      "balance_after": 90
    }
  ],
  "metadata": null,
  "operation": "spend",
  "feature": "power_up.extra_life",
  "customer_placement_id": "level-complete",
  "reference_id": "session_7781",
  "is_sandbox": false,
  "store": null,
  "store_transaction_id": null,
  "created_at": "2026-11-12T10:00:00.123Z",
  "response_created_at": 1794477600123,
  "balances": [
    {
      "code": "COINS",
      "name": "Coins",
      "balance": 90,
      "held": 0,
      "available": 90
    }
  ]
}

Hatalı istek. error_code alanı nedeni tanımlar:

  • validation_error — gövde veya başlıklar geçersiz. Örneğin, bir etiketleme alanı biçimini bozuyor, items boş veya 20'den fazla girişe sahip, bir amount 0 ya da int32 aralığının dışında, bir para birimi kodu tekrarlanıyor, metadata kısıtlamalarını ihlal ediyor ya da ne adapty-profile-id ne de adapty-customer-user-id gönderilmiş. errors[].source alanı isimlendirir. store'un store_transaction_id olmadan gönderilmesi gibi birden fazla alanı kapsayan bir kontrol için source boş bir dizedir.
  • parse_error — gövde geçerli JSON değil.
  • idempotency_key_invalid — Idempotency-Key bir UUID v4 değil.
  • unknown_currency — para birimi uygulamada kurulu değil.
  • unknown_store — store uygulamada kurulu olmayan özel bir mağaza.
  • insufficient_balance — bir borçlandırma mevcut bakiyeyi aşıyor.
  • balance_overflow — bir alacaklandırma bakiyeyi int32 aralığının ötesine taşıyacak.
Schema
errorsarray of objectrequired
sourcestring

Hatanın kaynağı

errorsarray of string

Hata mesajları dizisi

error_codestringrequired

Kısa hata adı

status_codeintegerrequired

HTTP durum kodu

Example
{
  "errors": [
    {
      "source": "feature",
      "errors": [
        "String should match pattern '^[a-zA-Z0-9_]{1,32}(\\.[a-zA-Z0-9_]{1,32})?$'"
      ]
    }
  ],
  "error_code": "validation_error",
  "status_code": 400
}

Yetkisiz. API anahtarı eksik veya geçersiz (error_code değeri not_authenticated).

Schema
errorsarray of objectrequired
sourcestring

Hatanın kaynağı

errorsarray of string

Hata mesajları dizisi

error_codestringrequired

Kısa hata adı

status_codeintegerrequired

HTTP durum kodu

Profil bulunamadı (error_code değeri profile_does_not_exist).

Schema
errorsarray of objectrequired
sourcestring

Hatanın kaynağı

errorsarray of string

Hata mesajları dizisi

error_codestringrequired

Kısa hata adı

status_codeintegerrequired

HTTP durum kodu

Çakışma. Aynı Idempotency-Key ile bir istek hâlâ işleniyor (error_code değeri idempotency_in_flight). Retry-After yanıt başlığındaki aralıktan sonra yeniden deneyin.

Schema
errorsarray of objectrequired
sourcestring

Hatanın kaynağı

errorsarray of string

Hata mesajları dizisi

error_codestringrequired

Kısa hata adı

status_codeintegerrequired

HTTP durum kodu

Example
{
  "errors": [
    {
      "source": null,
      "errors": [
        "A similar request is being processed."
      ]
    }
  ],
  "error_code": "idempotency_in_flight",
  "status_code": 409
}

Çok fazla istek. Uygulama başına veya global istek sınırı aşıldı (error_code değeri rate_limited). Varsayılan sınırlar uygulama başına dakikada 600 istek ve global olarak dakikada 6000 istektir.

Schema
errorsarray of objectrequired
sourcestring

Hatanın kaynağı

errorsarray of string

Hata mesajları dizisi

error_codestringrequired

Kısa hata adı

status_codeintegerrequired

HTTP durum kodu

Dahili sunucu hatası