> 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/6.-hediye-bakiye/1.-olustur-wallet.md).

# 1. Oluştur (Wallet)

## Cüzdan 'Id' ile Hediye Bakiye Oluştur

<mark style="color:yellow;">`POST`</mark>`{{WalletUrl}}/api/v1/balance/gift`&#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 servislerine genel erişimi sağlayan ortak anahtar bilgisidir.</td></tr><tr><td>apiclientpublic</td><td>string</td><td>Evet</td><td>İstemci uygulamayı tanımlayan açık istemci anahtar bilgisidir.</td></tr></tbody></table>

</details>

<details>

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

<table><thead><tr><th width="166">Parametre</th><th width="105">Tip</th><th width="94">Zorunlu</th><th>Açıklama</th></tr></thead><tbody><tr><td>WalletId</td><td>Guid</td><td>Evet</td><td>Hediye bakiyenin tanımlanacağı cüzdan kimlik bilgisi</td></tr><tr><td>Amount</td><td>decimal</td><td>Evet</td><td>Tanımlanacak hediye bakiye</td></tr><tr><td>ExternalReference</td><td>string</td><td>Evet</td><td>İşlemin sisteminiz tarafından takip edilebilmesi için takip numarası</td></tr><tr><td>ExpirationDate</td><td>DateTime</td><td>Hayır</td><td>Eğer ilgili hediye bakiye belirli bir tarihe kadar geçerli olsun istiyorsanız. Tarih tanımı yapabilirsiniz.<br><br><mark style="color:purple;">Eğer tarih verirseniz,</mark> ilgili tutar o tarihe kadar harcanmazsa otomatik olarak kullanım dışı kalır.<br><br><mark style="color:orange;">Eğer tarih verilmezse,</mark> ilgili tutar kullanılana kadar cüzdanda tanımlı kalır</td></tr><tr><td>Description</td><td>string</td><td>Hayır</td><td>Verilen hediye bakiyenin açıklaması<br><br>Örnek: "Doğum günü"</td></tr><tr><td>ExternalTransactionTypeId</td><td>integer</td><td>Hayır</td><td>Kendi sisteminizdeki bir işlem tipini bizim sistemimize ekledikten sonra size verdiğimiz id.</td></tr><tr><td>ExternalTransactionTypeEnum</td><td>integer</td><td>Hayır</td><td>Kendi sisteminizdeki bir işlem tipini bizim sistemimize eklerken verdiğiniz unique değer.</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" %}

* `ExternalReference` aynı Merchant kapsamında benzersiz olmalıdır.
* Bir cüzdana en fazla 100 adet hediye bakiye tanımlanabilir. Bu limit aşıldığında yeni kayıt oluşturulamaz.
* Son kullanma tarihi belirtilmeden oluşturulan hediye bakiyeler süresiz kabul edilir. Dönüş modelinde `ExpirationDate` alanı boş, `IsUnlimited` alanı `true` olarak döner.
* Hediye bakiye başarıyla oluşturulduğunda sistem tarafından otomatik olarak `GiftBalanceAdded` tipinde bir işlem kaydı oluşturulur ve `ExternalReference` bu kayıtla ilişkilendirilir.
  {% endhint %}

</details>

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

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

```json
{
    "WalletId": "92858707-7718-435c-9ba3-3d702a3bea9b",
    "Amount": 100.00,
    "ExternalReference": "{{$guid}}",
    "ExpirationDate": "2025-11-11",
    "Description": "External Gift Balance",
    "ExternalTransactionTypeId" :null,
    "ExternalTransactionTypeEnum" : null
}
```

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

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

<details>

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

<table><thead><tr><th width="234.05859375">Parametre</th><th width="162.38671875">Tip</th><th width="348.94140625">Açıklama</th></tr></thead><tbody><tr><td>IsFailure</td><td>bool</td><td>İşlem başarısızsa false, değilse true döner.</td></tr><tr><td>IsSuccess</td><td>bool</td><td>İşlem başarılıysa true, aksi halde false döner.</td></tr><tr><td>Errors</td><td>Array</td><td>Oluşan hata detaylarını içeren dizi yapısıdır.</td></tr><tr><td>Value</td><td>Array</td><td>Sonuç verilerini içeren öğe listesini barındırır.</td></tr><tr><td>Id</td><td>Guid</td><td>Sistemde bu varlığı benzersiz şekilde tanımlayan kimliktir.</td></tr><tr><td>WalletId</td><td>Guid</td><td>Kaydın bağlı olduğu cüzdanın eşsiz ID bilgisidir.</td></tr><tr><td>Amount</td><td>string</td><td>Tanımlanan toplam bakiye bilgisini metinsel olarak tutar.</td></tr><tr><td>RemainingAmount</td><td>decimal</td><td>Mevcut bakiye içerisinden harcanmamış kalan kısmı ifade eder.</td></tr><tr><td>ExpirationDate</td><td>decimal</td><td>Bakiyenin sona ereceği tarihi timestamp formatında temsil eder.</td></tr><tr><td>IsUnlimited</td><td>string</td><td>Hediye bakiyenin süresiz olup olmadığını belirtir. <code>ExpirationDate</code> değeri <code>null</code> ise <code>true</code> döner ve hediye bakiyenin son kullanma tarihi olmadığını ifade eder.</td></tr><tr><td>Description</td><td>string</td><td>Bakiye veya işlemin açıklamasıdır, kullanıcıya bilgi verir.</td></tr><tr><td>LastTransactionId</td><td>Guid</td><td>Bu bakiyeyi kullanan son işlemin kimliğidir.</td></tr><tr><td>CreatedAt</td><td>Guid</td><td>Kaydın oluşturulma tarihidir (muhtemelen veri tipi DateTime olmalıdır).</td></tr><tr><td>UpdatedAt</td><td>int</td><td>Kaydın en son ne zaman güncellendiğini gösteren UNIX zaman damgasıdır.</td></tr></tbody></table>

</details>

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

```json
{
    "IsSuccess": true,
    "IsFailure": false,
    "Value": {
        "Id": "29bddd16-16d1-4b16-bca9-906f9ef80725",
        "WalletId": "7883fb19-2359-4a9b-b917-f08a259898ed",
        "Amount": 100.00,
        "RemainingAmount": 100.00,
        "ExpirationDate": "2025-11-10T21:00:00Z",
        "IsUnlimited": false,
        "Description": "External Gift Balance",
        "LastTransactionId": null,
        "CreatedAt": "2025-08-20T14:32:16.468416Z",
        "UpdatedAt": null
    }
}
```

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