# Чеки

> Чеки — ссылки, по которым пользователь забирает деньги с баланса приложения: методы createCheck, getChecks и deleteCheck.

Чек — ссылка, по которой пользователь заберёт деньги с баланса приложения. В отличие от [перевода](https://help.pswallet.org/ru/pay-api/transfers), для чека не нужно знать Telegram ID получателя: достаточно отправить ему ссылку. Чеки без комиссии.

## Как работают чеки

- Сумма чека удерживается на балансе приложения (`onhold` в [getBalance](https://help.pswallet.org/ru/pay-api/balance#getbalance)) до активации или удаления.
- Активировать чек можно в мини-приложении PS Wallet по ссылке `bot_check_url`. Деньги приходят на счёт пользователя в той же монете и сети.
- Каждый чек активируется один раз.
- Владелец приложения свои чеки активировать не может.
- Чек можно закрепить за конкретным пользователем по Telegram ID (`pin_to_user_id`) или username (`pin_to_username`) — тогда активировать его сможет только он.
- Неактивированный чек можно удалить — удержанная сумма вернётся на баланс приложения.

## Перед началом

Включите метод в кабинете приложения: «Безопасность» → «Создание чеков через API» (понадобится PIN-код). По умолчанию метод выключен, и запрос вернёт ошибку `403 METHOD_DISABLED`.

> [!WARNING]
> Любой, у кого есть токен приложения, сможет выводить деньги с баланса через чеки. Включайте метод, только если он действительно нужен. Подробнее — в разделе [Безопасность](https://help.pswallet.org/ru/pay-api/security).

## createCheck

Создать чек. Только `POST`. Возвращает [Check](https://help.pswallet.org/ru/pay-api/types#check). Ссылка для пользователя — `bot_check_url`.

| Параметр | Тип | Описание |
|---|---|---|
| `asset` | String | Обязательно. Монета: `USDT`, `USDT-TRC20`, `USDT-BEP20`, `USDT-ERC20`, `USDT-TON`, `XAUT`, `TRX`, `BNB`, `ETH`, `GRAM`. Рубли другим пользователям сейчас передать нельзя. |
| `amount` | String | Обязательно. Сумма. |
| `pin_to_user_id` | Number | Необязательно. Telegram ID — активировать сможет только этот пользователь. |
| `pin_to_username` | String | Необязательно. Username (без `@`, от 4 до 32 символов) — активировать сможет только этот пользователь. |

Если указать `asset=USDT`, сумма удержится в первой сети, где на балансе приложения её хватает: TRC20 → BEP20 → TON → ERC20. Сеть чека вернётся в поле `asset` ответа.

### Пример запроса

```bash title="cURL"
curl https://pay.pswallet.org/api/createCheck \
  -H "PSWallet-Pay-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asset": "USDT", "amount": "5", "pin_to_username": "example_user"}'
```

```js title="Node.js"
// Node.js 18+ (встроенный fetch)
const response = await fetch("https://pay.pswallet.org/api/createCheck", {
  method: "POST",
  headers: {
    "PSWallet-Pay-API-Token": process.env.PSWALLET_PAY_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    asset: "USDT",
    amount: "5",
    pin_to_username: "example_user",
  }),
});
const data = await response.json();
if (!data.ok) throw new Error(data.error.name);

const check = data.result;
// сохраните check.check_id и отправьте ссылку пользователю
console.log(check.bot_check_url);
```

```python title="Python"
import os
import requests

response = requests.post(
    "https://pay.pswallet.org/api/createCheck",
    headers={"PSWallet-Pay-API-Token": os.environ["PSWALLET_PAY_TOKEN"]},
    json={"asset": "USDT", "amount": "5", "pin_to_username": "example_user"},
    timeout=15,
)
data = response.json()
if not data["ok"]:
    raise RuntimeError(data["error"]["name"])

check = data["result"]
# сохраните check["check_id"] и отправьте ссылку пользователю
print(check["bot_check_url"])
```

Ответ:

```json
{
  "ok": true,
  "result": {
    "check_id": 77,
    "hash": "9b2f3c1e-4a5d-4e8f-9a7b-1c2d3e4f5a6b",
    "asset": "USDT-TRC20",
    "amount": "5",
    "bot_check_url": "https://t.me/pswallet?startapp=check-9b2f3c1e-4a5d-4e8f-9a7b-1c2d3e4f5a6b",
    "status": "active",
    "created_at": "2026-11-09T12:00:00.000+00:00",
    "pin_to_username": "example_user"
  }
}
```

### Ошибки createCheck

Код ответа — 400, если не указан другой.

- `403 METHOD_DISABLED` — метод не включён в разделе «Безопасность».
- `403 TRANSFERS_DISABLED` — переводы для владельца приложения ограничены.
- `403 APP_FROZEN` — приложение заморожено.
- `PARAM_ASSET_REQUIRED`, `PARAM_ASSET_INVALID` — не передана, неизвестна или сейчас недоступна монета.
- `PARAM_AMOUNT_REQUIRED`, `PARAM_AMOUNT_INVALID` — нет суммы, она не больше нуля или в ней больше знаков, чем у монеты.
- `PARAM_PIN_TO_USER_ID_INVALID` — неверный Telegram ID.
- `PARAM_PIN_TO_USERNAME_INVALID` — неверный username.
- `403 TEMPORARILY_UNAVAILABLE` — чек в этой монете сейчас создать нельзя (например, в рублях).
- `INSUFFICIENT_FUNDS` — на балансе приложения не хватает денег.

## getChecks

Список чеков приложения (без удалённых), сначала новые. Возвращает `{ "items": [Check, …] }`.

| Параметр | Тип | Описание |
|---|---|---|
| `asset` | String | Необязательно. Только чеки в этой монете (`USDT` — во всех сетях). |
| `check_ids` | String | Необязательно. ID чеков через запятую (учитываются первые 1000). |
| `status` | String | Необязательно. `active` или `activated`. |
| `offset` | Number | Необязательно. Сколько чеков пропустить. По умолчанию 0. |
| `count` | Number | Необязательно. Сколько вернуть, от 1 до 1000. По умолчанию 100. |

```bash title="cURL"
curl "https://pay.pswallet.org/api/getChecks?status=activated" \
  -H "PSWallet-Pay-API-Token: $TOKEN"
```

Ответ:

```json
{
  "ok": true,
  "result": {
    "items": [
      {
        "check_id": 77,
        "hash": "9b2f3c1e-4a5d-4e8f-9a7b-1c2d3e4f5a6b",
        "asset": "USDT-TRC20",
        "amount": "5",
        "bot_check_url": "https://t.me/pswallet?startapp=check-9b2f3c1e-4a5d-4e8f-9a7b-1c2d3e4f5a6b",
        "status": "activated",
        "created_at": "2026-11-09T12:00:00.000+00:00",
        "activated_at": "2026-11-09T12:03:41.000+00:00",
        "pin_to_username": "example_user"
      }
    ]
  }
}
```

Ошибки (код 400): `PARAM_ASSET_INVALID`, `PARAM_CHECK_IDS_INVALID`, `PARAM_STATUS_INVALID`, `PARAM_OFFSET_INVALID`, `PARAM_COUNT_INVALID`.

## deleteCheck

Удалить неактивированный чек. Только `POST`. Удержанная сумма возвращается на баланс приложения, а ссылка перестаёт работать.

| Параметр | Тип | Описание |
|---|---|---|
| `check_id` | Number | Обязательно. ID чека. |

Возвращает `true`.

```bash title="cURL"
curl https://pay.pswallet.org/api/deleteCheck \
  -H "PSWallet-Pay-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"check_id": 77}'
```

Ошибки (код 400, если не указан другой):

- `PARAM_CHECK_ID_REQUIRED`, `PARAM_CHECK_ID_INVALID` — не передан или неверный `check_id`.
- `404 CHECK_NOT_FOUND` — чек не найден или уже удалён.
- `CHECK_ALREADY_ACTIVATED` — чек уже активирован, удалить его нельзя.

---
Источник: https://help.pswallet.org/ru/pay-api/checks