Sell on Telegram and in chats

Create one drop, give each fan a personal pay-per-view link and match every sale back to the right chat.

1. 1Create the drop once

   One drop has one price, so create one drop per price. Keep the productId.

   curlNodePython

   curl

   Copy

   curl -X POST "https://www.dropfans.io/api/external/v1/drops" \
     -H "Authorization: Bearer $DROPFANS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "name": "Friday set",
         "price": 25,
         "vaultItemIds": [
           "VAULT_ITEM_A",
           "VAULT_ITEM_B"
         ]
       }'

   Node

   Copy

   const res = await fetch('https://www.dropfans.io/api/external/v1/drops', {
     method: 'POST',
     headers: {
       Authorization: 'Bearer ' + process.env.DROPFANS_API_KEY,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       "name": "Friday set",
       "price": 25,
       "vaultItemIds": [
         "VAULT_ITEM_A",
         "VAULT_ITEM_B"
       ]
     }),
   });
   console.log(await res.json());

   Python

   Copy

   import os, requests
   
   res = requests.post(
       "https://www.dropfans.io/api/external/v1/drops",
       headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
       json={
         "name": "Friday set",
         "price": 25,
         "vaultItemIds": [
           "VAULT_ITEM_A",
           "VAULT_ITEM_B"
         ]
       },
   )
   print(res.json())

2. 2Make one link per fan

   A reference is 1 to 32 characters of A-Z a-z 0-9 _ -. GET /links returns the right templates for each creator. The fan pays on the web checkout. Telegram requires Stars for digital goods sold inside bots and Mini Apps, so this is the link to send.

   Link

   Copy

   https://www.dropfans.io/buy/{productId}?m={externalRef}

3. 3Match the payment

   Approved apps get a drop.paid webhook, where data.externalRef says which fan paid. Use data.orderId as your idempotency key. Personal keys can poll GET /orders?externalRef=….

   A fan can edit the link, so the reference is not proof of identity. For extra safety, compare buyer.telegramUserId with the chat you expect.

   Node

   Copy

   // drop.paid handler (after verifying the signature)
   const { orderId, externalRef, productId, buyer } = event.data;
   if (await alreadyDelivered(orderId)) return;
   const chat = await findConversationByRef(externalRef);
   await deliverMedia(chat, productId);
   await markDelivered(orderId);

4. 4Handle refunds

   Refunds and chargebacks arrive as drop.refunded with the same orderId and externalRef, plus a reason of refund or chargeback.

   Event

   Copy

   {
     "type": "drop.refunded",
     "data": {
       "orderId": "...",
       "externalRef": "tg_48213377",
       "refundedAt": "2026-10-17T16:20:00.000Z",
       "reason": "chargeback"
     }
   }

Last updated 2026-11-02