Journal
Freedom pay

Freedom Pay Telegram: Connect It to Your Shop

Freedom Pay (ex-PayBox) in Telegram, step by step: get the token in BotFather, paste it into your Telegram shop, test and go live. For KG, KZ and UZ sellers.

Freedom Pay (formerly PayBox) is a Central Asian payment company that works as a Telegram payment provider: buyers pay by card on Telegram's own payment sheet, and the money goes to your Freedom Pay merchant account. To connect it, you take a provider token from @BotFather and paste it into your store. This guide walks through it for sellers in Kyrgyzstan, Kazakhstan and Uzbekistan with physical goods or services, from the merchant application to the first live order.

For the bigger picture, see how Telegram payments work and the list of Telegram payment methods. Selling into Stripe countries? Use the Stripe guide.

How Freedom Pay works in Telegram#

  1. The buyer picks a product in your Telegram store and taps Pay.
  2. Telegram's payment sheet opens with the total.
  3. The buyer enters their card, and Freedom Pay confirms the payment (often with a code sent to the buyer's phone).
  4. The order is marked paid, and the money settles to your Freedom Pay account.

Telegram takes no commission on provider payments and doesn't store card details. Freedom Pay does the charging and sets its fee in your agreement.

What you need#

  1. A Telegram bot connected to your Tiny Shops store.
  2. A Freedom Pay merchant account for your country's legal entity (KG application form, or the KZ / UZ site if that's where your entity is).
  3. Company documents for verification and, for live payments, a signed connection agreement with Freedom Pay.

Step 1 β€” Open a Freedom Pay merchant account#

  1. Submit the merchant request (KG: freedompay.kg/en/anketa).
  2. Complete the application with the documents they ask for. New merchants usually start in test mode; Freedom Pay switches you to production after testing and a signed connection act.
  3. In your personal account, note your store / account ID. Use the ID from your own account.

Ask your Freedom Pay manager three things: that Telegram Bot Payments are enabled for you, which invoice currencies you can use (KG merchants usually price in KGS), and the fee in your agreement.

Step 2 β€” Get the provider token in BotFather#

  1. Open @BotFather β†’ /mybots β†’ your store bot.
  2. Tap Bot Settings β†’ Payments.
  3. Pick the Freedom Pay entry for your country. Depending on your account you may see FreedomPay KG, FreedomPay KZ, FreedomPay UZ or the older PayBox.money. Use the label BotFather actually shows.
  4. Follow Freedom Pay's connection flow (usually your store ID and a few fields).
  5. Copy the test provider token first. After live enablement, BotFather gives you a live token.

Step 3 β€” Paste the token into Tiny Shops#

  1. In the dashboard open Checkout β†’ Payment methods, click Add method and pick Telegram Invoice.
  2. The new row shows Not connected and its editor opens below. Click Connect.
  3. Click Add Provider and fill in:
    • Provider Name: your own label, for example Freedom Pay. There's no ready-made Freedom Pay entry.
    • Provider Token: the token from BotFather.
    • Test Mode: on while testing.
Add Provider dialog with Provider Name, Token, and Test Mode
Add Provider dialog with Provider Name, Token, and Test Mode
  1. Click Save Provider. The row shows Test Mode and Active, with Edit Provider and Delete Provider buttons.
Saved Freedom Pay provider with Test Mode and Active badges
Saved Freedom Pay provider with Test Mode and Active badges
  1. Set the store currency, in the card at the top of the same page, to the one Freedom Pay confirmed for your account.
  2. Press Save changes (top right) so Telegram Invoice reaches your storefront.

Step 4 β€” Place a test order#

Check out in your store with the test card from Freedom Pay's Merchant API docs:

FieldTest value
Card4111 1111 1111 1111
Expiry12/24 (2024/12 in Freedom Pay's docs)
CVV123
Cardholderat least two English words (e.g. Test User)
3-DS (if asked)12345678

If the expiry is rejected as past, check the current test-card list or ask Freedom Pay support for a newer test date.

Step 5 β€” Go live#

  1. Finish Freedom Pay's agreement and connection act so your account is in production.
  2. Get the live token in BotFather β†’ Payments.
  3. In Tiny Shops, click Edit Provider, paste the live token, turn Test Mode off and click Save Provider.
  4. Check that the row still shows Active, without Test Mode.
  5. Place a small real order and confirm it settles with Freedom Pay.

Before going live, also follow Telegram's checklist: two-step verification on the account that owns the bot, /terms and /support commands, and readiness to handle disputes.

Physical goods vs digital (Stars)#

Freedom Pay is for physical goods and services. Digital goods and services sold inside Telegram must be paid in Telegram Stars (XTR): Telegram says it cannot show a bot or Mini App to mobile users that sells digital goods through third-party providers. Details in Telegram Stars vs Stripe.

Fees and currency#

  • Telegram: no commission on provider payments.
  • Freedom Pay: set individually in your agreement (a percent, a fixed amount or both). Ask your manager or check the contract.
  • Tiny Shops: the plan's percent of every order: 7% on Free, 3% on Starter ($9.99 a month), 1.5% on Pro ($29), 0.7% on Scale ($79). Each account's first $100 in sales are commission-free, once, not every month. It's billed with your plan, not taken from the Freedom Pay payment. See pricing.
  • Currency: confirm it with Freedom Pay. KG merchants usually use KGS; KZT and UZS depend on your connection.

FAQ#

Is Freedom Pay the same as PayBox? Yes. Freedom Pay is the former PayBox.money. BotFather may still list a PayBox.money entry next to FreedomPay KG, KZ or UZ; pick the one for your country.

Do I need Freedom Pay's Merchant API? No. For Telegram payments you only need the BotFather provider token. The Merchant API is a separate integration for websites.

Why does a payment fail with PAYMENT_PROVIDER_INVALID? Usually a currency mismatch. Set the store currency at the top of Checkout β†’ Payment methods to the one Freedom Pay supports for your Telegram connection.

Can I sell digital downloads through Freedom Pay in Telegram? No. Use Telegram Stars for digital goods; Freedom Pay is for physical goods and services.

Where does the buyer pay? On Telegram's payment sheet, right after checkout in your store, without leaving the chat.

Sources#

Open your store and connect Freedom Pay at tiny-shops.com β†’

Read next

Stripe

Stripe Telegram Bot: How to Connect Payments

Stripe and Telegram, step by step: get a Stripe token in BotFather or use Stripe Connect, paste it into your Telegram shop, test with 4242 and go live.

The channel

New pieces land in Telegram first.
No spam, no growth hacks.