Abonelik

Abonelik, recurring türündeki ürünler için aylık ya da yıllık dönemlerle tahsilat yapar. İlk dönem gateway'in ödeme sayfasında ödenir ve ödemede kart saklanır. Sonraki dönemler müşterinin varsayılan kayıtlı kartından çekilir.

Ön koşullar

• Çalışma alanının planı abonelikleri ve kayıtlı kartları kapsamalıdır.
• Aboneliğin ödeneceği hesap kart saklamayı ve 3D ödemeyi desteklemelidir.
• Abonelikteki ürünler aynı kanalda save-product ile type: recurring olarak kaydedilmiş ve is_active: true olmalıdır. Ürünlerin period ve currency değerleri aynı olmalıdır.

Yaşam döngüsü

1. Açma — subscription-payment çağrılır. Abonelik pending açılır; yanıt subscription.token ve subscription.checkout_url döner.
2. İlk ödeme — Tarayıcı checkout_url adresine yönlendirilir. Ödeme başarılı olursa kart saklanır ve müşterinin varsayılan kartı olur; abonelik active olur, active webhook'u gönderilir ve tarayıcı success_url adresine dönüş formunu POST eder.
3. Yenileme — Dönem bittiğinde yeni dönem açılır ve tutarı katalogdaki güncel fiyatlardan hesaplanır. Tutar müşterinin varsayılan kartından çekilir. Başarılı çekimde active webhook'u gönderilir.
4. Başarısız yenileme — Çekim 3, 6, 9 ve 12 saat aralıklarla yeniden denenir (toplam 5 deneme). Hepsi başarısız olursa abonelik past_due olur, past_due webhook'u gönderilir ve subscription.checkout_url dönemin ödeme sayfasını gösterir. Müşterinin kayıtlı kartı yoksa yeniden deneme yapılmaz.
5. past_due sonrası ödeme — Dönem checkout_url üzerinden ödenirse abonelik active olur ve active webhook'u gönderilir. Dönemin bitiş zamanı geçmişse yeni dönem ödeme anından başlar. Ödemede kullanılan kart varsayılan kart olur.
6. İptal — cancel-subscription. İade yapılmaz; ödenmiş dönem bitene kadar abonelik active kalır.

Durumlar

status	Anlamı
pending	İlk dönem ödenmedi.
active	Ödenmiş bir dönemin içinde (iptal edilmişse cancelled_at dolu).
past_due	Yenileme tahsil edilemedi; dönem checkout_url üzerinden ödenmeyi bekliyor. Süre sınırı yoktur.
cancelled	Sona erdi.

Fiyat

• subscription.amount içinde bulunulan dönemin tutarıdır.
• İlk dönem için kalemde unit_amount gönderilirse yalnızca ilk dönem o fiyatla hesaplanır.
• Yenileme dönemlerinin tutarı, dönem açılırken katalogdaki fiyatlardan hesaplanır. save-product ile yapılan fiyat değişikliği yürüyen dönemi değiştirmez.

Ortam

Abonelik, ilk ödemenin yapıldığı moda (is_test) bağlanır. Yenilemeler yalnızca aynı modda saklanmış varsayılan karttan çekilir.

Örnek

PHP

use Gurmehub\Odemehub\Request\{RetrieveSubscription, SubscriptionItem, SubscriptionPayment};

$subscription = $client->subscriptionPayment(new SubscriptionPayment(
    channelReference: 'UYELIK-4471',
    items: [new SubscriptionItem(channelReference: 'PREMIUM-AYLIK')],
    successUrl: 'https://magazam.com/tesekkurler',
    customer: $customer,
    webhookUrl: 'https://magazam.com/odemehub/abonelik',
));

$token = $subscription->token;          // saklayın
header('Location: '.$subscription->checkoutUrl);

// Sonra:
$current = $client->retrieveSubscription(new RetrieveSubscription(subscriptionToken: $token));

Node.js

const subscription = await client.subscriptionPayment({
    channelReference: 'UYELIK-4471',
    items: [{ channelReference: 'PREMIUM-AYLIK' }],
    successUrl: 'https://magazam.com/tesekkurler',
    customer,
    webhookUrl: 'https://magazam.com/odemehub/abonelik',
});

const token = subscription.token;       // saklayın
res.redirect(subscription.checkoutUrl!);

// Sonra:
const current = await client.retrieveSubscription({ subscriptionToken: token });

Python

from odemehub.request import RetrieveSubscription, SubscriptionItem, SubscriptionPayment

subscription = client.subscription_payment(SubscriptionPayment(
    channel_reference="UYELIK-4471",
    items=[SubscriptionItem(channel_reference="PREMIUM-AYLIK")],
    success_url="https://magazam.com/tesekkurler",
    customer=customer,
    webhook_url="https://magazam.com/odemehub/abonelik",
))

token = subscription.token              # saklayın

# Sonra:
current = client.retrieve_subscription(RetrieveSubscription(subscription_token=token))

Java

import com.odemehub.request.RetrieveSubscription;
import com.odemehub.request.SubscriptionItem;
import com.odemehub.request.SubscriptionPayment;
import java.util.List;

var subscription = client.subscriptionPayment(SubscriptionPayment.builder()
    .channelReference("UYELIK-4471")
    .items(List.of(SubscriptionItem.of("PREMIUM-AYLIK")))
    .successUrl("https://magazam.com/tesekkurler")
    .customer(customer)
    .webhookUrl("https://magazam.com/odemehub/abonelik")
    .build());

String token = subscription.getToken(); // saklayın

// Sonra:
var current = client.retrieveSubscription(new RetrieveSubscription(token));

Bildirimler

Durum değişiklikleri webhook_url adresine gönderilir: Abonelik Webhook'u. webhook_url verilmediyse durum retrieve-subscription ile sorgulanır.