hikiehikieDeveloper Documentation
Eventler

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:

EventNe zaman giderSatıcı ne yapar
order.paidAboneliğin ilk ödemesinde (isSubscriptionStart: true) ve her başarılı yenilemede (isRecurring: true)Erişimi açar ya da uzatır
subscription.payment_failedYenileme ç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.cancelledAbonelik hangi sebeple kapanırsa kapansın, kapandığı anda. Gövdede erişimin ne zaman biteceği yazarEriş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.reasonautoRenew.cancelledByNe olduErişim
user-requestedcustomerMüşteri yenilemeyi kapattıÖdediği dönemin sonuna kadar
user-requestedmerchantSiz panelden yenilemeyi kapattınızÖdediği dönemin sonuna kadar
refundmerchantSon ödeme iade edildiÖdediği dönemin sonuna kadar
payment-failedsystem3 çekim denemesi de başarısız olduHemen kapanır — dateAccessEnds iptal anıdır
plan-completedsystemSayı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.

subscription.payment_failed
{
  "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ı.

subscription.cancelled
{
  "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

EventKaç kez gider
subscription.payment_failedBaş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
}

Bu sayfada