How to Accept Crypto Payments in a Telegram Bot with Coinom API

You can accept crypto payments in a Telegram bot by connecting the bot’s secure backend to the Coinom API. The basic flow is simple: create a Coinom account and merchant, obtain an API key, create a payment request, send the hosted payment link to the user, verify the result on your server, and unlock the purchase only after successful verification.

Coinom is a Crypto Payment Gateway for websites, applications, online stores, services, and bots. Standard signup uses an email address and password and does not request identity, address, or company documents. However, an API integration still requires basic backend development. This guide explains the architecture, implementation, security controls, and testing process in practical terms.

Can a Telegram Bot Accept Crypto Payments?

Yes. A Telegram bot can collect an order in chat, ask a payment gateway to create a crypto checkout, and send the user a button that opens the payment page. After Coinom detects and verifies the blockchain payment, the backend can tell the bot to deliver the product or activate the service.

The chat interface and the payment system have different jobs. Telegram handles messages, commands, and buttons. Your server stores orders and communicates with Coinom. Coinom creates the payment, displays the crypto checkout, monitors the blockchain, and returns the payment result.

Keep the Coinom API key on the backend. Never include it in a Telegram message, inline-button callback data, public repository, frontend script, or mobile application. Users should only receive the hosted payment URL and non-sensitive order information.

This setup can support many permitted products and services, including:

• Digital downloads and software licenses
• Premium bot commands and usage credits
• SaaS plans and account credit
• Event or course access
• Community roles and memberships
• Hosting, server, or agency invoices
• Donations and tips where appropriate

The bot operator remains responsible for the products offered, Telegram’s rules, refund terms, accounting, taxes, and any requirements that apply to the business.

What Is Coinom and Why Use It for a Telegram Bot?

Coinom provides the payment layer that connects a custom application to supported blockchain networks. After creating an account, you can create a merchant and obtain an API key. Your backend uses that key when it sends payment and verification requests to Coinom.

For a bot owner, the useful features are practical. Coinom creates a unique payment reference, provides a hosted checkout, monitors the selected blockchain, tracks confirmations, and records payment activity. Your integration can use a callback notification and an independent verification request to update the correct order.

The gateway supports several widely used assets, including Bitcoin, USDT, Ethereum, BNB, TRON, Litecoin, and Dogecoin. The exact list can change, so check the current Coinom documentation before publishing fixed payment options inside your bot.

“No KYC” describes Coinom’s standard merchant-registration process. It does not make blockchain transfers anonymous. Public blockchain activity remains traceable, and a customer’s wallet or exchange may apply its own verification rules.

You might be interested: How to Accept Crypto Payments Without KYC

Coinom Integration Options Beyond Telegram

The API is intended for custom systems such as Telegram bots, SaaS products, websites, and applications. Coinom also provides ready-made modules for WooCommerce, WHMCS, OpenCart, PrestaShop, Easy Digital Downloads, and WordPress donations.

A business can therefore use the API for a bot and a platform-specific module for its ecommerce site. Review the current Coinom payment plugins if you also sell through one of those platforms. Coinom states that custom integration assistance is available for unsupported systems at no additional integration-development cost. Confirm the scope and current availability with Coinom before planning a project.

You might be interested: What Is a Crypto Payment Gateway? Everything You Need to Know

How Telegram Bot Crypto Payments Work

A reliable integration links every Coinom payment to one internal order. The order is the bridge between the Telegram user, the product, and the blockchain result.

1. The user selects a product or service in the Telegram bot.
2. The backend creates an internal order with a unique ID and a pending status.
3. The backend sends a server-to-server payment request to Coinom.
4. Coinom returns a payment reference called trackId.
5. The backend stores that reference and builds the documented hosted checkout URL.
6. The bot sends the user a clear payment button.
7. The user selects a supported asset and network, then sends the payment.
8. Coinom monitors the blockchain and sends a status callback to the merchant.
9. The backend verifies the payment directly with Coinom and checks the amount.
10. The bot fulfills the order once, then sends the user a confirmation.

Telegram updates and Coinom callbacks are separate event sources. Telegram updates report user actions, such as commands and button presses. Coinom callbacks report changes related to a payment. Both should reach secure backend routes and update the same stored order safely.

Telegram Bot Payment Architecture at a Glance

