TgPay Merchant API

Read a TgPay Merchant API integration doc. START HERE before integrating: topics quickstart, invoices, subscriptions, transfers-checks, webhooks, errors.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "quickstart | invoices | subscriptions | transfers-checks | webhooks | errors"
    }
  },
  "required": [
    "topic"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "app_name": {
      "type": "string",
      "description": "Merchant app name shown to the approving human, 1-64 chars (e.g. the project/bot name)."
    }
  },
  "required": [
    "app_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.

{
  "type": "object",
  "properties": {
    "poll_secret": {
      "type": "string",
      "description": "The poll_secret from the connect tool."
    }
  },
  "required": [
    "poll_secret"
  ]
}

Verify the token: app id, name, webhook config, token scopes.

{
  "type": "object",
  "properties": {}
}

Merchant app balance per asset (available + onhold).

{
  "type": "object",
  "properties": {}
}

Supported crypto assets (code/name/decimals) and fiats.

{
  "type": "object",
  "properties": {}
}

Current asset↔fiat display rates.

{
  "type": "object",
  "properties": {}
}

App volume/count stats for a period.

{
  "type": "object",
  "properties": {
    "start_at": {
      "type": "string",
      "description": "ISO 8601 period start."
    },
    "end_at": {
      "type": "string",
      "description": "ISO 8601 period end."
    }
  }
}

List invoices (newest first).

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "description": "Filter by asset code."
    },
    "fiat": {
      "type": "string",
      "description": "Filter by fiat code."
    },
    "invoice_ids": {
      "type": "string",
      "description": "Comma-separated ids."
    },
    "status": {
      "type": "string",
      "description": "active | paid | expired."
    },
    "offset": {
      "type": "integer",
      "description": "Skip this many."
    },
    "count": {
      "type": "integer",
      "description": "Page size (default 100)."
    }
  }
}

List checks.

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "description": "Filter by asset code."
    },
    "check_ids": {
      "type": "string",
      "description": "Comma-separated ids."
    },
    "status": {
      "type": "string",
      "description": "active | activated."
    },
    "offset": {
      "type": "integer",
      "description": "Skip this many."
    },
    "count": {
      "type": "integer",
      "description": "Page size (default 100)."
    }
  }
}

List app→user transfers.

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "description": "Filter by asset code."
    },
    "transfer_ids": {
      "type": "string",
      "description": "Comma-separated ids."
    },
    "spend_id": {
      "type": "string",
      "description": "Filter by idempotency key."
    },
    "offset": {
      "type": "integer",
      "description": "Skip this many."
    },
    "count": {
      "type": "integer",
      "description": "Page size (default 100)."
    }
  }
}

List subscription plans.

{
  "type": "object",
  "properties": {}
}

List subscriptions (subscribers).

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "integer",
      "description": "Filter by plan."
    },
    "user_id": {
      "type": "integer",
      "description": "Filter by Telegram user id."
    },
    "status": {
      "type": "string",
      "description": "active | grace | cancelled | expired."
    }
  }
}

Create a one-off payment invoice; the payer opens result.mini_app_invoice_url. See the invoices doc.

{
  "type": "object",
  "properties": {
    "currency_type": {
      "type": "string",
      "description": "crypto (default) | fiat."
    },
    "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."
    },
    "fiat": {
      "type": "string",
      "description": "Fiat code (fiat mode)."
    },
    "accepted_assets": {
      "type": "string",
      "description": "Fiat mode: comma-separated assets the payer may pay in."
    },
    "rate_lock_seconds": {
      "type": "integer",
      "description": "Fiat mode: freeze crypto quotes for this long."
    },
    "description": {
      "type": "string",
      "description": "Shown to the payer (≤1024)."
    },
    "hidden_message": {
      "type": "string",
      "description": "Revealed to the payer ONLY after payment (≤2048)."
    },
    "payload": {
      "type": "string",
      "description": "Opaque data echoed back in the webhook (≤4096)."
    },
    "paid_btn_name": {
      "type": "string",
      "description": "viewItem | openChannel | openBot | callback."
    },
    "paid_btn_url": {
      "type": "string",
      "description": "URL for the paid button."
    },
    "allow_comments": {
      "type": "boolean",
      "description": "Default true."
    },
    "allow_anonymous": {
      "type": "boolean",
      "description": "Default true."
    },
    "expires_in": {
      "type": "integer",
      "description": "Invoice TTL in seconds."
    },
    "swap_to": {
      "type": "string",
      "description": "Auto-convert the received amount to this asset."
    }
  }
}

Delete an unpaid invoice.

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "integer",
      "description": "The invoice to delete."
    }
  },
  "required": [
    "invoice_id"
  ]
}

Delete an unclaimed check (refunds the hold).

{
  "type": "object",
  "properties": {
    "check_id": {
      "type": "integer",
      "description": "The check to delete."
    }
  },
  "required": [
    "check_id"
  ]
}

Create an IMMUTABLE recurring-billing plan; send payers to result.mini_app_subscribe_url. See the subscriptions doc.

{
  "type": "object",
  "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."
    }
  },
  "required": [
    "name",
    "asset",
    "amount",
    "period_days"
  ]
}

Stop new signups for a plan (live subscriptions keep renewing).

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "integer",
      "description": "The plan to archive."
    }
  },
  "required": [
    "plan_id"
  ]
}

Stop future charges for one subscription (paid time runs out).

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "description": "The subscription."
    }
  },
  "required": [
    "subscription_id"
  ]
}

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.

{
  "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",
      "description": "Extended event types to opt into (invoice_paid is always delivered); [] = invoice_paid-only.",
      "items": {
        "type": "string",
        "description": "Event type."
      }
    }
  }
}