Telegram mini app payments: taking crypto inside a mini app
Telegram mini app payments explained: taking crypto inside a Telegram mini app, what Qvard plans for mini app checkout and the working path with the API today.
Telegram mini app payments mean a shop built as a web app inside Telegram takes crypto for its items. Qvard plans a mini app checkout, and it is not released yet. This guide explains how a mini app payment would work and the path that works today: the mini app’s backend creates the payment through the API, opens the hosted page and confirms the order by webhook.
What a mini app payment is
A Telegram mini app is a web application that opens inside the chat. A payment in a mini app means the customer chooses an item in the app and pays for it without leaving Telegram for long.
Status: mini app checkout is on the roadmap
A native Qvard checkout for Telegram mini apps is not released yet, and this article does not describe it as available. The working path below uses the live API, the hosted payment page and the webhook.
What works today
The mini app’s backend creates the payment with POST /api/v1/payment and the x-api-key header, receives a redirectUrl and opens the hosted page for the customer. The webhook then delivers the final status to the backend, which unlocks the item.
Keep the key on the backend
A mini app runs in the customer’s browser, so the API key must never be placed in the front-end code. Only the backend calls POST /api/v1/payment.
x-api-key: sk_live_…
{
"id": "order_1024",
"price": 149.99,
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}Unlock the item on the webhook
The mini app shows the item as unlocked only after the webhook has delivered the id and the status paid for that order. Until then the item stays locked, even if the customer returns to the app.
Plan for a native mini app checkout
When the native checkout is released, the payment window may open inside the app. Until then, keep the order logic and the webhook in the backend, so that only the front-end changes later.
FAQ
Can a Telegram mini app take crypto payments today?
Yes. The mini app’s backend creates the payment through the API, opens the hosted page and unlocks the item after the webhook confirms the paid status. A native mini app checkout is on the roadmap.
Can the mini app call the payment API directly from the browser?
No. Keep the API key on the backend and call the payment endpoint only from there.
Does the customer have to leave the mini app?
Today the hosted payment page opens for the payment, and the result returns to the mini app through your backend and webhook.
How do I test a mini app payment?
Create a demo invoice from a test item, pay it on the hosted page and check that the item unlocks after the webhook.