Component	Responsibility	Important Security Rule
Telegram user	Selects an item, opens checkout, and sends the payment	Never treat the user’s screenshot or claim as payment proof
Telegram bot	Displays products, payment buttons, and order messages	Do not place secrets in messages or callback data
Bot backend	Calls APIs and coordinates order state	Keep API keys and the bot token server-side
Order database	Maps users, orders, amounts, and payment references	Use unique constraints and durable storage
Coinom API	Creates and verifies payments	Call it only from the secure backend
Coinom callback handler	Receives payment-status notifications	Use the callback to trigger server-side verification
Fulfillment logic	Grants credit, access, files, or services	Run only after verification and make it idempotent

The API key stays on the server throughout this architecture. The fulfillment process starts only after the server has verified a successful Coinom result and matched the returned amount to the stored order.

What You Need Before Integration

Prepare the following items before writing payment code:

• An existing Telegram bot and its securely stored bot token
• A backend written in Node.js, Python, PHP, Go, or another server-side language
• HTTPS hosting for public Telegram and Coinom endpoints
• A database or other durable order store
• A Coinom account, merchant, and API key
• Access to the Coinom API quick-start guide
• A small test product and a compatible crypto wallet

Your server must remain available when users order and when payment notifications arrive. Do not rely only on variables stored in the running bot process. A restart would erase that state and could separate a payment from its order.

How to Accept Crypto Payments in a Telegram Bot with Coinom API

Step 1: Create a Coinom account

Create your Coinom account with an email address and password. Coinom’s standard registration does not request an identity document, proof of address, or company-registration document.

Use an email address that your business controls. Choose a strong, unique password and secure the email account as well. Anyone who controls the merchant account may be able to view sensitive payment settings.

Step 2: Create a merchant and obtain the API key

Create a merchant inside your Coinom account. The merchant represents the bot or payment project. Copy its API key and store it in an environment variable or a managed secret store.

COINOM_API_KEY=replace_with_your_private_key
TELEGRAM_BOT_TOKEN=replace_with_your_private_token
COINOM_CALLBACK_URL=https://example.com/webhooks/coinom

Do not commit the environment file to version control. Also avoid printing either secret in application logs. If a credential becomes public, rotate it and remove the exposed value from every accessible location.

Step 3: Create an internal bot order

Create one internal order for each purchase attempt. A useful record includes:

• A unique internal order ID
• The stable Telegram user ID and the current chat ID
• The product or plan identifier
• The expected amount and its pricing currency
• A status such as pending, paid, or fulfilled
• Creation and update timestamps
• The Coinom trackId after payment creation
• A fulfillment timestamp or unique fulfillment record

Do not use the Telegram username as the permanent customer key. Users can change usernames, and some accounts do not have one. The numeric Telegram user ID is more suitable for linking the purchase to the user.

Step 4: Create the Coinom payment request

According to the current quick-start documentation, the backend creates a payment with an HTTP POST request to https://app.coinom.com/api/v1/request. The JSON body includes the merchant API key, amount, and callback URL. It can also include a return URL, description, and mobile flag.

async function createCoinomPayment(order) {
  const response = await fetch("https://app.coinom.com/api/v1/request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      merchant: process.env.COINOM_API_KEY,
      amount: order.amount,
      callbackUrl: process.env.COINOM_CALLBACK_URL,
      returnUrl: "https://example.com/payment/complete",
      description: `Telegram order ${order.id}`,
      mobile: true
    })
  });

  if (!response.ok) throw new Error("Coinom request failed");

  const data = await response.json();
  if (data.result !== 100 || !data.trackId) {
    throw new Error(data.message || "Payment was not created");
  }

  return {
    trackId: data.trackId,
    checkoutUrl: `https://app.coinom.com/pay/${data.trackId}`
  };
}

This example runs on the server and uses fictional application URLs. Validate the current endpoint, fields, and success values in the official documentation before deployment. Store amounts in a consistent format so later comparisons do not fail because of rounding.

Step 5: Store the returned payment reference

Coinom returns the unique trackId after successful payment creation. Save it against the internal order before sending a payment button to the user. Make the database column unique if one Coinom reference must belong to only one order.

This mapping lets the callback handler find the correct user and product. It also supports manual investigation, status checks, and safe retries. Without it, your backend cannot reliably tell which Telegram purchase a notification belongs to.

