Ana içeriğe geç

Abonelik

Abonelik, kalemlerinin tutarını günlük, haftalık, aylık ya da yıllık dönemlerle tahsil eder. İlk dönem gateway'in ödeme sayfasında ödenir ve kart bu ödemede saklanır. Sonraki dönemler müşterinin varsayılan kayıtlı kartından çekilir.

Ön koşullar​

  • Çalışma alanınızda Abonelikler ve Kayıtlı Kartlar modülleri açık olmalıdır; Abonelikler açılınca Kayıtlı Kartlar da açılır.
  • Aboneliğin ödeneceği hesap kart saklamalı ve 3D ödeme almalıdır.
  • Abonelik müşteri referansıyla (customer.reference) açılır; kart bu referansın altında saklanır ve sonraki dönemler bu referanstaki varsayılan karttan çekilir.

Yaşam döngüsü​

  1. Açma — create-subscription ç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 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ı aboneliğin güncel kalemlerinden hesaplanır; ilk dönemde uygulanan kupon yenilemelere uygulanmaz. Tutar müşterinin varsayılan kartından, ilk ödemenin yapıldığı modda (test ya da canlı) çekilir.
  4. Başarısız yenileme — Kart reddederse çekim 3, 6, 9 ve 12 saat arayla yeniden denenir (toplam 5 deneme). Hepsi başarısız olursa ya da müşterinin varsayılan kartı yoksa abonelik past_due olur ve subscription.checkout_url dönemin ödeme sayfasını gösterir.
  5. past_due sonrası ödeme — Dönem checkout_url üzerinden ödenirse abonelik active olur. Dönemin bitiş zamanı geçmişse yeni dönem ödeme anından başlar. Ödemede kullanılan kart varsayılan kart olur.
  6. Bitiş — renewal_limit verildiyse o kadar dönem ödenip son dönem bittiğinde abonelik completed olur. İptal edilen abonelik ödenmiş dönemin sonunda cancelled olur.

Durum değişiklikleri, panelde Ödeme Ayarları → Webhook sayfasında olaylara tanımladığınız adreslere webhook ile bildirilir. Webhook kullanmadan durumu retrieve-subscriptions ile sorabilirsiniz.

Durumlar​

statusAnlamı
pendingİlk dönem ödenmedi.
activeÖdenmiş bir dönemin içinde (iptal edilmişse cancelled_at dolu).
past_dueYenileme tahsil edilemedi; dönem checkout_url üzerinden ödenmeyi bekliyor. Süre sınırı yoktur.
cancelledİptal edildi ve sona erdi.
completedrenewal_limit kadar dönem ödendi ve son dönem bitti.

Açma​

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

use Gurmehub\Odemehub\Enum\Period;
use Gurmehub\Odemehub\Request\{CreateSubscription, Customer, Item, RetrieveSubscriptions};

$created = $client->createSubscription(new CreateSubscription(
reference: 'ABO-4471',
period: Period::Monthly,
successUrl: 'https://magazam.com/tesekkurler',
items: [new Item(name: 'Premium üyelik', unitAmount: '149.90', quantity: 1, taxRate: '20')],
customer: new Customer(reference: 'musteri-88'),
renewalLimit: 12,
));

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

// Sonra:
$current = $client->retrieveSubscriptions(RetrieveSubscriptions::byToken($token))->subscriptions[0] ?? null;

reference tekil değildir. Aynı reference ile create-subscription her çağrıldığında yeni bir abonelik ve yeni bir subscription.token açılır; önceki abonelikler olduğu gibi kalır ve istek 422 dönmez. İlk dönem ödenmediyse aynı referansla yeni abonelik açıp tarayıcıyı yeni checkout_url adresine yönlendirebilirsiniz. Var olan abonelik yalnızca token'ıyla update-subscription üzerinden değişir. Bkz. Aynı referansla tekrarlanan create-* istekleri.

Kupon​

API'de kupon alanı yoktur; kupon kodu ilk dönemin ödeme sayfasında girilir ve yalnızca ilk dönemin tutarından düşülür. retrieve-subscriptions yanıtında discount bu kuponu {code, amount} olarak gösterir. Aboneliğin subtotal, tax_amount ve amount alanları indirimsiz bir dönemin tutarıdır; ilk dönem için çekilen indirimli tutar ilk dönemin renewal.amount alanındadır. Webhook gövdeleri discount taşımaz. Bkz. Kupon ve discount.

Değiştirmek ve iptal etmek​

update-subscription yalnızca gönderilen alanları değiştirir:

  • items gönderilirse ödenmemiş dönemlerin tutarı yeniden hesaplanır; sonraki yenilemeler yeni kalemlerle çekilir.
  • renewal_limit şimdiye kadar ödenen dönem sayısının altına inemez; null sınırı kaldırır.
  • İlk dönem ödendikten sonra yalnızca iptal (status), renewal_limit, period ve kalem fiyatları (items[].unit_amount) değiştirilebilir; kalemler aynı kalmalıdır. Ödeme hesabı, para birimi, adresler ve customer gönderilemez; abonelik açıldığı gibi devam eder.
  • İptal: subscription.status: "cancelled". Para iade edilmez. Süren ödenmiş dönem varsa abonelik dönem sonuna kadar active kalır (cancelled_at dolu, next_payment_at null), sonra cancelled olur; yoksa hemen cancelled olur. İptal edilen abonelik bir daha değiştirilemez.

Kart​

  • Yenileme, müşterinin varsayılan kartından çekilir. Müşterinin başka bir kartını varsayılan yapmak için update-saved-card kullanın.
  • Varsayılan kart silinirse müşterinin en son saklanan kartı varsayılan olur. Hiç kart kalmazsa sonraki yenileme past_due olur.

İade​

Abonelik ödemeleri retrieve-payments listesinde subscription.token alanıyla görünür; bu ödemelerin token değeriyle refund-payment ve cancel-payment çağrılabilir. İade aboneliğin durumunu değiştirmez.