جریان یک سفارش
از «خرید» تا تحویل، در چهار گام
مشتری «خرید» را میزند
ربات شما با یک درخواست POST /v1/links برای این سفارش یک لینک تکبارمصرف میسازد و شناسه چت و محصول را در metadata میگذارد.
ربات لینک را میفرستد
لینک را با دکمه «پرداخت» برای همان مشتری میفرستید. مشتری کارتبهکارت میکند و پول مستقیم به کارت شما میرود.
خبر پرداخت به ربات میرسد
یا وبهوک امضاشده میآید، یا ربات هر چند ثانیه GET /v1/events را میپرسد. این فقط خبر است، نه مدرک.
verify، سپس تحویل یکبار
ربات پرداخت را از API میخواند و فقط اگر verified برابر true بود، کد را به شناسه پرداخت اختصاص میدهد، ذخیره میکند و میفرستد.
نمونه کد کوتاه
دو تکه کد کافی است: ساخت لینک برای هر سفارش، و یک تابع واحد برای تحویل که هم وبهوک و هم poll فقط شناسه پرداخت را به آن میدهند. این بریدهای کوتاه از الگوی کار است؛ نمونه کاملتر و دو ربات آماده (Node با grammY و Python با aiogram) در مخزن پروژه است.
// one single-use link per order; the chat and product ride along in metadata
const res = await fetch(`${API}/v1/links`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
amount: priceToman * 10, // rial, an integer
title: product.title,
metadata: { chat_id: ctx.chat.id, sku: product.sku },
external_ref: `tg-${ctx.callbackQuery.id}`, // a retried update returns the same link
}),
});
const { url } = await res.json(); // send it with a "Pay" button// the ONE function that delivers; the webhook and the poller both call it with a payment id
async function deliverIfPaid(paymentId: string) {
if (db.isDelivered(paymentId)) return; // UNIQUE(payment_id) in your database
const p = await getPayment(paymentId); // GET /v1/payments/{id}, never the event's own status
if (!p.verified || !['paid', 'paid_late'].includes(p.status)) return;
if (p.amount_rial !== priceRial(p.metadata.sku)) return; // is it really for this product?
const code = db.assignCode(paymentId); // save first ...
await bot.api.sendMessage(p.metadata.chat_id, code); // ... then send
db.markDelivered(paymentId);
}مبلغها به ریال و عدد صحیحاند. کلید sk_live_… و رمز وبهوک را فقط در متغیر محیطی نگه دارید، نه در کد، لاگ یا پیام تلگرام.
خبر پرداخت: وبهوک یا poll
هر دو را میتوانید با هم داشته باشید؛ تحویل یکتا کاری میکند که جواب یکی بشود.
| وبهوک | poll کردن رویدادها | |
|---|---|---|
| نیاز | آدرس عمومی https برای ربات | هیچ آدرس عمومی؛ ربات از کامپیوتر خانه هم کار میکند |
| چطور | POST امضاشده با هدر X-Signature | GET /v1/events?after=cursor، هر ۲ تا ۵ ثانیه |
| قاعده | بدنه خام را با HMAC-SHA256 بررسی کنید؛ بعد از انجام کار 2xx بدهید | رویداد را پردازش کنید، بعد cursor را ذخیره کنید |
| تضمین | حداقل یکبار؛ شناسه رویداد تکراری را نادیده بگیرید | حداقل یکبار؛ رویدادها هفت روز نگه داشته میشوند |
تحویل ایمن کد یا حساب
- خبر پرداخت اثبات نیست. وبهوک و رویداد فقط میگویند «به این پرداخت نگاه کن». پرداخت را از API بخوانید و فقط اگر
verifiedبرابرtrueو وضعیتpaidیاpaid_lateبود تحویل دهید. - مطمئن شوید پرداخت مال شماست. metadata را بخوانید و مبلغ را با قیمت محصول مقایسه کنید.
- اول ذخیره، بعد ارسال. کد را به شناسه پرداخت اختصاص دهید و ذخیره کنید، بعد بفرستید، بعد «تحویل شد» را ثبت کنید. اگر ارسال شکست خورد، تلاش بعدی همان کد را میفرستد، نه کد دیگری.
- تحویل را یکتا کنید. برای «کد» هر چیزی که میفروشید (آدرس دانلود، نام کاربری و رمز، …) همین قاعده است.
مشتری میتواند رسید جعلی بفرستد. فقط verified بودن پرداخت در API معتبر است.
آزمایش بدون پول واقعی
با کلید sk_test_… لینک آزمایشی بسازید و پرداختش را شبیهسازی کنید؛ همان موتور تطبیق، همان اعلان و همان صفحه پرداخت، بدون کارمزد:
curl -X POST $API/v1/test/deposits \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "payment_id": "pay_..." }'چیزهایی که باید بدانید
- واریزی که مبلغش با مبلغ یکتای پرداخت نخواند، تحویل نمیگیرد و به صف بررسی صاحب فروشگاه میرود.
- اگر اعتبار کیف پول کارمزد تمام شود، ساخت لینک و پرداخت واقعی تازه خطای
INSUFFICIENT_WALLET_BALANCEمیدهد؛ به صاحب ربات خبر بدهید. - به گوشی روشن و وصل نیاز است: تشخیص واریز از پیامک بانک روی گوشی شما میآید.
- مرجع کامل در راهنمای توسعهدهندگان است.
پرسشهای رباتنویسها
ربات من آدرس عمومی ندارد. باز هم میشود؟
بله. بهجای وبهوک، ربات خودش GET /v1/events را هر ۲ تا ۵ ثانیه میپرسد و با cursor دقیقاً از جایی که مانده ادامه میدهد. رویدادها هفت روز نگه داشته میشوند. این کار روی کامپیوتر خانه هم جواب میدهد.
اگر وبهوک دو بار برسد یا ربات وسط کار بمیرد، کد دو بار تحویل داده میشود؟
نباید. تحویل را با شناسه پرداخت یکتا میکنید: کد را به شناسه پرداخت اختصاص میدهید و ذخیره میکنید، بعد میفرستید. در محصول واقعی این یک قید UNIQUE(payment_id) در پایگاه داده است تا خود پایگاه داده تحویل دوم را ناممکن کند.
مشتری کمتر یا بیشتر واریز کرد چه میشود؟
واریزی که با مبلغ یکتای هیچ پرداختی نخواند خودکار تطبیق نمیخورد و به صف بررسی صاحب فروشگاه میرود؛ ربات چیزی تحویل نمیدهد. مشتری میتواند رسید بفرستد و صاحب فروشگاه دستی تأیید کند که آنوقت اعلان پرداخت ساخته میشود.
با پیشنمایش لینک در تلگرام پرداخت ساخته میشود؟
نه. پیشنمایش تلگرام و واتساپ فقط عنوان و مبلغ را میبیند و پرداختی نمیسازد؛ فقط باز کردن واقعی لینک پرداخت میسازد.
ربات را بدون پول واقعی امتحان کنم؟
بله. با کلید sk_test_ لینک آزمایشی میسازید و با یک درخواست POST /v1/test/deposits پرداخت را «انجام» میدهید. همان موتور تطبیق، همان اعلان و همان صفحه پرداخت است و کارمزد ندارد.
رباتتان را به پرداخت وصل کنید
با کلید آزمایشی شروع کنید و وقتی مطمئن شدید، کلید واقعی بگیرید.