Step 6: Send the payment action to the user

The documented hosted checkout follows the form https://app.coinom.com/pay/{trackId}. Send that URL through a Telegram inline keyboard button. A URL button opens the payment page; it does not contain either secret.

await telegramApi("sendMessage", {
  chat_id: order.chatId,
  text: `Order ${order.id} is ready. Pay ${order.amount} to continue.`,
  reply_markup: {
    inline_keyboard: [
      [{ text: "Pay with crypto", url: payment.checkoutUrl }],
      [{ text: "Check payment", callback_data: `check:${order.publicId}` }]
    ]
  }
});

Use a short public order reference in callback_data, not an API key or a full database object. Telegram limits callback data length, and users can manipulate data sent back to the bot. Always look up the stored order and confirm that it belongs to the requesting Telegram user.

Step 7: Receive and verify the payment status

A callback tells your backend that it should check a payment. Do not treat the callback alone as final proof. Instead, call the documented verification endpoint from your server.

The current Coinom documentation uses an HTTP POST request to https://app.coinom.com/api/v1/verify with the merchant key and trackId. A successful verification returns result value 100, the verified amount, and a reference number.

async function verifyCoinomPayment(trackId) {
  const response = await fetch("https://app.coinom.com/api/v1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      merchant: process.env.COINOM_API_KEY,
      trackId
    })
  });

  if (!response.ok) throw new Error("Coinom verification failed");
  return response.json();
}

Load the order by trackId. Confirm that the returned result is successful and that the verified amount equals the expected order amount. A return-page visit, browser redirect, screenshot, customer message, or user-submitted transaction ID is not sufficient proof.

Step 8: Fulfill the order safely

Fulfillment must be idempotent. In plain language, the same successful payment may reach your handler more than once, but the product must be delivered only once.

async function verifyAndFulfill(trackId) {
  const payment = await verifyCoinomPayment(trackId);

  return database.transaction(async (tx) => {
    const order = await tx.orders.findByTrackIdForUpdate(trackId);
    if (!order) throw new Error("Unknown payment reference");
    if (order.fulfilledAt) return { alreadyFulfilled: true };

    if (payment.result !== 100) return { pending: true };
    if (String(payment.amount) !== String(order.amount)) {
      throw new Error("Verified amount does not match the order");
    }

    await tx.entitlements.grantOnce(order.userId, order.productId, order.id);
    await tx.orders.markFulfilled(order.id, payment.refNumber);
    return { fulfilled: true, chatId: order.chatId };
  });
}

A database transaction and unique fulfillment record prevent two workers from granting the same credit simultaneously. After the transaction succeeds, send the user a confirmation. If the message fails, retry only the notification, not the product delivery.

Step 9: Handle incomplete and failed payments

The current verification reference lists different results for a completed payment, an incomplete transaction, an invalid or unfinished payment, an invalid key, and a disabled merchant. Map documented outcomes to internal states without guessing what happened.

For example, keep an unfinished payment pending and show the user a neutral message. Send configuration errors to your monitoring system rather than exposing technical details in chat. Follow current Coinom guidance for underpayments, overpayments, expired checkouts, wrong-network transfers, or other exceptional cases. Do not promise an automatic refund unless it is explicitly supported and configured.

Step 10: Run an end-to-end test

Test the complete workflow with a small, appropriate payment before accepting customer orders. Confirm each of these points:

• The bot creates one internal order per purchase attempt.
• The backend creates a Coinom payment and stores its trackId.
• The Telegram button opens the correct hosted checkout.
• The displayed product, amount, asset, and network instructions are clear.
• Coinom detects the payment and tracks confirmation status.
• The callback reaches the correct HTTPS endpoint.
• The backend verifies the result and compares the amount.
• The system fulfills the order once.
• Repeated callbacks do not repeat fulfillment.
• The payment and transaction record appears in Coinom.
• The user receives an accurate final message.

Also test abandoned checkouts, invalid button presses, server restarts, and temporary API failures. These cases reveal problems that a single successful test may hide.

How to Match Payments to Telegram Users and Orders

Four identifiers play different roles in a Telegram bot payment integration:

• Telegram user ID: identifies the person’s Telegram account.
• Chat ID: identifies the chat where the bot sends messages.
• Internal order ID: identifies one purchase attempt in your business system.
• Coinom trackId: identifies the related Coinom payment.

