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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.paywall.one/cuzdan-servisleri/6.-hediye-bakiye/1.-olustur-wallet.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.