Ödemeler (Ink)
Uygulaman dijital ürün, abonelik ve ücretli içerik satabilir. Telegram'daki Stars'ın yerini inkiveta'nın uygulama içi parası Ink alır. Telegram ödeme kodun neredeyse değişmeden çalışır.
Dikkat: Gerçek ortamda ödemeler kademeli açılıyor. Uygulaman için henüz açık değilse yeni fatura
400 Bad Request: payments are not enableddöner ve ödeme bileşenleri yerinefallback_textgörünür. Test ortamında ödeme akışı her zaman çalışır (test cüzdanıyla), yani entegrasyonunu bugünden yazıp deneyebilirsin. İadeler her durumda çalışır.
Akış#
sendInvoiceile sohbete fatura gönderirsin ya dacreateInvoiceLinkile bağlantı üretirsin.- Kullanıcı öde'ye basar → sana
pre_checkout_querygelir. - 10 saniye içinde
answerPreCheckoutQueryile onayla (ok: true) ya da nedenini yazarak reddet (stok bitti vb.). - Onaylarsan ödeme tahsil edilir → sana
message.successful_paymentgelir. - Ürünü teslim et.
successful_payment.invoice_payloadsenin faturaya koyduğun sipariş kimliğidir.
bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/sendInvoice" -H 'Content-Type: application/json' -d '{
"chat_id": 4185489292941965,
"title": "Pro tema paketi",
"description": "12 özel tema, ömür boyu",
"payload": "siparis-8f3a2c",
"currency": "INK",
"prices": [{"label":"Pro tema","amount":250}]
}'
pythonfrom telegram.ext import PreCheckoutQueryHandler, MessageHandler, filters
async def on_onay(update, context):
q = update.pre_checkout_query
if stokta_var_mi(q.invoice_payload):
await q.answer(ok=True)
else:
await q.answer(ok=False, error_message="Üzgünüz, bu ürün tükendi.")
async def odendi(update, context):
p = update.message.successful_payment
teslim_et(p.invoice_payload, p.telegram_payment_charge_id)
app.add_handler(PreCheckoutQueryHandler(on_onay))
app.add_handler(MessageHandler(filters.SUCCESSFUL_PAYMENT, odendi))
Fatura kuralları#
currency:INKya daXTR(Telegram kodun değişmesin diye). Hangisini yazdıysan yanıtlar ve iadeler o kodu taşır. 1 birim = 1 Ink.- Tek fiyat kalemi, tutar 1–10.000. Bahşiş yoktur (
STARS_INVOICE_INVALID).provider_tokenboş bırakılır. telegram_payment_charge_idbc_…biçimindedir; iade için sakla.provider_payment_charge_idboş döner.createInvoiceLinkhttps://app.inkiveta.com/bot/fatura/<kod>döner. Mini App içindeTelegram.WebApp.openInvoice(url)ile açılır. Uygulaması olmayan biri bağlantıyı tarayıcıda açarsa "uygulamada aç / indir" sayfası görür.- Kullanıcının Ink+ üyeliğindeki "sınırsız Ink" uygulama alışverişinde geçmez; ödeme gerçek bakiyeden düşer.
- Gerçek ortamda kendi uygulamandan alışveriş yapamazsın (test ortamında yapabilirsin).
- Sohbette güzel bir ödeme kartı için [
ink_pay](/gelistiriciler/bilesenler#ink-pay) ve [payment_status](/gelistiriciler/bilesenler#payment-status) bileşenlerini kullanabilirsin.
Abonelik#
- Yalnız
createInvoiceLink+subscription_period: 2592000(30 gün). - Yenileme başarısız olursa 3 gün boyunca günde bir denenir, sonra askıya alınır.
- Her durum değişikliğinde
subscriptionupdate'i gelir:state=active,canceled,failedya dapaused(ödemeler genel olarak kapatıldığında dönem sonunda; iptal sayılmaz). - Aboneliği sen bitirmek istersen:
editUserStarSubscription(is_canceled: true).
Ücretli içerik#
sendPaidMedia (star_count 1–10.000, en çok 10 foto/video): kullanıcı ödeyince içerik açılır ve sana purchased_paid_media gelir.
Kazanç#
- Platform payı %10 (
floor(tutar × 0,10)); kalanı senindir. - Kazanç 14 gün bekler (abonelikte gün gün), sonra "kullanılabilir" olur. Atölye → Kazançlar'dan Ink cüzdanına aktarırsın.
- Son 30 günün satışlarının %10'u iade rezervi olarak tutulur.
- Ink paraya çevrilemez: uygulama kazancı yalnız Ink'tir.
getMyStarBalancevegetStarTransactions(offset ≤ 5.000) Ink hesabını gösterir.
İade#
refundStarPayment(user_id, telegram_payment_charge_id) ödemeyi bir kez ve kalan tutarın tamamıyla iade eder. Ekipte Destek rolündekiler de Atölye'den iade onaylayabilir.
- İadenin kaynağı sırayla: o ödemenin bekleyen kazancı → uygulamanın kullanılabilir kazancı → senin cüzdanın → kalanı sahip borcu.
- Borç varken kazanç aktaramazsın; borç 1.000 Ink'i aşarsa bütün uygulamalarında ödeme kabulü durur. İade borcu 1.000 Ink'in üstüne çıkaracaksa iade yapılmaz:
400 Bad Request: REFUND_DEBT_LIMIT. - 14 günlük pencere geçmiş bir ödemenin iadesi borç üretmez: tutar senin cüzdanından alınır, yetmezse
400 Bad Request: REFUND_WALLET_INSUFFICIENT. - Uygulama devredildiyse eski sahibin dönemine ait ödeme iade edilemez:
400 Bad Request: REFUND_PREVIOUS_OWNER(alıcı Destek'e başvurur). - Uygulama silinince aktif aboneliklere kalan gün oranında iade her durumda yapılır.
Fiziksel ürün ve hizmet#
Telegram'ın provider_token modeli (kendi iyzico/PayTR üye işyeri hesabını bağlayıp TL ile satış) altyapıda hazırdır ama şu an kapalıdır; açıldığında bu sayfada duyurulacak. Fiziksel ürün ve hizmet Ink ile satılamaz (mağaza kuralı). inki_product_class alanı (digital | physical) ürün sınıfını belirtir; digital + provider_token → 400 PAYMENT_PROVIDER_INVALID, INK/XTR + provider_token → 400 CURRENCY_INVALID.
Test ödemeleri#
Test ortamında her uygulamanın 10.000 test Ink'lik ayrı bir cüzdanı vardır (Atölye → Test'ten sıfırlanır). Sahip kendi test uygulamasından alışveriş yapabilir; olay simülatörü "ödeme başarılı / reddedildi / iade isteği" olaylarını tek tıkla üretir. Gerçek Ink'e hiç dokunulmaz. Ayrıntı: Test ortamı.