18. Satış/Harcama (Wallet)

Cüzdan ile yapılan satış/harcama işlemlerini bu servis üzerinden yönetebilirsiniz

Cüzdan 'Id' ile Satış/Harcama

POST{{WalletUrl}}/api/v1/Wallet/purchase

Not: Bu servisin kullanılabilmesi için apikeypublic ve apiclientpublic parametrelerinin Header alanına eklenmiş olması zorunludur.

WalletAPI Adresi

Gerekli header ve istek parametreleri:

Zorunlu header parametreleri

Parametre	Tip	Zorunlu	Açıklama
apikeypublic	string	Evet	API'ye erişim için kullanılan genel anahtar.
apiclientpublic	string	Evet	API istemci kimliğini temsil eden genel anahtar.

İstek gövdesi parametreleri

Parametre	Tip	Zorunlu	Açıklama
Id	Guid	Evet	Satın alma işleminin yapılacağı cüzdanın benzersiz tanımlayıcısı.
Amount	decimal	Evet	Satın alma tutarı. Sıfırdan büyük olmalıdır.
Description	string	Hayır	İşleme ait açıklama veya not. Opsiyoneldir.
ExternalReference	string	Evet	Kendi sisteminizdeki işleme ait benzersiz referans numarası. Aynı referansın tekrar gönderilmesi durumunda işlem reddedilebilir
UseGiftBalances	bool	Evet	İlgili işlemin gerçekleştiği cüzdana tanımlı hediye bakiye varsa, bu bakiye kullanılsın mı?
CashbackApply	bool	Hayır	İşleme cashback uygulanıp uygulanmayacağını belirtir. Varsayılan: false
CashbackType	enum	Hayır	Cashback türü. Amount = Sabit tutar, Percentage = Yüzde
CashbackValue	decimal	Hayır	Cashback değeri. CashbackType = Amount ise tutar, Percentage ise yüzde değeri olarak belirtilir. Sıfır veya sıfırdan büyük olmalıdır
ExternalTransactionTypeId	Guid	Hayır	Kendi sisteminizdeki işlem tipini UUID olarak belirtir. ExternalTransactionTypeEnum ile birlikte kullanılabilir, ikisi birbirinin alternatifidir.
ExternalTransactionTypeEnum	string	Hayır	Kendi sisteminizdeki işlem tipini string olarak belirtir. ExternalTransactionTypeId ile birlikte kullanılabilir, ikisi birbirinin alternatifidir.

İş Kuralları

• Amount sıfırdan büyük olmalıdır.

• Id ile belirtilen cüzdan Merchant altında aktif olarak kayıtlı olmalıdır.

• ExternalReference aynı Merchant kapsamında benzersiz olmalıdır.

• Silinmiş veya dondurulmuş cüzdanlar üzerinde işlem gerçekleştirilemez.

• ExternalTransactionType gönderildiğinde sistemde tanımlı ve aktif olmalıdır. İlgili işlem tipine özel limitler uygulanır, genel satın alma limitleri dikkate alınmaz.

• ExternalTransactionType gönderilmediğinde genel satın alma limitleri uygulanır.

• İşlem öncesinde kullanılabilir bakiye, işlem tutarı ve varsa komisyon tutarını karşılamalıdır.

• Aynı cüzdana 2 saniye içinde tekrar gönderilen satın alma istekleri reddedilir.

• UseGiftBalances aktif ise önce son kullanma tarihi en yakın hediye bakiyeler tüketilir. İşlem tutarının tamamı hediye bakiye ile karşılanırsa standart satın alma işlemi oluşturulmaz.

• CashbackApply aktif ise işlem sonrasında yüzdesel veya sabit tutarlı cashback hesaplanır ve ayrı bir işlem olarak cüzdana yansıtılır.

• Aktif komisyon tanımı varsa komisyon tutarı işlem tutarıyla birlikte bakiyeden düşülür.

Servise gönderilecek örnek bir JSON dosyası şu şekildedir :

JSON

{
    "Id": "7883fb19-2359-4a9b-b917-f08a259898ed",
    "Amount": 1.00,
    "Description": "Satın alma işlemi",
    "ExternalReference": "4dcac110-5511-4cdf-9047-c27bfdb203fb",
    "UseGiftBalances": false,
    "CashbackApply": false,
    "CashbackType": "Percentage",
    "CashbackValue": 50,
    "ExternalTransactionTypeId": null,
    "ExternalTransactionTypeEnum": null
}

Servisten dönen parametreler şu şekildedir:

Parametreler ve açıklamaları

