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ü
- Açma —
create-subscriptionçağrılır. Abonelikpendingaçılır; yanıtsubscription.tokenvesubscription.checkout_urldöner. - İlk ödeme — Tarayıcı
checkout_urladresine yönlendirilir. Ödeme başarılı olursa kart saklanır ve müşterinin varsayılan kartı olur; abonelikactiveolur ve tarayıcısuccess_urladresine dönüş formunuPOSTeder. - 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.
- 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_dueolur vesubscription.checkout_urldönemin ödeme sayfasını gösterir. past_duesonrası ödeme — Dönemcheckout_urlüzerinden ödenirse abonelikactiveolur. Dönemin bitiş zamanı geçmişse yeni dönem ödeme anından başlar. Ödemede kullanılan kart varsayılan kart olur.- Bitiş —
renewal_limitverildiyse o kadar dönem ödenip son dönem bittiğinde abonelikcompletedolur. İptal edilen abonelik ödenmiş dönemin sonundacancelledolur.
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
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 | İptal edildi ve sona erdi. |
completed | renewal_limit kadar dönem ödendi ve son dönem bitti. |
Açma
Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.
- PHP
- Node.js
- Python
- Java
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;
const created = await client.createSubscription({
reference: 'ABO-4471',
period: 'monthly',
successUrl: 'https://magazam.com/tesekkurler',
items: [{ name: 'Premium üyelik', unitAmount: '149.90', quantity: 1, taxRate: '20' }],
customer: { reference: 'musteri-88' },
renewalLimit: 12,
});
const token = created.subscription.token; // saklayın
res.redirect(created.subscription.checkoutUrl!);
// Sonra:
const [current] = (await client.retrieveSubscriptions({ token })).subscriptions;
from odemehub.enums import Period
from odemehub.request import CreateSubscription, Customer, Item, RetrieveSubscriptions
created = client.create_subscription(CreateSubscription(
reference="ABO-4471",
period=Period.MONTHLY,
success_url="https://magazam.com/tesekkurler",
items=[Item(name="Premium üyelik", unit_amount="149.90", quantity=1, tax_rate="20")],
customer=Customer(reference="musteri-88"),
renewal_limit=12,
))
token = created.subscription.token # saklayın
# Sonra:
current = client.retrieve_subscriptions(RetrieveSubscriptions(token=token)).subscriptions
import com.odemehub.enums.Period;
import com.odemehub.request.CreateSubscription;
import com.odemehub.request.Customer;
import com.odemehub.request.Item;
import com.odemehub.request.RetrieveSubscriptions;
import java.util.List;
var created = client.createSubscription(CreateSubscription.builder()
.reference("ABO-4471")
.period(Period.MONTHLY)
.successUrl("https://magazam.com/tesekkurler")
.items(List.of(Item.builder().name("Premium üyelik").unitAmount("149.90").quantity(1).taxRate("20").build()))
.customer(Customer.builder().reference("musteri-88").build())
.renewalLimit(12)
.build());
String token = created.getSubscription().getToken(); // saklayın
// Sonra:
var current = client.retrieveSubscriptions(RetrieveSubscriptions.byToken(token)).getSubscriptions();
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:
itemsgö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;nullsınırı kaldırır.- İlk dönem ödendikten sonra yalnızca iptal (
status),renewal_limit,periodve kalem fiyatları (items[].unit_amount) değiştirilebilir; kalemler aynı kalmalıdır. Ödeme hesabı, para birimi, adresler vecustomergönderilemez; abonelik açıldığı gibi devam eder. - İptal:
subscription.status: "cancelled". Para iade edilmez. Süren ödenmiş dönem varsa abonelik dönem sonuna kadaractivekalır (cancelled_atdolu,next_payment_atnull), sonracancelledolur; yoksa hemencancelledolur. İ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-cardkullanın. - Varsayılan kart silinirse müşterinin en son saklanan kartı varsayılan olur. Hiç kart kalmazsa sonraki yenileme
past_dueolur.
İ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.