create-subscription

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

Bir abonelik açar; çekim yapılmaz. İlk dönem yanıttaki subscription.checkout_url adresindeki ödeme sayfasında 3D Secure ile ödenir ve kart bu ödemede saklanır; sonraki dönemler o karttan çekilir. Tutar gönderilmez; kalemlerden ve ödeyenin seçtiği gönderim yönteminden hesaplanır. Akış: Abonelik rehberi.

Aynı referansla tekrar çağırmak

Her create-subscription çağrısı yeni bir abonelik ve yeni bir subscription.token açar; aynı reference daha önce gönderilmiş olsa da. Aynı referanslı önceki abonelikler değiştirilmez; önceki abonelik ödenmiş, sona ermiş ya da üzerinde bekleyen bir ödeme bulunsa da istek 422 dönmez. İlk dönem ödenmediyse aynı referansla yeni abonelik açıp ödeyeni yeni checkout_url adresine yönlendirebilirsiniz; var olan aboneliği değiştirmek için update-subscription kullanılır. Yanıttaki subscription.token değerini saklayın: webhook'lar aboneliği yalnızca token'la anar. Ayrıntılar: Aynı referansla tekrarlanan create-* istekleri.

Ön koşullar

Çalışma alanının planı abonelikleri ve kayıtlı kartları kapsamalıdır. Abonelikler modülü kapalıysa 403, Kayıtlı Kartlar modülü kapalıysa 422 döner.
Aboneliğin ödeneceği hesap (gönderilen payment_provider_token ya da varsayılan hesap) kart saklamalı ve 3D ödeme almalıdır; değilse 422.

Kimlik doğrulama

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

İstek

{
  "subscription": {
    "reference": "ABO-4471",
    "period": "monthly",
    "renewal_limit": 12,
    "success_url": "https://magazam.com/abonelik/donus",
    "items": [
      { "reference": "PREMIUM-AYLIK", "name": "Premium üyelik", "quantity": 1, "unit_amount": "149.90", "tax_rate": "20" }
    ]
  },
  "customer": {
    "reference": "musteri-88",
    "billing_address": {
      "firstname": "Ahmet",
      "lastname": "Yılmaz",
      "email": "[email protected]"
    }
  }
}

`subscription`

create-order isteğindeki order alanlarının tamamı (reference, success_url, cancel_url, description, currency, payment_provider_token, requires_shipping, locks_customer, emails_customer, items) aynı kurallarla subscription altında gönderilir. reference tekil değildir; aynı referansla her çağrı yeni abonelik açar (ayrıntı). Abonelikte emails_customer açıksa müşteriye her durum değişiminde e-posta gider (E-postalar). Ek alanlar:

Alan	Tip	Zorunlu	Açıklama
`period`	string	evet	Dönem: `daily`, `weekly`, `monthly`, `annually`.
`renewal_limit`	integer	hayır	Alınacak toplam dönem ödemesi sayısı, 1–1000. Gönderilmezse abonelik iptal edilene kadar sürer.

Aboneliğin olayları, panelde Ödeme Ayarları → Webhook sayfasında olaylara tanımladığınız webhook adreslerine bildirilir.

`customer`

Zorunlu. customer.reference zorunludur: ilk dönem ödendiğinde ödeyen bu referansla müşteri olarak kaydedilir, kart bu müşterinin altında saklanır ve sonraki dönemler müşterinin varsayılan kartından çekilir. billing_address ve shipping_address isteğe bağlıdır; gönderilmeyenler ödeme sayfasında alınır. Alanlar: customer nesnesi.

SDK örnekleri

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Enum\Period;
use Gurmehub\Odemehub\Request\{Address, CreateSubscription, Customer, Item};

$created = $client->createSubscription(new CreateSubscription(
    reference: 'ABO-4471',
    period: Period::Monthly,
    successUrl: 'https://magazam.com/abonelik/donus',
    items: [new Item(name: 'Premium üyelik', unitAmount: '149.90', quantity: 1, taxRate: '20', reference: 'PREMIUM-AYLIK')],
    customer: new Customer(
        reference: 'musteri-88',
        billingAddress: new Address(firstname: 'Ahmet', lastname: 'Yılmaz', email: '[email protected]'),
    ),
    renewalLimit: 12,
));

header('Location: '.$created->subscription->checkoutUrl);

const created = await client.createSubscription({
    reference: 'ABO-4471',
    period: 'monthly',
    successUrl: 'https://magazam.com/abonelik/donus',
    items: [{ name: 'Premium üyelik', unitAmount: '149.90', quantity: 1, taxRate: '20', reference: 'PREMIUM-AYLIK' }],
    customer: {
        reference: 'musteri-88',
        billingAddress: { firstname: 'Ahmet', lastname: 'Yılmaz', email: '[email protected]' },
    },
    renewalLimit: 12,
});

res.redirect(created.subscription.checkoutUrl!);

