Dokümantasyon

08 — Abonelik Satışı ve Ödeme Yönlendirme

Kimin için: Uygulama içinden abonelik veya paket satışı yapan geliştiriciler.
Ön koşul: TALOST ID üzerinde tanımlanmış en az bir ücretli plan.
Tahmini süre: 15 dakika.

Ne Öğreneceksiniz

Kullanıcıyı uygulamanız içinden TALOST ID güvenli ödeme sayfasına yönlendirmeyi,
POST /api/v1/billing/checkout uç noktasının kullanımını,
Ödeme tamamlandığında kullanıcının geri dönüşünü ve hakların tanımlanmasını.

Ödeme ve Satın Alma Mimarisi

TALOST ID, tüm ödeme altyapısını (PayTR entegrasyonu, 3D Secure, kredi kartı saklama, fatura ve KDV hesaplama) merkezi olarak yönetir. Uygulamanızın doğrudan kredi kartı bilgisiyle temas etmesine gerek yoktur:

Diyagram (Mermaid)

sequenceDiagram
    autonumber
    actor User as Kullanıcı
    participant App as Uygulamanız
    participant TalostBilling as TALOST ID Ödeme Motoru (/billing)
    participant PayTR as PayTR / Banka 3D Secure

    User->>App: "Pro Plana Yükselt" butonuna tıklar
    App->>TalostBilling: POST /api/v1/billing/checkout (plan_code, success_url)
    TalostBilling-->>App: 200 OK (checkout_url)
    App-->>User: checkout_url adresine yönlendirir
    User->>TalostBilling: Fatura ve Kart bilgilerini girer
    TalostBilling->>PayTR: 3D Secure doğrulaması
    PayTR-->>User: SMS Onayı
    PayTR-->>TalostBilling: Ödeme Başarılı
    TalostBilling-->>App: Webhook Gönderir (payment.succeeded, subscription.activated)
    TalostBilling-->>User: 302 Redirect (success_url?payment_id=XYZ)
    User->>App: Uygulamaya döner, hakları anında açılır

Adım Adım Entegrasyon

1. Checkout Oturumu Başlatma (`POST /api/v1/billing/checkout`)

Uygulamanızın arka ucundan aşağıdaki isteği gönderin:

Uç Nokta: POST {{ISSUER}}/api/v1/billing/checkout
Headers: Authorization: Bearer {{ACCESS_TOKEN}} veya X-Talost-Api-Key: {{API_KEY}}
Gövde:

json

{
  "app_slug": "talost-crm",
  "plan_code": "pro_monthly",
  "billing_cycle": "MONTHLY",
  "success_url": "https://app.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.com/pricing"
}

Başarılı Yanıt:

json

{
  "checkout_url": "https://id.talost.com/odeme/pay_01h8x9...",
  "session_id": "cs_01h8x9..."
}

Kod Örnekleri

TypeScript (Next.js Server Action veya API Rotası)

typescript

// app/api/billing/create-checkout/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { planCode, billingCycle } = await req.json();
  const token = req.headers.get("Authorization"); // Bearer token

  const res = await fetch(`${process.env.TALOST_ISSUER}/api/v1/billing/checkout`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: token || `Bearer ${process.env.TALOST_APP_API_KEY}`,
    },
    body: JSON.stringify({
      app_slug: process.env.TALOST_APP_SLUG,
      plan_code: planCode,
      billing_cycle: billingCycle || "MONTHLY",
      success_url: `${process.env.APP_URL}/dashboard?billing=success`,
      cancel_url: `${process.env.APP_URL}/pricing`,
    }),
  });

  const data = await res.json();
  if (!res.ok) {
    return NextResponse.json({ error: "Ödeme oturumu oluşturulamadı." }, { status: 400 });
  }

  // Kullanıcıyı data.checkout_url adresine yönlendirin
  return NextResponse.json({ checkoutUrl: data.checkout_url });
}

Sık Yapılan Hatalar

Güvenlik Uyarısı: Sadece URL Parametresine Güvenmeyin!
Kullanıcı ödeme sonrası `https://app.com/dashboard?billing=success` adresine yönlendiğinde, yalnızca URL'deki parametreye bakarak veritabanınızda kullanıcıya hak **tanımlamayın**. Kötü niyetli bir kullanıcı bu adresi tarayıcısına doğrudan yazabilir. Yetkiyi her zaman arka planda gelen **`payment.succeeded` veya `subscription.activated` Webhook'una** göre veya `/api/v1/apps/users/[sub]/entitlements` uç noktasını sunucudan sorgulayarak açın.

