Abonelik eventleri
subscription.payment_failed ve subscription.cancelled — başarısız yenilemeler ve kapanan abonelikler.
Abonelikli bir ürün sattığınızda müşteri bir kez abone olur, Hikie her dönem ücreti otomatik çeker. Erişimi kendi tarafınızda yönetmek için üç event yeterli:
| Event | Ne zaman gider | Satıcı ne yapar |
|---|---|---|
order.paid | Aboneliğin ilk ödemesinde (isSubscriptionStart: true) ve her başarılı yenilemede (isRecurring: true) | Erişimi açar ya da uzatır |
subscription.payment_failed | Yenileme çekimi her başarısız olduğunda. Hikie yaklaşık 24 saat arayla toplam 3 kez dener | İsterse müşteriye "kartını güncelle" der. Denemeler sürerken erişim açık kalır |
subscription.cancelled | Abonelik hangi sebeple kapanırsa kapansın, kapandığı anda. Gövdede erişimin ne zaman biteceği yazar | Erişimi o tarihte kapatır |
subscription.created ve subscription.renewed yok. İlk ödeme ve her yenileme
order.paid olarak gelir; isSubscriptionStart ve isRecurring bayrakları
ikisini ayırır. Bkz. Abonelik satın alımları.
stateDiagram-v2
[*] --> Active: order.paid (isSubscriptionStart)
Active --> Active: order.paid (isRecurring)
Active --> PastDue: subscription.payment_failed
PastDue --> Active: order.paid (isRecurring)
PastDue --> Closed: subscription.payment_failed (son deneme) ardından subscription.cancelled
Active --> Closed: subscription.cancelled
Closed --> [*]
Erişim ne zaman kapanır
subscription.cancelled, abonelik yenilenmeyi bıraktığında gider. Erişimin
tam o anda bittiği anlamına gelmez — kesin tarih dateAccessEnds alanında,
neden kapandığı autoRenew.reason alanında yazar.
autoRenew.reason | autoRenew.cancelledBy | Ne oldu | Erişim |
|---|---|---|---|
user-requested | customer | Müşteri yenilemeyi kapattı | Ödediği dönemin sonuna kadar |
user-requested | merchant | Siz panelden yenilemeyi kapattınız | Ödediği dönemin sonuna kadar |
refund | merchant | Son ödeme iade edildi | Ödediği dönemin sonuna kadar |
payment-failed | system | 3 çekim denemesi de başarısız oldu | Hemen kapanır — dateAccessEnds iptal anıdır |
plan-completed | system | Sayılı plan (örneğin 6 ay) son çekimine ulaştı | Son ödenen dönemin sonunda |
subscription.cancelled geldiği an erişimi kesmeyin — dateAccessEnds
tarihinde kesin. payment-failed için bu tarih "şimdi"dir, diğer nedenlerde
gelecektedir.
subscription.payment_failed
Bir yenileme çekimi reddedildi. Her denemede bir kez gider; yani tek bir
kötü yenileme en fazla üç tane gönderebilir. Deneme dizisinde nerede olduğunuzu
lastPayment.attemptNumber ve lastPayment.nextAttemptAt söyler.
{
"subscriptionId": "66b2c1a70f5e8d4319ab72c6",
"status": "pastDue",
"storeSlug": "magazam",
"customerId": "66a0d31f4b7c2e0018e5f9a2",
"cycle": 3,
"dateStarted": "2026-08-07T09:19:58.000Z",
"dateAccessEnds": "2026-10-07T09:19:58.000Z",
"currency": "TRY",
"plan": {
"membershipId": "669fbc8e2a1d4c0021b3e847",
"title": "VIP Üyelik",
"priceType": "recurring",
"intervalMonths": 1,
"price": "249.90"
},
"customerInfo": {
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "[email protected]",
"phone": "+905321234567"
},
"autoRenew": {
"enabled": true,
"dateCancelled": null,
"cancelledBy": null,
"reason": null
},
"sourceOrder": { "orderId": "17716204135268844HKS" },
"lastPayment": {
"status": "failed",
"total": "249.90",
"date": "2026-10-07T03:00:44.000Z",
"failureReason": "Yetersiz bakiye",
"attemptNumber": 1,
"maxAttempts": 3,
"nextAttemptAt": "2026-10-08T03:00:44.000Z",
"isFinalAttempt": false
}
}Son denemede isFinalAttempt true, nextAttemptAt null olur. Hemen ardından
reason: "payment-failed" ile bir subscription.cancelled gelir.
Bu event erişimi kesme sinyali değildir. Bugün reddedilen kart yarın çoğu zaman sorunsuz çekilir; erken kesmek yalnızca destek talebi üretir.
async function onSubscriptionPaymentFailed(data) {
if (data.lastPayment.isFinalAttempt) return; // ardından subscription.cancelled gelir
await notifyUser(
data.customerInfo.email,
`Kartınızdan çekim yapamadık. ${data.lastPayment.nextAttemptAt} tarihinde tekrar deneyeceğiz.`,
);
}subscription.cancelled
Abonelik yenilenmeyi bıraktı.
{
"subscriptionId": "66b2c1a70f5e8d4319ab72c6",
"status": "cancelled",
"storeSlug": "magazam",
"customerId": "66a0d31f4b7c2e0018e5f9a2",
"cycle": 3,
"dateStarted": "2026-08-07T09:19:58.000Z",
"dateAccessEnds": "2026-11-07T09:19:58.000Z",
"currency": "TRY",
"plan": {
"membershipId": "669fbc8e2a1d4c0021b3e847",
"title": "VIP Üyelik",
"priceType": "recurring",
"intervalMonths": 1,
"price": "249.90"
},
"customerInfo": {
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "[email protected]",
"phone": "+905321234567"
},
"autoRenew": {
"enabled": false,
"dateCancelled": "2026-10-20T18:41:07.000Z",
"cancelledBy": "customer",
"reason": "user-requested"
},
"sourceOrder": { "orderId": "17716204135268844HKS" },
"lastPayment": null
}async function onSubscriptionCancelled(data) {
// dateAccessEnds'e kadar erişim açık kalır — dönem zaten ödenmiş.
await db.markCancelled(data.subscriptionId, {
reason: data.autoRenew.reason,
accessUntil: data.dateAccessEnds,
});
await scheduleAccessRemoval(data.customerId, new Date(data.dateAccessEnds));
}Alanlar
İki event aynı gövdeyi paylaşır. Yalnızca lastPayment farklıdır.
Alan
Tip
Tekrarlar ve sıralama
| Event | Kaç kez gider |
|---|---|
subscription.payment_failed | Başarısız deneme başına bir kez |
subscription.cancelled | İptal başına bir kez. Müşteri yeniden abone olup tekrar iptal ederse yeni bir event gelir |
Teslimat yeniden denenebildiği için aynı event iki kez gelebilir —
Hikie-Webhook-Id ile ayıklayın. İki farklı event sırasız da gelebilir; bir
değişikliği uygulamadan önce Tekrarları yönetme
sayfasındaki gibi Hikie-Occurred-At'i karşılaştırın.
const occurredAt = new Date(req.get('Hikie-Occurred-At'));
const current = await db.getMembership(payload.subscriptionId);
if (current && new Date(current.lastEventAt) >= occurredAt) {
return; // daha eski bir event — atla
}