Parametre	Tip	Açıklama
Id	Guid	İşleme ait sistem tarafından üretilen benzersiz kimlik numarasıdır. UUID formatındadır.
WalletId	String	İşlemin yapıldığı cüzdanın sistemdeki kimlik numarasıdır. Hangi cüzdanla ilişkili olduğunu gösterir.
Alias	String	İşlemin yapıldığı cüzdanın alias'ı
TransactionType	String	İşlemin tipini belirtir. Örneğin "Ödeme", "İade", "Transfer" gibi işlemleri tanımlar.
Amount	Decimal	Gerçekleştirilen işlemin tutarıdır. Para birimi üzerinden ifade edilir.
GiftAmount	Decimal	İşlemde kullanılan hediye bakiye miktarıdır. Normal bakiyeden farklı olarak promosyonel kullanımı temsil eder.
Description	String	İşleme dair açıklayıcı bilgidir. Kullanıcı tarafından veya sistem tarafından yazılabilir.
ExternalReference	String	İşleme dış kaynaklı bir sistem üzerinden verilen referans numarasıdır. Genellikle entegrasyon sistemleri için kullanılır.
CreatedAt	DateTime	İşlemin oluşturulduğu tarih ve saat bilgisidir. UTC veya sistem saatine göre kaydedilir.
UpdatedAt	DateTime	İşlemin en son güncellendiği tarih ve saat bilgisidir. Bir değişiklik olduğunda güncellenir.
BalanceAfterTransaction	Decimal	İşlem gerçekleştikten sonra cüzdanda kalan bakiye miktarıdır. Hesap güncellemeleri sonrası değeri ifade eder.
BlockedBalanceAfterTransaction	Decimal	İşlem sonrası cüzdanın bloke bakiyesi.
AvailableBalanceAfterTransaction	Decimal	İşlem sonrası cüzdanın kullanılabilir bakiyesi.
GiftBalanceBalanceAfterTransaction	Decimal	İşlem sonrası cüzdanın toplam hediye bakiyesi.
CurrencyCode	String	İşlemin gerçekleştiği para birimi kodu.
SourceWalletId	Guid	Transfer işlemlerinde kaynak cüzdanın tanımlayıcısı
DestinationWalletId	Guid	Transfer işlemlerinde hedef cüzdanın tanımlayıcısı.
GiftBalanceId	Guid	Varsa işlemle ilişkili hediye bakiye kaydının tanımlayıcısı.
MainTransactionId	Guid	Varsa bu işlemin bağlı olduğu ana işlemin tanımlayıcısı
UniqueCode	String	İşleme ait benzersiz kod
UsedGiftBalances	array	İşlemde kullanılan hediye bakiyelerin listesi
UsedGiftBalances > Id	guid	Kullanılan hediye bakiye kaydının benzersiz tanımlayıcısı
UsedGiftBalances > Amount	decimal	Bu işlemde kullanılan hediye bakiye tutarı
UsedGiftBalances > ExpirationDate	datetime	Hediye bakiyenin son kullanma tarihi. null ise süresizdir
UsedGiftBalances > IsUnlimited	bool	ExpirationDate değeri null ise true döner, hediye bakiyenin süresiz olduğunu belirtir
UsedGiftBalances > Description	string	Hediye bakiyeye ait açıklama veya not
CashbackAmount	decimal	Varsa işleme ait cashback tutarı
ExternalTransactionTypeId	guid	Kendi sisteminizdeki işlem tipinin UUID tanımlayıcısı
ExternalTransactionTypeEnum	string	Kendi sisteminizdeki işlem tipinin string değeri
ExternalTransactionTypeName	string	Kendi sisteminizdeki işlem tipinin görünen adı

JSON

{
    "IsSuccess": true,
    "IsFailure": false,
    "Value": {
        "Id": "784f8d50-c2cc-4911-b82b-2f8f49a0b98f",
        "WalletId": "7883fb19-2359-4a9b-b917-f08a259898ed",
        "Alias": "2816220769",
        "TransactionType": "Purchase",
        "Amount": 1.00,
        "GiftAmount": null,
        "Description": "Satın alma işlemi",
        "ExternalReference": "4dcac110-5511-4cdf-9047-c27bfdb203fb",
        "CreatedAt": "2025-08-20T11:56:24.8210569Z",
        "UpdatedAt": null,
        "BalanceAfterTransaction": 99.00,
        "BlockedBalanceAfterTransaction": 0.00,
        "AvailableBalanceAfterTransaction": 99.00,
        "GiftBalanceBalanceAfterTransaction": 0.00,
        "CurrencyCode": "TRY",
        "SourceWalletId": null,
        "DestinationWalletId": null,
        "GiftBalanceId": null,
        "MainTransactionId": null,
        "UniqueCode": "bd0413e8-2a5f-4476-8617-57775655e322",
        "UsedGiftBalances": [
            {
                "Id": "aa230ce5-127d-44a0-b480-7f9c4a24a9fd",
                "Amount": 1.00,
                "ExpirationDate": "2025-12-31T23:59:59Z",
                "IsUnlimited": false,
                "Description": "Hoşgeldin bonusu"
            }
        ],
        "CashbackAmount": 0.00,
        "ExternalTransactionTypeId": null,
        "ExternalTransactionTypeEnum": null,
        "ExternalTransactionTypeName": null
    }
}