# Creating a payment link

<mark style="color:green;">`POST`</mark> <https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/link>

{% hint style="danger" %}
**ATTENTION: New Error Response Format**\
In the near future, errors in our system will be classified as **expected** and **unexpected**. Depending on the type of error, the format of the JSON response will be changed. Please review the new formats on the [**Error Codes**](https://docs.tarlanpayments.kz/eng/agws/error-codes) page. This change will be applied to all APIs in the AGWS system **except** ''[Make a payment](https://docs.tarlanpayments.kz/eng/agws/make-a-payment)'.

Click [here ](#examples-of-error-responses-before-the-changes)to view the old and new JSON error responses. Please take note of this update and ensure your system is ready for these changes, if necessary.
{% endhint %}

**Headers**

| Name         | Value                                                                              |
| ------------ | ---------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                                 |
| X-Signature  | [Authorization hash](https://docs.tarlanpayments.kz/eng/agws/creating-a-signature) |

**Body**

| Name                                            | Type    | Description                                |
| ----------------------------------------------- | ------- | ------------------------------------------ |
| `agent`<mark style="color:red;">`*`</mark>      | String  | Showcase code in the Tarlanpayments system |
| `username`<mark style="color:red;">`*`</mark>   | String  | Username                                   |
| `amount`<mark style="color:red;">`*`</mark>     | Integer | Transaction amount                         |
| `service`<mark style="color:red;">`*`</mark>    | String  | Service name                               |
| `return_url`                                    | String  | Link to follow after payment               |
| `refer_host`<mark style="color:red;">`*`</mark> | String  | The domain from which the payment is made  |

**Response**

{% tabs %}
{% tab title="200: OK Example of a successful response" %}

```json
{
    "result": {
        "code": 0,
        "redirect_url": "https://kaspi.kz/pay/quickpayment?quick_pay_id=Betssonkzad1e50a5-6afd-481e-8e14-37487734ed292517:52:00",
        "message": "Успешно обработано",
        "qr_code_image": ""
    }
}
```

{% endtab %}
{% endtabs %}

#### Examples of error responses *before* the changes

{% tabs %}
{% tab title="404 Not Found" %}

```json
{
    "status": false,
    "status_code": 9718,
    "message": "provider not found",
    "result": {}
}
```

{% endtab %}

{% tab title="400 Bad Request" %}

```json
{
    "status": false,
    "status_code": 1014,
    "message": "Invalid signature",
    "result": {}
}
```

{% endtab %}
{% endtabs %}

#### Examples of error responses *after* the changes

{% tabs %}
{% tab title="200 OK: Expected error" %}

```json
{
    "status": true,
    "status_code": 0,
    "message": "Success",
    "result": {
        "error_code": 1881,
        "code": -1,
        "message": "provider doesn't exists",
        "redirect_url": "",
        "qr_code_image": ""
    }
}
```

{% endtab %}

{% tab title="400 Bad Request: Unexpected Error" %}

```json
{
    "status": false,
    "status_code": 1014,
    "message": "Invalid signature",
    "result": {}
}
```

{% endtab %}
{% endtabs %}

```
curl --location 'https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/link' \
--header 'X-Signature: qfqer1231' \
--header 'Content-Type: application/json' \
--data '{
    "agent": "test1",
    "username": "e41e6e7b-a0b9-46cf-ac10-bb8333fd6391",
    "amount": 10000,
    "service": "service1",
    "return_url": "https://www.youresite.com/",
    "refer_host": "site.kz"
}'
```