Geliştirici paneli inkiveta.com

Ö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 enabled döner ve ödeme bileşenleri yerine fallback_text gö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ış#

  1. sendInvoice ile sohbete fatura gönderirsin ya da createInvoiceLink ile bağlantı üretirsin.
  2. Kullanıcı öde'ye basar → sana pre_checkout_query gelir.
  3. 10 saniye içinde answerPreCheckoutQuery ile onayla (ok: true) ya da nedenini yazarak reddet (stok bitti vb.).
  4. Onaylarsan ödeme tahsil edilir → sana message.successful_payment gelir.
  5. Ürünü teslim et. successful_payment.invoice_payload senin 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: INK ya da XTR (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_token boş bırakılır.
  • telegram_payment_charge_id bc_… biçimindedir; iade için sakla. provider_payment_charge_id boş döner.
  • createInvoiceLink https://app.inkiveta.com/bot/fatura/<kod> döner. Mini App içinde Telegram.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 subscription update'i gelir: state = active, canceled, failed ya da paused (ö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.
  • getMyStarBalance ve getStarTransactions (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ı.