# Object types

> Fields of PS Wallet Pay API objects: Invoice, Transfer, Check, Balance, ExchangeRate, Currency, AppStats, and Update.

Objects returned by API methods and webhooks. Amounts are strings with a decimal point (except `fee_amount` in Invoice and the AppStats fields), dates are ISO 8601 strings. Fields that are not set are omitted from the response.

## Invoice

An invoice for payment. Returned by [createInvoice](https://help.pswallet.org/en/pay-api/invoices#createinvoice), [getInvoices](https://help.pswallet.org/en/pay-api/invoices#getinvoices), and the `invoice_paid` webhook.

| Field | Type | Description |
|---|---|---|
| `invoice_id` | Number | Invoice ID. Shown in the dashboard and to the user as `#IV528`. |
| `hash` | String | Invoice hash, also part of payment links. |
| `currency_type` | String | `crypto` or `fiat`. |
| `asset` | String | `crypto` only. Invoice coin (`USDT` — any network). |
| `fiat` | String | `fiat` only. Currency of the amount. |
| `accepted_assets` | String | `fiat` only. Allowed coins, comma-separated. |
| `amount` | String | Invoice amount in `asset` or `fiat`. |
| `paid_asset` | String | Paid invoice. What was paid with — coin code with network: `USDT-TRC20`, `USDT-BEP20`, `USDT-ERC20`, `USDT-TON`, `XAUT`, `TRX`, `BNB`, `ETH`, `GRAM`, or `RUB`. The funds were credited to the app balance in this coin. |
| `paid_amount` | String | Paid invoice. How much was debited from the user in `paid_asset`. |
| `paid_fiat_rate` | String | Paid fiat invoice. Rate of `paid_asset` to `fiat` at the time of payment. |
| `paid_usd_rate` | String | Paid invoice. Rate of `paid_asset` to USD at the time of payment. |
| `fee_asset` | String | Paid invoice. Fee coin (= `paid_asset`). |
| `fee_amount` | Number | Paid invoice. PS Wallet Pay fee. `paid_amount − fee_amount` was credited to the app balance. |
| `bot_invoice_url` | String | Link to the invoice in the bot chat. |
| `mini_app_invoice_url` | String | Link directly to the payment screen in the mini app. |
| `web_app_invoice_url` | String | Same as `mini_app_invoice_url`. |
| `pay_url` | String | Same as `bot_invoice_url`. |
| `description` | String | Description, if set. |
| `status` | String | `active`, `paid`, or `expired`. |
| `created_at` | String | Creation date, ISO 8601. |
| `allow_comments` | Boolean | Whether a comment can be left. |
| `allow_anonymous` | Boolean | Whether the invoice can be paid anonymously. |
| `expiration_date` | String | Expiration date, ISO 8601, if `expires_in` is set. |
| `paid_at` | String | Paid invoice. Payment date, ISO 8601. |
| `paid_anonymously` | Boolean | Whether the invoice was paid anonymously. |
| `comment` | String | User's comment on the payment, if left. |
| `hidden_message` | String | Message shown after payment, if set. |
| `payload` | String | Your data, if set. |
| `paid_btn_name` | String | Button after payment, if set. |
| `paid_btn_url` | String | Link of the button after payment. |

## Transfer

A transfer to a user. Returned by [transfer](https://help.pswallet.org/en/pay-api/transfers#transfer) and [getTransfers](https://help.pswallet.org/en/pay-api/transfers#gettransfers).

| Field | Type | Description |
|---|---|---|
| `transfer_id` | Number | Transfer ID. |
| `spend_id` | String | Your transfer identifier. |
| `user_id` | String | Recipient's Telegram ID. |
| `asset` | String | Coin with network (`USDT-TRC20`, …). |
| `amount` | String | Amount. |
| `status` | String | Always `completed`: transfers are processed instantly. |
| `completed_at` | String | Transfer date, ISO 8601. |
| `comment` | String | Comment, if set. |

## Check

A check. Returned by [createCheck](https://help.pswallet.org/en/pay-api/checks#createcheck) and [getChecks](https://help.pswallet.org/en/pay-api/checks#getchecks).

| Field | Type | Description |
|---|---|---|
| `check_id` | Number | Check ID. |
| `hash` | String | Check hash. |
| `asset` | String | Coin with network. |
| `amount` | String | Amount. |
| `bot_check_url` | String | Activation link. |
| `status` | String | `active` or `activated`. |
| `created_at` | String | Creation date, ISO 8601. |
| `activated_at` | String | Activation date, ISO 8601. |
| `pin_to_user_id` | Number | Set if the check is for one user only, by Telegram ID. |
| `pin_to_username` | String | Set if the check is for one user only, by username. |

## Balance

The app balance in one coin. Returned by [getBalance](https://help.pswallet.org/en/pay-api/balance#getbalance).

| Field | Type | Description |
|---|---|---|
| `currency_code` | String | Coin with network. |
| `available` | String | Available for transfers, checks, and withdrawal. |
| `onhold` | String | Held for non-activated checks. |

## ExchangeRate

A coin exchange rate. Returned by [getExchangeRates](https://help.pswallet.org/en/pay-api/balance#getexchangerates).

| Field | Type | Description |
|---|---|---|
| `is_valid` | Boolean | The rate is up to date. If `false`, the rate source is temporarily unavailable. |
| `is_crypto` | Boolean | `source` is a cryptocurrency. |
| `is_fiat` | Boolean | `source` is a fiat currency. |
| `source` | String | Coin: `USDT`, `XAUT`, `TRX`, `BNB`, `ETH`, `GRAM`, or `RUB`. |
| `target` | String | Currency: `USD` or `RUB`. |
| `rate` | String | Price of one unit of `source` in `target`. |

## Currency

A coin or currency accepted by the API. Returned by [getCurrencies](https://help.pswallet.org/en/pay-api/balance#getcurrencies).

| Field | Type | Description |
|---|---|---|
| `is_blockchain` | Boolean | Cryptocurrency. |
| `is_stablecoin` | Boolean | Stablecoin. |
| `is_fiat` | Boolean | Fiat currency. |
| `name` | String | Name. |
| `code` | String | Code for API parameters. |
| `decimals` | Number | Number of decimal places. |

## AppStats

App statistics for a period. Returned by [getStats](https://help.pswallet.org/en/pay-api/balance#getstats).

| Field | Type | Description |
|---|---|---|
| `volume` | Number | Turnover of paid invoices for the period in USD. |
| `conversion` | Number | Share of paid invoices among those created during the period (0–1). |
| `unique_users_count` | Number | Number of different users who paid invoices. |
| `created_invoice_count` | Number | Invoices created. |
| `paid_invoice_count` | Number | Invoices paid. |
| `start_at` | String | Start of the period, ISO 8601. |
| `end_at` | String | End of the period, ISO 8601. |

## Update

An event that PS Wallet Pay sends to your server via a [webhook](https://help.pswallet.org/en/pay-api/webhooks).

| Field | Type | Description |
|---|---|---|
| `update_id` | Number | Event ID. For `invoice_paid` it equals `invoice_id`, for `test` it is 0. |
| `update_type` | String | `invoice_paid` — invoice paid; `test` — test webhook from the dashboard. |
| `request_date` | String | Time this attempt was sent, ISO 8601. |
| `payload` | Object | For `invoice_paid` — the paid [Invoice](#invoice). For `test` — `{ "app_id": …, "name": … }`. |

---
Source: https://help.pswallet.org/en/pay-api/types