> For the complete documentation index, see [llms.txt](https://developer.paywall.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.paywall.one/cuzdan-servisleri/2.-cuzdan/18.-satis-harcama-wallet.md).

# 18. Satış/Harcama (Wallet)

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

<mark style="color:yellow;">`POST`</mark>`{{WalletUrl}}/api/v1/Wallet/purchase`&#x20;

{% hint style="info" %}
Not: Bu servisin kullanılabilmesi için **apikeypublic** ve **apiclientpublic** parametrelerinin Header alanına eklenmiş olması zorunludur.

\
[<mark style="color:green;">**WalletAPI Adresi**</mark>](/ortam.md)
{% endhint %}

**Gerekli header ve istek parametreleri:**

<details>

<summary><strong>Zorunlu header parametreleri</strong></summary>

<table><thead><tr><th width="162">Parametre</th><th width="79">Tip</th><th width="107">Zorunlu</th><th width="403">Açıklama</th></tr></thead><tbody><tr><td>apikeypublic</td><td>string</td><td>Evet</td><td>API'ye erişim için kullanılan genel anahtar.</td></tr><tr><td>apiclientpublic</td><td>string</td><td>Evet</td><td>API istemci kimliğini temsil eden genel anahtar.</td></tr></tbody></table>

</details>

<details>

<summary><strong>İstek gövdesi parametreleri</strong></summary>

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

</details>

<details>

<summary><i class="fa-memo-circle-info">:memo-circle-info:</i>   <mark style="color:blue;"><strong><code>İş Kuralları</code></strong></mark></summary>

{% hint style="info" %}

* `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.
  {% endhint %}

</details>

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

{% tabs %}
{% tab title="JSON" %}

```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
}
```

{% endtab %}
{% endtabs %}

**Servisten dönen parametreler şu şekildedir:**

<details>

<summary><strong>Parametreler ve açıklamaları</strong></summary>

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

</details>

{% tabs %}
{% tab title="JSON" %}
{% code lineNumbers="true" %}

```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
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}