from odemehub.enums import Period
from odemehub.request import Address, CreateSubscription, Customer, Item

created = client.create_subscription(CreateSubscription(
    reference="ABO-4471",
    period=Period.MONTHLY,
    success_url="https://magazam.com/abonelik/donus",
    items=[Item(name="Premium üyelik", unit_amount="149.90", quantity=1, tax_rate="20", reference="PREMIUM-AYLIK")],
    customer=Customer(
        reference="musteri-88",
        billing_address=Address(firstname="Ahmet", lastname="Yılmaz", email="[email protected]"),
    ),
    renewal_limit=12,
))

return redirect(created.subscription.checkout_url)

import com.odemehub.enums.Period;
import com.odemehub.request.Address;
import com.odemehub.request.CreateSubscription;
import com.odemehub.request.Customer;
import com.odemehub.request.Item;
import java.util.List;

var created = client.createSubscription(CreateSubscription.builder()
    .reference("ABO-4471")
    .period(Period.MONTHLY)
    .successUrl("https://magazam.com/abonelik/donus")
    .items(List.of(Item.builder().name("Premium üyelik").unitAmount("149.90").quantity(1).taxRate("20").reference("PREMIUM-AYLIK").build()))
    .customer(Customer.builder()
        .reference("musteri-88")
        .billingAddress(Address.builder().firstname("Ahmet").lastname("Yılmaz").email("[email protected]").build())
        .build())
    .renewalLimit(12)
    .build());

return "redirect:" + created.getSubscription().getCheckoutUrl();

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/create-subscription"
BODY='{"subscription":{"reference":"ABO-4471","period":"monthly","renewal_limit":12,"success_url":"https://magazam.com/abonelik/donus","items":[{"reference":"PREMIUM-AYLIK","name":"Premium üyelik","quantity":1,"unit_amount":"149.90","tax_rate":"20"}]},"customer":{"reference":"musteri-88","billing_address":{"firstname":"Ahmet","lastname":"Yılmaz","email":"[email protected]"}}}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

{
  "result": { "successful": true, "message": null },
  "subscription": {
    "token": "9a2c4e6f-1b3d-4f5a-8c7e-2d4f6a8b0c1e",
    "reference": "ABO-4471",
    "description": null,
    "payment_provider_token": null,
    "status": "pending",
    "period": "monthly",
    "renewal_limit": 12,
    "renewals_paid": 0,
    "items": [
      { "reference": "PREMIUM-AYLIK", "name": "Premium üyelik", "image": null, "quantity": 1, "unit_amount": "149.90", "tax_rate": "20.00" }
    ],
    "shipping_method": null,
    "discount": null,
    "subtotal": "124.92",
    "shipping_amount": "0.00",
    "tax_amount": "24.98",
    "amount": "149.90",
    "currency": "TRY",
    "is_test": null,
    "renewal": {
      "token": "5e7a9c1b-3d5f-4a2c-9e4b-6f8a0c2e4d13",
      "amount": "149.90",
      "currency": "TRY",
      "starts_at": null,
      "ends_at": null,
      "paid_at": null
    },
    "next_payment_at": null,
    "cancelled_at": null,
    "created_at": "2026-10-02T09:30:00.000000Z",
    "checkout_url": "https://sandbox.odemehub.com/checkout/subscription/5e7a9c1b-3d5f-4a2c-9e4b-6f8a0c2e4d13"
  },
  "customer": {
    "reference": "musteri-88",
    "billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" },
    "shipping_address": null
  }
}

Alanlar: Abonelik nesnesi ve yanıttaki customer.

discount yeni açılan abonelikte null'dır. Ödeyen ilk dönemin ödemesinde ödeme sayfasında kupon uygularsa discount bu kuponu gösterir; aboneliğin subtotal, tax_amount ve amount alanları indirimsiz kalır, ilk dönem için çekilen indirimli tutar renewal.amount alanındadır. Bkz. Kupon ve discount.

HTTP durum kodları

Kod	Durum
`200`	Abonelik açıldı.
`401`	API anahtarı ya da imza geçersiz.
`403`	Çalışma alanı işlem yapamıyor, planı abonelikleri kapsamıyor ya da Abonelikler modülü kapalı.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.

Hatalar

create-order ile aynı alan mesajları (order.* yerine subscription.*), ayrıca:

Alan	Mesaj
`subscription.payment_provider_token`	`Bu ö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_token`	`Bu ö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`	`Çalışma alanınızın planı kayıtlı kartları kapsamıyor; abonelik açılamaz.` / `Çalışma alanınızda Kayıtlı Kartlar modülü kapalı; abonelik açılamaz.`
`customer.reference`	`Müşteri referansı (customer.reference) zorunludur.`

Aynı referansla tekrar çağırmak​

Ön koşullar​

Kimlik doğrulama​

İstek​

subscription​

customer​

SDK örnekleri​

Yanıt​

HTTP durum kodları​

Hatalar​