İlgili Sayfalar

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/app/api/v1/billing/checkout/route.ts

Son doğrulama: 2026-10-04 · Kaynak: `_envanter.md`, `src/app/api/v1/billing/checkout/route.ts`

Dokümantasyon

08 — Abonelik Satışı ve Ödeme Yönlendirme

Kimin için: Uygulama içinden abonelik veya paket satışı yapan geliştiriciler.
Ön koşul: TALOST ID üzerinde tanımlanmış en az bir ücretli plan.
Tahmini süre: 15 dakika.

Ne Öğreneceksiniz

Kullanıcıyı uygulamanız içinden TALOST ID güvenli ödeme sayfasına yönlendirmeyi,
POST /api/v1/billing/checkout uç noktasının kullanımını,
Ödeme tamamlandığında kullanıcının geri dönüşünü ve hakların tanımlanmasını.

Ödeme ve Satın Alma Mimarisi

Diyagram (Mermaid)

sequenceDiagram
    autonumber
    actor User as Kullanıcı
    participant App as Uygulamanız
    participant TalostBilling as TALOST ID Ödeme Motoru (/billing)
    participant PayTR as PayTR / Banka 3D Secure

    User->>App: "Pro Plana Yükselt" butonuna tıklar
    App->>TalostBilling: POST /api/v1/billing/checkout (plan_code, success_url)
    TalostBilling-->>App: 200 OK (checkout_url)
    App-->>User: checkout_url adresine yönlendirir
    User->>TalostBilling: Fatura ve Kart bilgilerini girer
    TalostBilling->>PayTR: 3D Secure doğrulaması
    PayTR-->>User: SMS Onayı
    PayTR-->>TalostBilling: Ödeme Başarılı
    TalostBilling-->>App: Webhook Gönderir (payment.succeeded, subscription.activated)
    TalostBilling-->>User: 302 Redirect (success_url?payment_id=XYZ)
    User->>App: Uygulamaya döner, hakları anında açılır

Adım Adım Entegrasyon

1. Checkout Oturumu Başlatma (`POST /api/v1/billing/checkout`)

Uygulamanızın arka ucundan aşağıdaki isteği gönderin:

Uç Nokta: POST {{ISSUER}}/api/v1/billing/checkout
Headers: Authorization: Bearer {{ACCESS_TOKEN}} veya X-Talost-Api-Key: {{API_KEY}}
Gövde:

json

{
  "app_slug": "talost-crm",
  "plan_code": "pro_monthly",
  "billing_cycle": "MONTHLY",
  "success_url": "https://app.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://app.com/pricing"
}

Başarılı Yanıt:

json

{
  "checkout_url": "https://id.talost.com/odeme/pay_01h8x9...",
  "session_id": "cs_01h8x9..."
}

Kod Örnekleri

TypeScript (Next.js Server Action veya API Rotası)

typescript

// app/api/billing/create-checkout/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { planCode, billingCycle } = await req.json();
  const token = req.headers.get("Authorization"); // Bearer token

  const res = await fetch(`${process.env.TALOST_ISSUER}/api/v1/billing/checkout`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: token || `Bearer ${process.env.TALOST_APP_API_KEY}`,
    },
    body: JSON.stringify({
      app_slug: process.env.TALOST_APP_SLUG,
      plan_code: planCode,
      billing_cycle: billingCycle || "MONTHLY",
      success_url: `${process.env.APP_URL}/dashboard?billing=success`,
      cancel_url: `${process.env.APP_URL}/pricing`,
    }),
  });

  const data = await res.json();
  if (!res.ok) {
    return NextResponse.json({ error: "Ödeme oturumu oluşturulamadı." }, { status: 400 });
  }

  // Kullanıcıyı data.checkout_url adresine yönlendirin
  return NextResponse.json({ checkoutUrl: data.checkout_url });
}

Sık Yapılan Hatalar

İlgili Sayfalar

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/app/api/v1/billing/checkout/route.ts

Son doğrulama: 2026-10-04 · Kaynak: `_envanter.md`, `src/app/api/v1/billing/checkout/route.ts`