Accept crypto payments via the TgPay Merchant API — invoices, subscriptions, webhooks.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Merchant API token. Optional — without it the connect tool issues a scoped token after one-tap approval in the TgPay Telegram bot.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Stop new signups for a plan (live subscriptions keep renewing).
The plan to archive.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Stop new signups for a plan (live subscriptions keep renewing).
| Argument | Type | Description |
|---|---|---|
| plan_id* | integer | The plan to archive. |
{
"type": "object",
"required": [
"plan_id"
],
"properties": {
"plan_id": {
"type": "integer",
"description": "The plan to archive."
}
}
}Stop future charges for one subscription (paid time runs out).
| Argument | Type | Description |
|---|---|---|
| subscription_id* | integer | The subscription. |
{
"type": "object",
"required": [
"subscription_id"
],
"properties": {
"subscription_id": {
"type": "integer",
"description": "The subscription."
}
}
}Start token issuance WITHOUT the Mini App UI: creates a merchant-app request and returns a t.me approve link plus a poll_secret. Show the link to the human — they approve with one button in the @tgpaycryptobot bot — then call connect_status with the poll_secret. Use only when no API token is configured yet.
| Argument | Type | Description |
|---|---|---|
| app_name* | string | Merchant app name shown to the approving human, 1-64 chars (e.g. the project/bot name). |
{
"type": "object",
"required": [
"app_name"
],
"properties": {
"app_name": {
"type": "string",
"description": "Merchant app name shown to the approving human, 1-64 chars (e.g. the project/bot name)."
}
}
}Poll a connect request. Returns pending | denied | expired, or — once approved — the app id and the API TOKEN (returned exactly once: save it to the project's .env immediately, never print it in logs). The token is SCOPED (read, invoices, subscriptions, webhooks) — it cannot move money out of the app; transfers/refunds/checks need the primary token the human holds in the Mini App. Poll every 3-5 seconds while pending.
| Argument | Type | Description |
|---|---|---|
| poll_secret* | string | The poll_secret from the connect tool. |
{
"type": "object",
"required": [
"poll_secret"
],
"properties": {
"poll_secret": {
"type": "string",
"description": "The poll_secret from the connect tool."
}
}
}Create a one-off payment invoice; the payer opens result.mini_app_invoice_url. See the invoices doc.
| Argument | Type | Description |
|---|---|---|
| fiat | string | Fiat code (fiat mode). |
| asset | string | Asset code (crypto mode). |
| amount | string | Decimal string in MAJOR units, e.g. "5" = 5 USDT. Never a float. Omit for an open-amount invoice. |
| payload | string | Opaque data echoed back in the webhook (≤4096). |
| swap_to | string | Auto-convert the received amount to this asset. |
| expires_in | integer | Invoice TTL in seconds. |
| description | string | Shown to the payer (≤1024). |
| paid_btn_url | string | URL for the paid button. |
| currency_type | string | crypto (default) | fiat. |
| paid_btn_name | string | viewItem | openChannel | openBot | callback. |
Create an IMMUTABLE recurring-billing plan; send payers to result.mini_app_subscribe_url. See the subscriptions doc.
| Argument | Type | Description |
|---|---|---|
| name* | string | Plan name shown to payers (≤64). |
| asset* | string | Asset code, e.g. USDT. |
| amount* | string | Decimal string in MAJOR units, e.g. "5" = 5 USDT. Never a float. Charged per period. |
| period_days* | integer | Billing period in days. |
{
"type": "object",
"required": [
"name",
"asset",
"amount",
"period_days"
],
"properties": {
"name": {
"type": "string",
"description": "Plan name shown to payers (≤64)."
},
"asset": {
"type": "string",
"description": "Asset code, e.g. USDT."
},
"amount": {
"type": "string",
"description": "Decimal string in MAJOR units, e.g. \"5\" = 5 USDT. Never a float. Charged per period."
},
"period_days": {
"type": "integer",
"description": "Billing period in days."
}
}
}Delete an unclaimed check (refunds the hold).
| Argument | Type | Description |
|---|---|---|
| check_id* | integer | The check to delete. |
{
"type": "object",
"required": [
"check_id"
],
"properties": {
"check_id": {
"type": "integer",
"description": "The check to delete."
}
}
}Delete an unpaid invoice.
| Argument | Type | Description |
|---|---|---|
| invoice_id* | integer | The invoice to delete. |
{
"type": "object",
"required": [
"invoice_id"
],
"properties": {
"invoice_id": {
"type": "integer",
"description": "The invoice to delete."
}
}
}Merchant app balance per asset (available + onhold).
No arguments.
{
"type": "object",
"properties": {}
}List checks.
| Argument | Type | Description |
|---|---|---|
| asset | string | Filter by asset code. |
| count | integer | Page size (default 100). |
| offset | integer | Skip this many. |
| status | string | active | activated. |
| check_ids | string | Comma-separated ids. |
{
"type": "object",
"properties": {
"asset": {
"type": "string",
"description": "Filter by asset code."
},
"count": {
"type": "integer",
"description": "Page size (default 100)."
},
"offset": {
"type": "integer",
"description": "Skip this many."
},
"status": {
"type": "string",
"description": "active | activated."
},
"check_ids": {
"type": "string",
"description": "Comma-separated ids."
}
}
}Supported crypto assets (code/name/decimals) and fiats.
No arguments.
{
"type": "object",
"properties": {}
}Current asset↔fiat display rates.
No arguments.
{
"type": "object",
"properties": {}
}List invoices (newest first).
| Argument | Type | Description |
|---|---|---|
| fiat | string | Filter by fiat code. |
| asset | string | Filter by asset code. |
| count | integer | Page size (default 100). |
| offset | integer | Skip this many. |
| status | string | active | paid | expired. |
| invoice_ids | string | Comma-separated ids. |
{
"type": "object",
"properties": {
"fiat": {
"type": "string",
"description": "Filter by fiat code."
},
"asset": {
"type": "string",
"description": "Filter by asset code."
},
"count": {
"type": "integer",
"description": "Page size (default 100)."
},
"offset": {
"type": "integer",
"description": "Skip this many."
},
"status": {
"type": "string",
"description": "active | paid | expired."
},
"invoice_ids": {
"type": "string",
"description": "Comma-separated ids."
}
}
}Verify the token: app id, name, webhook config, token scopes.
No arguments.
{
"type": "object",
"properties": {}
}App volume/count stats for a period.
| Argument | Type | Description |
|---|---|---|
| end_at | string | ISO 8601 period end. |
| start_at | string | ISO 8601 period start. |
{
"type": "object",
"properties": {
"end_at": {
"type": "string",
"description": "ISO 8601 period end."
},
"start_at": {
"type": "string",
"description": "ISO 8601 period start."
}
}
}List subscription plans.
No arguments.
{
"type": "object",
"properties": {}
}List subscriptions (subscribers).
| Argument | Type | Description |
|---|---|---|
| status | string | active | grace | cancelled | expired. |
| plan_id | integer | Filter by plan. |
| user_id | integer | Filter by Telegram user id. |
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "active | grace | cancelled | expired."
},
"plan_id": {
"type": "integer",
"description": "Filter by plan."
},
"user_id": {
"type": "integer",
"description": "Filter by Telegram user id."
}
}
}List app→user transfers.
| Argument | Type | Description |
|---|---|---|
| asset | string | Filter by asset code. |
| count | integer | Page size (default 100). |
| offset | integer | Skip this many. |
| spend_id | string | Filter by idempotency key. |
| transfer_ids | string | Comma-separated ids. |
{
"type": "object",
"properties": {
"asset": {
"type": "string",
"description": "Filter by asset code."
},
"count": {
"type": "integer",
"description": "Page size (default 100)."
},
"offset": {
"type": "integer",
"description": "Skip this many."
},
"spend_id": {
"type": "string",
"description": "Filter by idempotency key."
},
"transfer_ids": {
"type": "string",
"description": "Comma-separated ids."
}
}
}Read a TgPay Merchant API integration doc. START HERE before integrating: topics quickstart, invoices, subscriptions, transfers-checks, webhooks, errors.
| Argument | Type | Description |
|---|---|---|
| topic* | string | quickstart | invoices | subscriptions | transfers-checks | webhooks | errors |
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"description": "quickstart | invoices | subscriptions | transfers-checks | webhooks | errors"
}
}
}Update app name / webhook_url (https) / webhook_events opt-in list. Needs the 'webhooks' scope (the connect-issued token has it) or the primary token. See the webhooks doc for the event types and signature verification.
| Argument | Type | Description |
|---|---|---|
| name | string | New app name (1-64). |
| webhook_url | string | https URL for webhook delivery; "" clears it. |
| webhook_events | array | Extended event types to opt into (invoice_paid is always delivered); [] = invoice_paid-only. |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New app name (1-64)."
},
"webhook_url": {
"type": "string",
"description": "https URL for webhook delivery; \"\" clears it."
},
"webhook_events": {
"type": "array",
"items": {
"type": "string",
"description": "Event type."
},
"description": "Extended event types to opt into (invoice_paid is always delivered); [] = invoice_paid-only."
}
}
}| allow_comments |
| boolean |
| Default true. |
| hidden_message | string | Revealed to the payer ONLY after payment (≤2048). |
| accepted_assets | string | Fiat mode: comma-separated assets the payer may pay in. |
| allow_anonymous | boolean | Default true. |
| rate_lock_seconds | integer | Fiat mode: freeze crypto quotes for this long. |
{
"type": "object",
"properties": {
"fiat": {
"type": "string",
"description": "Fiat code (fiat mode)."
},
"asset": {
"type": "string",
"description": "Asset code (crypto mode)."
},
"amount": {
"type": "string",
"description": "Decimal string in MAJOR units, e.g. \"5\" = 5 USDT. Never a float. Omit for an open-amount invoice."
},
"payload": {
"type": "string",
"description": "Opaque data echoed back in the webhook (≤4096)."
},
"swap_to": {
"type": "string",
"description": "Auto-convert the received amount to this asset."
},
"expires_in": {
"type": "integer",
"description": "Invoice TTL in seconds."
},
"description": {
"type": "string",
"description": "Shown to the payer (≤1024)."
},
"paid_btn_url": {
"type": "string",
"description": "URL for the paid button."
},
"currency_type": {
"type": "string",
"description": "crypto (default) | fiat."
},
"paid_btn_name": {
"type": "string",
"description": "viewItem | openChannel | openBot | callback."
},
"allow_comments": {
"type": "boolean",
"description": "Default true."
},
"hidden_message": {
"type": "string",
"description": "Revealed to the payer ONLY after payment (≤2048)."
},
"accepted_assets": {
"type": "string",
"description": "Fiat mode: comma-separated assets the payer may pay in."
},
"allow_anonymous": {
"type": "boolean",
"description": "Default true."
},
"rate_lock_seconds": {
"type": "integer",
"description": "Fiat mode: freeze crypto quotes for this long."
}
}
}