> 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/payment-orchestration-integration-document/wallet-services/6.-gift-balance/2.-create-alias.md).

# 2. Create (Alias)

## Create Gift Balance with Wallet 'Alias'

<mark style="color:yellow;">`POST`</mark>`{{WalletUrl}}/api/v1/balance/gift/by/wallet/alias`&#x20;

{% hint style="info" %}
**Note:** To use this service, it is mandatory to include the **apikeypublic** and **apiclientpublic** parameters in the Header field.

\
[<mark style="color:green;">**WalletAPI Address**</mark>](/payment-orchestration-integration-document/environment.md)
{% endhint %}

**The parameters that need to be sent to the service are as follows:**

<table><thead><tr><th width="162">Parameter</th><th width="106.9609375">Type</th><th width="137.27734375">Compolsory</th><th width="403">Description</th></tr></thead><tbody><tr><td>apikeypublic</td><td>string</td><td>Yes</td><td>It is the shared key information that provides general access to the API services.</td></tr><tr><td>apiclientpublic</td><td>string</td><td>Yes</td><td>It is the public client key information that identifies the client application.</td></tr></tbody></table>

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

```json
{
    "Alias": "2816220769",
    "Amount": 100.00,
    "ExternalReference": "{{$guid}}",
    "ExpirationDate": null,
    "Description": "External Gift Balance"
}
```

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

## Service Request

| Parameter         | Type      | Description                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alias             | string    | The wallet number where the gift balance will be assigned.                                                                                                                                                                                                                                                                                                       |
| Amount            | decimal   | The gift balance to be assigned.                                                                                                                                                                                                                                                                                                                                 |
| ExpirationDate    | DateTime? | <p>If you want the gift balance to be valid until a specific date, you can define a date.<br><br><mark style="color:purple;">If a date is provided</mark>, the amount will automatically become inactive if not spent by that date.<br><br><mark style="color:orange;">If no date is provided</mark>, the amount will remain in the wallet until it is used.</p> |
| Description       | string    | <p>The description of the given gift balance.</p><p></p><p>Example: "Birthday"</p>                                                                                                                                                                                                                                                                               |
| ExternalReference | string    | **Tracking number used by your system to track the transaction**                                                                                                                                                                                                                                                                                                 |

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

```json
{
    "IsSuccess": true,
    "IsFailure": false,
    "Value": {
        "Id": "47c4ec69-58d2-415c-841e-c1144542181b",
        "WalletId": "7883fb19-2359-4a9b-b917-f08a259898ed",
        "Amount": 100.00,
        "RemainingAmount": 100.00,
        "ExpirationDate": null,
        "IsUnlimited": true,
        "Description": "External Gift Balance",
        "LastTransactionId": null,
        "CreatedAt": "2025-08-20T14:33:15.741943Z",
        "UpdatedAt": null
    }
}
```

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

## Service Response

<table><thead><tr><th width="192">Parameter</th><th width="147.89192708333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>IsFailure</td><td>bool</td><td>It returns false if the transaction failed, and true if it was successful.</td></tr><tr><td>IsSuccess</td><td>bool</td><td>It returns true if the transaction was successful, and false if it failed.</td></tr><tr><td>Errors</td><td>Array</td><td>It is an array structure containing the error details that occurred.</td></tr><tr><td>Value</td><td>Array</td><td>It contains a list of items that hold the result data.</td></tr></tbody></table>

## Service Response (Value)

<table><thead><tr><th width="234.05859375">Parameter</th><th width="162.38671875">Type</th><th width="348.94140625">Description</th></tr></thead><tbody><tr><td>Id</td><td>Guid</td><td>It is the ID assigned by the system specifically for this record.</td></tr><tr><td>WalletId</td><td>Guid</td><td>It is the identity number that shows which wallet it is associated with.</td></tr><tr><td>Amount</td><td>string</td><td>It is the total amount assigned to the user (e.g., "100.00").</td></tr><tr><td>RemainingAmount</td><td>decimal</td><td>It is the current balance that the user can spend.</td></tr><tr><td>ExpirationDate</td><td>decimal</td><td>The last date this amount is valid.</td></tr><tr><td>IsUnlimited</td><td>string</td><td>It indicates whether the amount is valid indefinitely.</td></tr><tr><td>Description</td><td>string</td><td>The purpose or explanatory note of this amount.</td></tr><tr><td>IsUsed</td><td>DateTime</td><td>The time when the first spending transaction took place.</td></tr><tr><td>IsFullyUsed</td><td>DateTime</td><td>The time when the user has used the entire amount.</td></tr><tr><td>IsPartiallyUsed</td><td>decimal</td><td>The amount of the used portion (e.g., 25.50).</td></tr><tr><td>LastTransactionId</td><td>Guid</td><td>The unique ID number associated with the last transaction.</td></tr><tr><td>CreatedAt</td><td>Guid</td><td>The date when this record was created (should include the date information).</td></tr><tr><td>UpdatedAt</td><td>int</td><td>It specifies the time when the information was last updated.</td></tr></tbody></table>