Abonelikler

Kayıtlı kartlarla yinelenen tahsilat. Oluşturun, duraklatın, devam ettirin, yeniden deneyin, iptal edin ve anında tahsilat tetikleyin.

12 endpoints

POST/v1/subscriptionsOptional

Yinelenen bir abonelik oluşturur. cardToken isteğe bağlıdır — belirtilmezse müşterinin varsayılan kayıtlı kartı kullanılır. İsteğe bağlı bir Idempotency-Key başlığını destekler.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`storeId`	string	Zorunlu	Store the subscription belongs to
`customerId`	string	Zorunlu	Customer being billed
`amountMinor`	integer	Zorunlu	Per-cycle amount in kuruş
`currency`	string	Zorunlu	Always "TRY"
`intervalCount`	integer	Zorunlu	Number of interval units per cycle
`intervalUnit`	string	Zorunlu	day\|week\|month\|year
`cardToken`	string	İsteğe Bağlı	Saved card token (defaults to the customer default card)
`trialEndAt`	string	İsteğe Bağlı	ISO 8601 — start trialing until this date
`generateInvoices`	boolean	İsteğe Bağlı	Generate an invoice each renewal
`description`	string	İsteğe Bağlı	Subscription description

JSONİstek Örneği

{
  "storeId": "sto_5a6b7c8d",
  "customerId": "cus_a1b2c3d4e5f6",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month"
}

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "customerId": "cus_a1b2c3d4e5f6",
  "publicHash": "kQ7rS1tV5wY8zaB3xK9mN2",
  "status": "active",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month",
  "cycleNumber": 0,
  "nextChargeAt": "2026-05-13T10:00:00Z",
  "cardLast4": "4321",
  "cardBrand": "visa",
  "createdAt": "2026-04-13T10:00:00Z"
}

GET/v1/subscriptionsOptional

Keyset sayfalama ile abonelikleri listeler. Filtreler: storeId, customerId, status, from, to.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`storeId`	string	İsteğe Bağlı	Filter by store
`customerId`	string	İsteğe Bağlı	Filter by customer
`status`	string	İsteğe Bağlı	trialing\|active\|past_due\|paused\|cancelled\|expired
`limit`	integer	İsteğe Bağlı	Page size
`cursor`	string	İsteğe Bağlı	Opaque keyset cursor

JSONYanıt Örneği

{
  "items": [
    {
      "id": "sub_5e6f70819a2b",
      "storeId": "sto_5a6b7c8d",
      "status": "active",
      "amountMinor": 50000,
      "currency": "TRY",
      "intervalCount": 1,
      "intervalUnit": "month",
      "nextChargeAt": "2026-05-13T10:00:00Z",
      "createdAt": "2026-04-13T10:00:00Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEzVDEwOjAwOjAwWiJ9"
}

GET/v1/subscriptions/{id}Optional

Bir aboneliği kimliğine göre getirir.

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "customerId": "cus_a1b2c3d4e5f6",
  "status": "active",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month",
  "cycleNumber": 1,
  "nextChargeAt": "2026-05-13T10:00:00Z",
  "cardLast4": "4321",
  "cardBrand": "visa",
  "createdAt": "2026-04-13T10:00:00Z"
}

GET/v1/subscriptions/{id}/chargesOptional

Bir abonelik için döngü bazında çekim geçmişi.

JSONYanıt Örneği

{
  "items": [
    {
      "cycleNumber": 1,
      "paymentId": "pay_1a2b3c4d5e6f",
      "status": "captured",
      "amountMinor": 50000,
      "chargedAt": "2026-04-13T10:00:02Z"
    }
  ]
}

POST/v1/subscriptions/{id}/cancelOptional

Aboneliği hemen (atPeriodEnd=false) veya mevcut dönemin sonunda (atPeriodEnd=true) iptal eder.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`atPeriodEnd`	boolean	Zorunlu	Cancel now (false) or at period end (true)
`reason`	string	İsteğe Bağlı	Cancellation reason

JSONİstek Örneği

{
  "atPeriodEnd": true,
  "reason": "Customer requested"
}

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "status": "active",
  "cancelAtPeriodEnd": true
}

POST/v1/subscriptions/{id}/pauseOptional

Aktif veya deneme sürecindeki bir aboneliği duraklatır. Reconciler, duraklatılmış kayıtları dikkate almaz.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "status": "paused"
}

POST/v1/subscriptions/{id}/resumeOptional

Duraklatılmış bir aboneliği devam ettirir; bir sonraki tick'te hemen bir çekim denemesi yapılır.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "status": "active"
}

POST/v1/subscriptions/{id}/retryOptional

past_due durumundaki bir abonelik için nextChargeAt değerini şimdiki zamana çeker, böylece reconciler bir sonraki tick'te yeniden dener.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "sub_5e6f70819a2b",
  "status": "past_due",
  "nextChargeAt": "2026-04-13T12:00:00Z"
}

POST/v1/subscriptions/{id}/charge-nowOptional

nextChargeAt beklenmeden anında bir yenileme çekimi tetikler. Kuyruğa alındığını bildiren bir yanıt döner; durum charging dışına çıkana kadar GET /v1/subscriptions/{id} ile sorgulama yapın.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "status": "queuing",
  "subscriptionId": "sub_5e6f70819a2b",
  "expectedAt": "2026-04-13T10:01:00Z",
  "checkAt": "/v1/subscriptions/sub_5e6f70819a2b"
}

GET/v1/public/subscriptions/{hash}Optional

Herkese açık portal bağlantısı üzerinden alıcıya yönelik görüntüleme (publicHash bearer görevi görür).

JSONYanıt Örneği

{
  "publicHash": "kQ7rS1tV5wY8zaB3xK9mN2",
  "merchantName": "Acme Store",
  "status": "active",
  "amountMinor": 50000,
  "currency": "TRY",
  "intervalCount": 1,
  "intervalUnit": "month",
  "cardLast4": "4321",
  "cardBrand": "visa",
  "nextChargeAt": "2026-05-13T10:00:00Z"
}

POST/v1/public/subscriptions/{hash}/cancelOptional

Portal üzerinden alıcı tarafında iptal işlemi.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`atPeriodEnd`	boolean	İsteğe Bağlı	Cancel at period end (default true)

JSONİstek Örneği

{
  "atPeriodEnd": true
}

JSONYanıt Örneği

{
  "publicHash": "kQ7rS1tV5wY8zaB3xK9mN2",
  "status": "active",
  "cancelAtPeriodEnd": true
}

POST/v1/public/subscriptions/{hash}/update-card-sessionOptional

Alıcı "Kartı güncelle"ye tıkladığında bu uç nokta tetiklenir: bir card_update_only ödeme oturumu oluşturur ve URL'sini döndürür.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "sessionId": "2a7b8c9d-0e1f-3f1c-9a2e-6b4d4e8a9c1f",
  "checkoutUrl": "https://pay.kvell.group/s/2a7b8c9d-0e1f-3f1c-9a2e-6b4d4e8a9c1f",
  "expiresAt": "2026-04-13T11:00:00Z"
}

Kategori Özeti

Toplam Endpoint

Ana Domain

api.pay.kvell.group