Create a new internal order for each attempt. Then attach one trackId to it. Use unique database constraints on both identifiers. This design prevents one payment from being attached to several purchases.

Keep Telegram callback data small and non-sensitive. When a user presses “Check payment,” read the public order token, load the full order from the database, and confirm ownership. The button should never carry the amount, fulfillment state, or merchant secret as authoritative data.

Durable storage also improves recovery. If the bot restarts, it can reload pending orders and continue processing callbacks. If a callback is delayed, a user-initiated status check can run the same safe verification function without creating a second delivery path.

Supported Cryptocurrencies and Networks

Coinom currently lists Bitcoin, USDT, Ethereum, BNB, TRON, Litecoin, and Dogecoin among its supported assets. Available payment choices are shown through the Coinom checkout. Always use the current asset list displayed by the gateway and documented by Coinom.

Network selection matters, especially for USDT. Coinom supports USDT on networks including TRC20, ERC20, and BEP20 when shown in the current documentation and checkout. These networks are not interchangeable. The customer must send the correct token through the exact network selected for that payment.

Do not hardcode permanent fee or confirmation-time promises in bot messages. Blockchain conditions and exchange withdrawal charges can change. Instead, ask the customer to review the asset, network, amount, and wallet details shown on the hosted checkout.

You might be interested: USDT TRC20 vs ERC20 vs BEP20: Best for Crypto Payments?

Security Best Practices for Telegram Bot Crypto Payments

Security comes from several small controls working together. Focus on protecting credentials, authenticating events, and preventing duplicate fulfillment.

• Keep secrets server-side. Store the Coinom API key and Telegram bot token in environment variables or a secret manager.
• Use HTTPS. Protect Telegram webhook and Coinom callback traffic in transit.
• Validate Telegram webhooks. When you configure Telegram’s webhook secret token, verify the X-Telegram-Bot-Api-Secret-Token header as described in Telegram’s official Bot API documentation.
• Verify Coinom payments server-side. Treat a callback as a prompt to call Coinom’s verification endpoint.
• Reject malformed requests. Check HTTP methods, content types, required fields, and size limits.
• Use idempotent fulfillment. Protect delivery with database transactions and uniqueness rules.
• Rate-limit status checks. Prevent one user from creating excessive API traffic through a “Check payment” button.
• Keep useful logs. Record order IDs, payment references, result codes, and timestamps without storing secrets.
• Separate environments. Use different configuration for development and production. Never test experimental code against live fulfillment data.
• Rotate exposed credentials. Replace a key or token immediately if it appears in logs, source code, chat, or a public repository.
• Update dependencies. Apply security updates to the bot framework, HTTP client, database driver, and server.

No payment integration is risk-free. A clear operating process, restricted server access, backups, monitoring, and retained transaction records help you detect and resolve problems.

Common Mistakes and Troubleshooting

Calling Coinom from unsafe client code

A mobile app, browser script, or Telegram message cannot protect a merchant API key. Move payment creation and verification to your backend. The client should ask the backend to create an order, then receive only a safe checkout URL.

Failing to store the trackId

Save the Coinom reference before returning the payment button. If storage fails, do not continue as if the order is ready. Otherwise, a later callback may not match any internal purchase.

Trusting the customer or the return page

A screenshot, transaction hash, success message, or return-page visit can be mistaken or manipulated. Verify through Coinom and compare the returned amount with the order stored on your server.

Confusing two types of callbacks

A Telegram callback query reports an inline-button press. A Coinom callback reports a payment-related event. Give them different routes and handlers, even if both eventually call the same order service.

Delivering more than once

Networks and web services retry requests. Therefore, duplicate callbacks are normal events to handle, not proof of an attack. Check the fulfillment record inside a database transaction before granting access.

The callback endpoint does not receive requests

Confirm that the configured URL is public, uses HTTPS, accepts the correct method, and is not blocked by a firewall or authentication page. Review sanitized server logs. Then compare your handler with the current Coinom API documentation.

The payment stays pending

Blockchain detection and confirmation can take time. Check the current verified result instead of assuming a fixed delay. Also confirm that the user selected the correct asset and network. Contact Coinom support when the official records and your integration do not agree.

The API request fails

Check the endpoint, JSON format, required fields, merchant status, and API key. Avoid coding against remembered field names or old examples. Use the current Coinom API documentation as the source of truth.

