Ana içeriğe geç

subscription-payment

POST /api/{team}/gateway/subscription-payment

recurring türündeki bir ya da birkaç ürün için abonelik açar. Bu istekte kart verisi gönderilmez ve çekim yapılmaz. Abonelik pending durumunda açılır ve yanıt, ilk dönemin ödeneceği gateway ödeme sayfasının adresini (subscription.checkout_url) döner. İlk ödemede kart saklanır; sonraki dönemler müşterinin varsayılan kayıtlı kartından çekilir. Akış: Abonelik rehberi.

Çalışma alanının planı abonelikleri kapsamıyorsa istek 403 ile reddedilir. Planın kayıtlı kartları da kapsaması gerekir.

Kimlik doğrulama​

X-Api-Key, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek​

{
  "subscription": {
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14",
    "channel_reference": "UYELIK-4471",
    "items": [
      { "channel_reference": "PREMIUM-AYLIK" },
      { "channel_reference": "EK-KULLANICI", "quantity": 3 }
    ],
    "success_url": "https://magazam.com/tesekkurler",
    "webhook_url": "https://magazam.com/odemehub/abonelik"
  },
  "customer": {
    "channel_reference": "musteri-88",
    "firstname": "Ahmet",
    "lastname": "Yılmaz",
    "email": "[email protected]",
    "phone": "05551112233",
    "address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
    "district": "Çankaya",
    "province": "Ankara",
    "country": "Türkiye"
  }
}

subscription​

AlanTipZorunluAçıklama
channel_tokenstring (UUID)evetÇalışma alanınıza ait kanalın token'ı.
channel_referencestringevetAboneliğin sizin sisteminizdeki kimliği. En çok 255 karakter, en az bir rakam.
itemsarrayevetEn az bir kalem.
success_urlstringevetİlk dönem ödendikten sonra dönüş POST'unun gönderileceği adres. http/https, en çok 2048 karakter.
cancel_urlstringhayırÖdeme sayfasında vazgeçme bağlantısı olarak verilen adres.
webhook_urlstringhayırAbonelik durumu değiştiğinde webhook gönderilecek adres. Gönderilmezse webhook gönderilmez.
payment_provider_tokenstring (UUID)hayırAboneliğin ödeneceği hesap. Hesabın hem kart saklamayı hem 3D ödemeyi desteklemesi gerekir. Gönderilmezse bu koşullar varsayılan hesap için denetlenir; ilk ödemenin geçeceği hesap ödeme sırasında ödeme hesabı seçimi ile belirlenir.

subscription.items[]​

AlanTipZorunluAçıklama
channel_referencestringevetAynı kanalda save-product ile kaydedilmiş, type: recurring, is_active: true bir ürün.
quantityintegerhayırEn az 1. Gönderilmezse 1.
unit_amountstringhayırYalnızca ilk dönem için birim fiyat. Sonraki dönemler katalog fiyatıyla hesaplanır.
  • Kalemlerdeki ürünlerin period ve currency değerleri aynı olmalıdır; aboneliğin dönemi ve para birimi bunlardan gelir.
  • Aynı ürün birden fazla kalemde gönderilemez.

customer​

Zorunlu. Alanlar: customer nesnesi.

SDK örnekleri​

use Gurmehub\Odemehub\Request\{SubscriptionItem, SubscriptionPayment};

$subscription = $client->subscriptionPayment(new SubscriptionPayment(
    channelReference: 'UYELIK-4471',
    items: [
        new SubscriptionItem(channelReference: 'PREMIUM-AYLIK'),
        new SubscriptionItem(channelReference: 'EK-KULLANICI', quantity: 3),
    ],
    successUrl: 'https://magazam.com/tesekkurler',
    customer: $customer,
    webhookUrl: 'https://magazam.com/odemehub/abonelik',
));

// $subscription->token değerini saklayın
header('Location: '.$subscription->checkoutUrl);

Yanıt​

PREMIUM-AYLIK 149.90, EK-KULLANICI 30.00 iken:

{
  "result": {
    "successful": true,
    "message": null
  },
  "subscription": {
    "token": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14",
    "channel_reference": "UYELIK-4471",
    "status": "pending",
    "period": "monthly",
    "items": [
      { "channel_reference": "PREMIUM-AYLIK", "name": "Premium üyelik", "quantity": 1, "unit_amount": "149.90", "tax_rate": "20.00" },
      { "channel_reference": "EK-KULLANICI", "name": "Ek kullanıcı", "quantity": 3, "unit_amount": "30.00", "tax_rate": "20.00" }
    ],
    "amount": "239.90",
    "currency": "TRY",
    "is_test": null,
    "starts_at": null,
    "ends_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "checkout_url": "https://odeme.gurmehub.com/checkout/subscription/<dönem token'ı>"
  },
  "customer": {
    "channel_reference": "musteri-88"
  }
}

subscription nesnesinin alanları: retrieve-subscription. Bu yanıtta:

  • status her zaman pending; starts_at, ends_at, paid_at ve is_test null.
  • amount ilk dönemin tutarıdır (unit_amount gönderilen kalemlerde gönderilen fiyatla hesaplanır).
  • items[].unit_amount katalogdaki fiyattır; ilk dönem için gönderilen unit_amount burada görünmez.

HTTP durum kodları​

KodDurum
200Abonelik açıldı.
401API anahtarı ya da imza geçersiz.
403Çalışma alanı işlem yapamıyor ya da planı abonelikleri kapsamıyor.
422Doğrulama hatası.

Hatalar​

AlanMesaj
subscription.items.{i}.channel_referenceBu kanalda böyle bir ürün yok. / Bu ürün abonelik ürünü değil. / Bu ürün satışa kapalı.
subscription.itemsAynı ürün birden fazla kez gönderilemez. / Aboneliğe konan ürünlerin dönemi aynı olmalı. / Aboneliğe konan ürünlerin para birimi aynı olmalı.
subscription.success_urlBaşarı adresi zorunludur; ödeme sonrası müşteri oraya yönlendirilir.
subscription.channel_referenceReferans en az bir rakam içermelidir (ör. SIP1); bankaya giden sipariş numarası bu rakamlarla kurulur.
subscription.payment_provider_tokenÇalışma alanınızın planı kayıtlı kartları kapsamıyor; abonelik açılamaz.
subscription.payment_provider_tokenBu ödeme hesabı kart saklamıyor; abonelik açılamaz. / Çalışma alanınızın varsayılan ödeme hesabı kart saklamıyor; abonelik açılamaz.
subscription.payment_provider_tokenBu ödeme hesabı 3D ödeme almıyor; abonelik açılamaz. / Çalışma alanınızın varsayılan ödeme hesabı 3D ödeme almıyor; abonelik açılamaz.
subscription.payment_provider_tokenÖdeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.