Checks

A check is a link that lets a user claim funds from the app's balance. Unlike a transfer, a check does not require the recipient's Telegram ID: just send them the link. Checks have no fees.

#How checks work

• The check amount is held on the app's balance (onhold in getBalance) until the check is activated or deleted.
• A check can be activated in the PS Wallet mini app via the bot_check_url link. The funds arrive in the user's account in the same coin and network.
• Each check can be activated only once.
• The app owner cannot activate their own checks.
• A check can be pinned to a specific user by Telegram ID (pin_to_user_id) or username (pin_to_username) — then only that user can activate it.
• An unactivated check can be deleted — the held amount returns to the app's balance.

#Before you start

Enable the method in the app dashboard: "Security" → "Create checks via API" (a PIN is required). The method is disabled by default, and the request will return the error 403 METHOD_DISABLED.

#createCheck

Create a check. POST only. Returns Check. The link for the user is bot_check_url.

If you specify asset=USDT, the amount is held in the first network where the app's balance has enough funds: TRC20 → BEP20 → TON → ERC20. The check's network is returned in the asset field of the response.

#Request example

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+ (built-in 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;
// save check.check_id and send the link to the user
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"]
# save check["check_id"] and send the link to the user
print(check["bot_check_url"])

Response:

{
  "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 errors

The response code is 400 unless otherwise specified.

• 403 METHOD_DISABLED — the method is not enabled in the "Security" section.
• 403 TRANSFERS_DISABLED — transfers are restricted for the app owner.
• 403 APP_FROZEN — the app is frozen.
• PARAM_ASSET_REQUIRED, PARAM_ASSET_INVALID — the coin is missing, unknown, or currently unavailable.
• PARAM_AMOUNT_REQUIRED, PARAM_AMOUNT_INVALID — the amount is missing, is not greater than zero, or has more decimal places than the coin allows.
• PARAM_PIN_TO_USER_ID_INVALID — invalid Telegram ID.
• PARAM_PIN_TO_USERNAME_INVALID — invalid username.
• 403 TEMPORARILY_UNAVAILABLE — a check in this coin cannot be created right now (for example, in rubles).
• INSUFFICIENT_FUNDS — the app's balance does not have enough funds.

#getChecks

List of the app's checks (excluding deleted ones), newest first. Returns { "items": [Check, …] }.

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

Response:

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

Errors (code 400): PARAM_ASSET_INVALID, PARAM_CHECK_IDS_INVALID, PARAM_STATUS_INVALID, PARAM_OFFSET_INVALID, PARAM_COUNT_INVALID.

#deleteCheck

Delete an unactivated check. POST only. The held amount returns to the app's balance, and the link stops working.

Returns true.

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

Errors (code 400 unless otherwise specified):

• PARAM_CHECK_ID_REQUIRED, PARAM_CHECK_ID_INVALID — check_id is missing or invalid.
• 404 CHECK_NOT_FOUND — the check was not found or has already been deleted.
• CHECK_ALREADY_ACTIVATED — the check has already been activated and cannot be deleted.