Telegram Bot Use Cases for Coinom Payments

The same verified-payment pattern can support different business models. Fulfillment changes, but the payment architecture remains consistent.

• Premium bot commands: unlock a command set or usage allowance after payment.
• Digital downloads: send a protected file or time-limited download link.
• SaaS credits: add a verified number of credits to the customer’s account.
• Community access: assign a permitted role or provide an invitation after payment.
• Courses: unlock lessons, materials, or a private learning area.
• Software licenses: issue one license linked to the fulfilled order.
• Hosting services: mark an invoice paid and trigger the approved provisioning workflow.
• Gaming communities: grant allowed community items or credits under the applicable platform rules.
• Donations: record a contribution and send a receipt or thank-you message.
• Invoice bots: create an order-specific checkout and notify both the customer and operator.
• AI tools: add message, generation, or automation credits to the verified account.

A successful payment can activate a plan, but that does not automatically mean recurring billing. Do not promise automatic subscription rebilling or automated refunds unless current Coinom documentation explicitly supports your intended workflow.

You might be interested: How to Accept USDT Payments on Your Website with a USDT Payment Gateway

Frequently Asked Questions

Can a Telegram bot accept cryptocurrency payments?

Yes. Its backend can create a payment through Coinom, send the hosted checkout link in Telegram, verify the final result on the server, and deliver the purchase after confirmation.

How does the Coinom API work with a Telegram bot?

The backend creates an internal order and sends a payment request to Coinom. It stores the returned trackId, sends the checkout URL to the user, receives a callback, verifies the payment with Coinom, and fulfills the matching order.

Does Coinom require KYC?

Coinom’s standard merchant signup uses an email address and password without requesting identity, address, or company documents. This onboarding model does not remove the operator’s legal, tax, accounting, or platform responsibilities.

What information is needed to create a Coinom account?

Standard registration requires an email address and password. You then create a merchant to obtain the API key used by your server-side integration.

Do I need a backend server?

Yes. A secure backend protects the Coinom API key and Telegram bot token. It also stores orders, processes callbacks, verifies payments, and controls fulfillment.

Can I put the Coinom API key inside my Telegram bot code?

You may use it in private server-side bot code, but load it from an environment variable or secret manager. Never expose it in public source code, client applications, messages, URLs, or Telegram callback data.

Which cryptocurrencies can the bot accept?

Coinom currently lists Bitcoin, USDT, Ethereum, BNB, TRON, Litecoin, and Dogecoin among its supported assets. Check the live checkout and official documentation for the current list and available networks.

Can a Telegram bot accept Bitcoin and USDT?

Yes, when those options are available in the Coinom checkout. For USDT, the user must send it through the exact displayed network, such as TRC20, ERC20, or BEP20.

How does the bot know that a payment is complete?

A Coinom callback prompts the backend to verify the payment through the official API. The backend then checks the successful result and amount against the stored order before changing its status.

Should the bot trust a customer’s transaction ID or screenshot?

No. Neither proves that the correct order received the correct confirmed amount. Use Coinom’s server-side verification result as the payment source of truth.

How can I prevent duplicate delivery after repeated callbacks?

Use idempotent fulfillment. Store a unique fulfillment record and check it inside a database transaction. If the order has already been fulfilled, acknowledge the event without issuing the product again.

Can Coinom help with a custom integration?

Coinom currently states that custom integration assistance is available for unsupported websites, platforms, and applications at no additional integration-development cost. Contact Coinom to confirm the current offer, project scope, requirements, and timing.

Start Accepting Crypto Payments in Your Telegram Bot

To accept crypto payments in a Telegram bot safely, keep the payment logic on a secure backend. Create one internal order per attempt, request a Coinom payment, store its trackId, send the hosted checkout link, verify the final result server-side, compare the amount, and fulfill the order only once.

A Coinom crypto payment gateway integration gives bot developers hosted checkout, blockchain monitoring, payment verification, support for multiple cryptocurrencies, and straightforward no-KYC merchant onboarding. The API approach works well for custom bot commands, credits, downloads, SaaS access, and other controlled fulfillment workflows.

When you are ready, sign up for Coinom, create a merchant, protect the API key, and follow the official quick-start documentation. Then complete a small end-to-end test before enabling crypto payments for live Telegram users.