# Счета

> Создание, получение и удаление счетов на оплату в PS Wallet Pay API: createInvoice, getInvoices, deleteInvoice.

Счёт — запрос на оплату, который пользователь открывает по ссылке и оплачивает в PS Wallet. Сумма оплаты за вычетом [комиссии](https://help.pswallet.org/ru/pay-api/fees-and-limits) зачисляется на баланс приложения, а на ваш сервер приходит [вебхук](https://help.pswallet.org/ru/pay-api/webhooks) `invoice_paid`.

Счёт можно выставить в монете (`USDT`, `USDT-TRC20`, `TRX` и т. д.) или в фиате (`USD`, `RUB`) — тогда пользователь выберет монету для оплаты сам. Коды монет и правила записи сумм — в разделе [Монеты и суммы](https://help.pswallet.org/ru/pay-api/assets).

## Статусы счёта

| Статус | Что значит |
|---|---|
| `active` | Счёт ждёт оплаты. |
| `paid` | Счёт оплачен, деньги зачислены на баланс приложения. |
| `expired` | Истёк срок действия (`expires_in`), оплатить счёт больше нельзя. |

Удалённый через `deleteInvoice` счёт оплатить нельзя, и он пропадает из `getInvoices`.

## createInvoice

Создать счёт на оплату. Только `POST`. Возвращает [Invoice](https://help.pswallet.org/ru/pay-api/types#invoice).

| Параметр | Тип | Описание |
|---|---|---|
| `currency_type` | String | Необязательно. `crypto` (по умолчанию) или `fiat`. |
| `asset` | String | Обязательно при `currency_type=crypto`. Монета счёта: `USDT` (любая сеть), `USDT-TRC20`, `USDT-BEP20`, `USDT-ERC20`, `USDT-TON`, `XAUT`, `TRX`, `BNB`, `ETH`, `GRAM`. |
| `fiat` | String | Обязательно при `currency_type=fiat`. Валюта суммы: `USD` или `RUB`. |
| `accepted_assets` | String | Необязательно, только для `fiat`. Монеты для оплаты через запятую, например `USDT,TRX`. В JSON можно передать и массив. По умолчанию — `USDT,TRX,BNB,ETH,GRAM,RUB` (из них — доступные сейчас). |
| `amount` | String | Обязательно. Сумма в монете `asset` или в фиате `fiat`, например `125.50`. |
| `description` | String | Необязательно. Описание, которое увидит пользователь. До 1024 символов. |
| `hidden_message` | String | Необязательно. Сообщение, которое пользователь увидит после оплаты. До 2048 символов. |
| `paid_btn_name` | String | Необязательно. Кнопка на экране после оплаты: `viewItem`, `openChannel`, `openBot` или `callback` (см. ниже). |
| `paid_btn_url` | String | Обязательно, если указан `paid_btn_name`. Ссылка кнопки, начинается с `https://` или `http://`, до 512 символов. |
| `payload` | String | Необязательно. Любые ваши данные (например, номер заказа), до 4 КБ. Вернутся в счёте и в вебхуке. |
| `allow_comments` | Boolean | Необязательно. Разрешить пользователю оставить комментарий к оплате. По умолчанию `true`. |
| `allow_anonymous` | Boolean | Необязательно. Разрешить оплатить анонимно: имя плательщика не будет видно в истории приложения. По умолчанию `true`. |
| `expires_in` | Number | Необязательно. Время жизни счёта в секундах, от 1 до 2678400 (31 день). По умолчанию счёт бессрочный. |

Логические параметры принимают `true`/`false`, а также `1`/`0` — удобно для `application/x-www-form-urlencoded`.

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

```bash title="cURL"
curl https://pay.pswallet.org/api/createInvoice \
  -H "PSWallet-Pay-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT",
    "amount": "12.5",
    "description": "Подписка на месяц",
    "payload": "order-1042",
    "expires_in": 3600
  }'
```

```js title="Node.js"
// Node.js 18+ (встроенный fetch)
const response = await fetch("https://pay.pswallet.org/api/createInvoice", {
  method: "POST",
  headers: {
    "PSWallet-Pay-API-Token": process.env.PSWALLET_PAY_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    asset: "USDT",
    amount: "12.5",
    description: "Подписка на месяц",
    payload: "order-1042",
    expires_in: 3600,
  }),
});
const data = await response.json();
if (!data.ok) throw new Error(data.error.name);

const invoice = data.result;
// сохраните invoice.invoice_id рядом с заказом и отправьте ссылку пользователю
console.log(invoice.bot_invoice_url);
```

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

response = requests.post(
    "https://pay.pswallet.org/api/createInvoice",
    headers={"PSWallet-Pay-API-Token": os.environ["PSWALLET_PAY_TOKEN"]},
    json={
        "asset": "USDT",
        "amount": "12.5",
        "description": "Подписка на месяц",
        "payload": "order-1042",
        "expires_in": 3600,
    },
    timeout=15,
)
data = response.json()
if not data["ok"]:
    raise RuntimeError(data["error"]["name"])

invoice = data["result"]
# сохраните invoice["invoice_id"] рядом с заказом и отправьте ссылку пользователю
print(invoice["bot_invoice_url"])
```

Ответ:

```json
{
  "ok": true,
  "result": {
    "invoice_id": 528,
    "hash": "IVq3Lm9TzR4wXkPa",
    "currency_type": "crypto",
    "asset": "USDT",
    "amount": "12.5",
    "bot_invoice_url": "https://t.me/pswallet?start=IVq3Lm9TzR4wXkPa",
    "mini_app_invoice_url": "https://t.me/pswallet?startapp=IVq3Lm9TzR4wXkPa",
    "web_app_invoice_url": "https://t.me/pswallet?startapp=IVq3Lm9TzR4wXkPa",
    "pay_url": "https://t.me/pswallet?start=IVq3Lm9TzR4wXkPa",
    "description": "Подписка на месяц",
    "status": "active",
    "created_at": "2026-10-28T15:51:21.000+00:00",
    "allow_comments": true,
    "allow_anonymous": true,
    "expiration_date": "2026-10-28T16:51:21.000+00:00",
    "payload": "order-1042",
    "paid_anonymously": false
  }
}
```

Отправьте пользователю `bot_invoice_url` (счёт откроется в чате бота с кнопкой оплаты) или `mini_app_invoice_url` (сразу экран оплаты в мини-приложении).

> [!TIP]
> Передавайте в `payload` номер заказа: он вернётся в вебхуке `invoice_paid`, и заказ будет легко найти без отдельной таблицы соответствий.

### Счёт в долларах или рублях

Чтобы выставить счёт в фиате, передайте `currency_type=fiat`, валюту `fiat` и, если нужно, список монет `accepted_assets`:

```json
{
  "currency_type": "fiat",
  "fiat": "USD",
  "amount": "9.99",
  "accepted_assets": "USDT,TRX",
  "description": "Премиум на месяц"
}
```

Пользователь выберет монету из разрешённых, а сумма пересчитается по курсу в момент оплаты. Подробнее — в разделе [Монеты и суммы](https://help.pswallet.org/ru/pay-api/assets#счета-в-долларах-и-рублях).

> [!NOTE]
> Если в `accepted_assets` есть монета, которая сейчас недоступна, вернётся ошибка `PARAM_ACCEPTED_ASSETS_INVALID`. Рубли (`RUB`) при оплате сейчас не учитываются, а список только из `RUB` тоже вернёт эту ошибку.

### Кнопка после оплаты

После оплаты пользователь увидит экран с сообщением `hidden_message` (если задано) и кнопкой, которая ведёт на `paid_btn_url`:

| `paid_btn_name` | Текст кнопки |
|---|---|
| `viewItem` | «Открыть товар» |
| `openChannel` | «Открыть канал» |
| `openBot` | «Открыть бота» |
| `callback` | «Вернуться» |

### Ошибки createInvoice

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

- `PARAM_CURRENCY_TYPE_INVALID` — `currency_type` не `crypto` и не `fiat`.
- `PARAM_ASSET_REQUIRED`, `PARAM_ASSET_INVALID` — не передана, неизвестна или сейчас недоступна монета `asset`.
- `PARAM_FIAT_REQUIRED`, `PARAM_FIAT_INVALID` — не передана или неизвестна валюта `fiat`.
- `PARAM_ACCEPTED_ASSETS_INVALID` — неверный список `accepted_assets`.
- `PARAM_AMOUNT_REQUIRED`, `PARAM_AMOUNT_INVALID` — нет суммы, она не больше нуля или в ней больше знаков, чем у монеты.
- `PARAM_DESCRIPTION_INVALID`, `PARAM_HIDDEN_MESSAGE_INVALID`, `PARAM_PAYLOAD_INVALID` — текст длиннее допустимого.
- `PARAM_PAID_BTN_NAME_INVALID`, `PARAM_PAID_BTN_URL_REQUIRED`, `PARAM_PAID_BTN_URL_INVALID` — неверная кнопка после оплаты.
- `PARAM_ALLOW_COMMENTS_INVALID`, `PARAM_ALLOW_ANONYMOUS_INVALID` — не логическое значение.
- `PARAM_EXPIRES_IN_INVALID` — `expires_in` не целое число от 1 до 2678400.
- `403 APP_FROZEN` — приложение заморожено.

## getInvoices

Список счетов приложения, сначала новые. Удалённые счета не возвращаются. Возвращает объект `{ "items": [Invoice, …] }`.

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

```bash title="cURL"
curl "https://pay.pswallet.org/api/getInvoices?status=paid&count=10" \
  -H "PSWallet-Pay-API-Token: $TOKEN"
```

Ответ:

```json
{
  "ok": true,
  "result": {
    "items": [
      {
        "invoice_id": 528,
        "hash": "IVq3Lm9TzR4wXkPa",
        "currency_type": "crypto",
        "asset": "USDT",
        "amount": "12.5",
        "status": "paid",
        "paid_asset": "USDT-TRC20",
        "paid_amount": "12.5",
        "paid_usd_rate": "1",
        "fee_asset": "USDT-TRC20",
        "fee_amount": 0.375,
        "paid_at": "2026-10-28T15:51:22.000+00:00",
        "paid_anonymously": false,
        "payload": "order-1042"
      }
    ]
  }
}
```

В примере показана часть полей. Полный список — в описании типа [Invoice](https://help.pswallet.org/ru/pay-api/types#invoice).

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

## deleteInvoice

Удалить счёт. Только `POST`. После удаления оплатить его нельзя, и он пропадает из `getInvoices`. Оплаченный счёт удалить нельзя.

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

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

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

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

- `PARAM_INVOICE_ID_REQUIRED`, `PARAM_INVOICE_ID_INVALID` — не передан или неверный `invoice_id`.
- `404 INVOICE_NOT_FOUND` — счёт не найден или уже удалён.
- `INVOICE_PAID` — счёт уже оплачен.

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