Skip to main content
Use the Coinom Merchant API to accept cryptocurrency payments directly inside your Telegram bot. The integration flow is identical to a website or mobile application. Your bot creates a payment, sends the Coinom checkout link to the user, receives the payment callback, verifies the payment, and finally delivers the purchased product or service.
Telegram bots do not process cryptocurrency payments directly.Coinom securely hosts the payment page and processes the payment. Your bot is responsible only for creating the payment, sending the payment link, and verifying the payment after completion.

​
Integration Flow

​
Step 1 — Create a Payment

Create a payment using the standard Create Payment endpoint.
Example request
Successful response
The returned trackId uniquely identifies the payment and is required for the next steps.
Generate the Coinom checkout URL using the returned trackId.
Example
Send this URL to the customer using an Inline Keyboard button or any clickable Telegram message. Example
💳 Complete your payment by clicking the button below.
[ Pay with Crypto ]

​
Step 3 — Receive the Callback

When the customer completes the payment, Coinom sends an HTTP POST request to your callbackUrl. Example
Your callback endpoint should immediately verify the payment using the Verify Payment endpoint.
Never assume a payment is successful simply because the customer returned to your bot.Always verify the payment from your server.

​
Step 4 — Verify the Payment

Verify the payment using the Verify Payment endpoint.
Example request
Successful response
A payment is considered successful only when:
  • result equals 100
  • The returned amount matches your original order amount

​
Step 5 — Notify the User

When creating the payment, store the Telegram chat_id together with the generated trackId. After successful payment verification:
  1. Find the matching chat_id
  2. Deliver the purchased product or service
  3. Send a confirmation message using the Telegram Bot API
Example message

​
Common Use Cases

Telegram Bot Payments can be used for:
  • Digital products
  • Premium subscriptions
  • Membership access
  • License keys
  • Account balance top-ups
  • Donations
  • Private channel access
  • AI bot credits
  • Virtual goods

​
Best Practices

Verify Every Payment

Always verify payments using the Verify Payment endpoint before delivering any product or service.

Compare the Amount

Always compare the verified amount with your original order amount before completing the purchase.

Store Track IDs

Store the generated trackId together with the Telegram chat_id or your internal order ID.

Use HTTPS

Your callback URL should be publicly accessible over HTTPS for production environments.

Do Not Trust Redirects

Never rely on the customer returning to your bot as proof of payment.

Store Reference Numbers

Save the returned refNumber for future support, reconciliation, and accounting.

​
Integration Summary

  1. Create a payment.
  2. Receive the trackId.
  3. Send the Coinom payment link to the Telegram user.
  4. Wait for the payment callback.
  5. Verify the payment.
  6. Compare the verified amount.
  7. Deliver the purchased product or service.
  8. Notify the user.

Quick Start

Get started with the Coinom API.

Create Payment

Create a new payment.

Verify Payment

Verify completed payments.

Response Codes

View all API response codes.