Чеки

Чек — ссылка, по которой пользователь заберёт деньги с баланса приложения. В отличие от перевода, для чека не нужно знать Telegram ID получателя: достаточно отправить ему ссылку. Чеки без комиссии.

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

• Сумма чека удерживается на балансе приложения (onhold в getBalance) до активации или удаления.
• Активировать чек можно в мини-приложении PS Wallet по ссылке bot_check_url. Деньги приходят на счёт пользователя в той же монете и сети.
• Каждый чек активируется один раз.
• Владелец приложения свои чеки активировать не может.
• Чек можно закрепить за конкретным пользователем по Telegram ID (pin_to_user_id) или username (pin_to_username) — тогда активировать его сможет только он.
• Неактивированный чек можно удалить — удержанная сумма вернётся на баланс приложения.

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

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

#createCheck

Создать чек. Только POST. Возвращает Check. Ссылка для пользователя — bot_check_url.

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

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

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"}'

// 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);

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"])

Ответ:

{
  "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, …] }.

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

Ответ:

{
  "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. Удержанная сумма возвращается на баланс приложения, а ссылка перестаёт работать.

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

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 — чек уже активирован, удалить его нельзя.