hikiehikieDeveloper Documentation
Endpoint'ler

Ödeme alma linkleri

Yayındaki bir dijital ürünü, alıcıya gönderebileceğiniz bir ödeme alma linkine çevirin.

Ödeme alma linki, mağazanızdaki bir dijital ürünün ödeme sayfasını açar. Linki e-postaya, mesaja ya da QR koda koyabilirsiniz.

Bunlar panelinizde yönettiğiniz ödeme alma linkleriyle aynı kayıtlardır: panelde oluşturduğunuz linkler burada da listelenir, burada oluşturduğunuz linkler de panelde görünür.

Ödemeden sonra alıcı kendi sayfalarınıza dönebilir; siparişi webhook ile işlersiniz.

POST /payment-links için payment_links izni ve bir Idempotency-Key gerekir. Aynı izinle linkleri listeleyebilir, tek tek okuyabilir ve silebilirsiniz.

POST /payment-links

Alan

Tip

curl -X POST https://api.hikie.space/v1/payment-links \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: link-pro-plan-2026-11-02-a" \
  -H "Content-Type: application/json" \
  -d '{"productId":"66b1efd21c9a4e0021f3ab77","maxUses":50}'

Yanıt 201 döner:

{
  "id": "6730a1f2c3d4e5f607182930",
  "url": "https://www.hikie.space/link/checkout/Fq3n8…",
  "productId": "66b1efd21c9a4e0021f3ab77",
  "maxUses": 50,
  "useCount": 0,
  "isMaxUsesApplied": false,
  "status": "active",
  "createdAt": "2026-11-02T09:15:00.000Z",
  "expiresAt": "2026-12-02T09:15:00.000Z"
}

id değerini saklayın: linki daha sonra okumak ya da silmek için bunu kullanırsınız.

AlanAnlamı
idLinkin id değeri; GET ve DELETE /payment-links/{id} endpoint'lerinde kullanılır.
urlAlıcıya göndereceğiniz adres.
productIdLinkin sattığı dijital ürün.
maxUsesLinkin kaç kez açılabileceği; sınır yoksa null.
useCountÖdeme sayfasının link üzerinden kaç kez açıldığı. Satış sayısı değildir.
isMaxUsesApplieduseCount, maxUses değerine ulaşınca true olur. Bu durumdaki link artık açılmaz. maxUses yoksa her zaman false.
statusexpiresAt gelene kadar active, sonra expired. maxUses değerine bakmaz: isMaxUsesApplied değerini de kontrol edin.
createdAt, expiresAtISO 8601 zaman damgaları.

Alıcı ne görür

Link, alıcıyı ürünün ödeme sayfasına götürür; alıcı diğer ödemelerde olduğu gibi öder.

Link fiyatı değil ürünü saklar. Alıcı, ödeme anındaki ürün fiyatını öder; yani linki oluşturduktan sonra yaptığınız fiyat değişikliği geçerli olur.

Sonuç sayfaları

Panelde (Ödeme Alma Linkleri) oluşturulan linkler, ödemeden sonra alıcının tarayıcısını kendi sayfalarınıza gönderebilir:

AlanDeğerNe zaman
Başarılı Ödeme Redirect URL'i (redirectUrl)Başarılı sonuç sayfanızın tam URL'i, örneğin https://magazam.example/odeme/tamamlandiÖdeme başarılı olduğunda
Başarısız Ödeme Redirect URL'i (failRedirectUrl)Başarısızlık ya da tekrar deneme sayfanızın tam URL'i, örneğin https://magazam.example/odeme/tekrar-deneÖdeme başarısız olduğunda

İkisi de isteğe bağlıdır ve tam URL olmalıdır; eklediğiniz sorgu parametreleri korunur. API ile oluşturulan linklerde ve bu adresleri boş bırakılan linklerde hikie'nin varsayılan sonuç ekranları gösterilir.

hikie bu adreslere status gibi parametreler ekleyebilir. Bunlar imzalı değildir ve ödeme sağlayıcısının dönüş akışına göre değişebilir; yalnızca sayfada göstermek için kullanın. Erişimi sonuç sayfası açıldı diye vermeyin: alıcı tarayıcıyı daha önce kapatabilir.

Ödemeyi webhook ile işleme

Siparişleri order.paid webhook'u ile işleyin. Link üzerinden ödenen bir sipariş şu alanlarla gelir:

AlanAnlamı
isLinkSipariş bir link üzerinden geldiyse true.
linkIdSiparişin geldiği linkin id değeri.
merchantOrderIdEklediyseniz kendi sipariş numaranız; eklemediyseniz null.
orderIdhikie sipariş numarası. Tekil ödeme kimliği olarak saklayın.

Ödemeyi kendi sisteminizdeki bir siparişle eşleştirmek için önce taslak sipariş açın ve tekil kimliğini linke ekleyin:

https://www.hikie.space/link/checkout/Fq3n8…?merchantOrderId=MO-9876543210

URL'de zaten parametre varsa ? yerine & kullanın. Ardından her order.paid olayında:

  1. Webhook imzasını doğrulayın.
  2. Bu orderId daha önce işlendiyse tekrar teslim etmeden 200 dönün.
  3. merchantOrderId ile taslak siparişinizi bulun ve ödenmiş yapın.
  4. Ürünü teslim edin ya da erişimi açın.

Geçerlilik

  • expiresAt vermezseniz link 30 gün geçerlidir. Seçtiğiniz tarih gelecekte ve en çok 365 gün ileride olmalıdır, aksi halde 400 EXPIRES_AT_INVALID döner. Bu tarihten sonra link açılmaz.
  • maxUses yoksa linkin kullanım sınırı yoktur: linke sahip herkes açıp satın alabilir, aynı linki birçok alıcı kullanabilir.
  • Bir kullanım, satış değil ödeme sayfasının bir açılışıdır. Sayfa link üzerinden her açıldığında, alıcı ödese de ödemese de useCount bir artar. maxUses değerine ulaşınca link artık açılmaz ve isMaxUsesApplied true olur.
  • Açılışlar sayıldığı için linki birden fazla açan bir alıcı birden fazla hak harcar. maxUses belirlerken pay bırakın ve onu satış saymak için kullanmayın: satışları siparişlerinizden ya da order.paid webhook'undan okuyun.
  • Ürün yayından kaldırılır ya da gizlenirse, veya mağaza askıya alınır ya da satışa kapanırsa link de açılmaz.
  • Linki süresi dolmadan durdurmak için silin.
  • Mağazanız doğrulanmış olmalıdır: 403 STORE_NOT_VERIFIED.
  • Ürün bir dijital ürün (type: "membership") olmalıdır. Fiziksel ürün ya da eski tip dijital ürün 409 PRODUCT_TYPE_NOT_SUPPORTED döner.
  • Ürün yayında ve görünür olmalıdır: 409 PRODUCT_NOT_PUBLISHED.
  • Mağazanızda olmayan bir id 404 PRODUCT_NOT_FOUND döner.

Linkleri listeleme

GET /payment-links, panelde oluşturulanlar dahil mağazanızın linklerini yeniden eskiye döner. Sildiğiniz linkler listelenmez; süresi dolmuş linkler status: "expired" ile listelenir.

SorguAçıklama
page1'den başlar. Varsayılan 1.
limit1 ile 100 arası. Varsayılan 20.
statusİsteğe bağlı. Süresi dolmamış linkler için active, diğerleri için expired.
curl "https://api.hikie.space/v1/payment-links?status=active&limit=20" \
  -H "Authorization: Bearer hks_..."
{
  "items": [
    {
      "id": "6730a1f2c3d4e5f607182930",
      "url": "https://www.hikie.space/link/checkout/Fq3n8…",
      "productId": "66b1efd21c9a4e0021f3ab77",
      "maxUses": 50,
      "useCount": 12,
      "isMaxUsesApplied": false,
      "status": "active",
      "createdAt": "2026-11-02T09:15:00.000Z",
      "expiresAt": "2026-12-02T09:15:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

status yalnızca bitiş tarihini yansıtır. maxUses değerine ulaşmış ya da ürünü yayından kaldırılmış bir link yine active görünür.

Tek bir linki okuma

GET /payment-links/{id}, tek bir linki yukarıdaki biçimde döner.

curl https://api.hikie.space/v1/payment-links/6730a1f2c3d4e5f607182930 \
  -H "Authorization: Bearer hks_..."

Olmayan, başka bir mağazaya ait ya da silinmiş bir id 404 PAYMENT_LINK_NOT_FOUND döner.

Linki silme

DELETE /payment-links/{id} linki hemen durdurur ve gövdesiz 204 döner.

curl -X DELETE https://api.hikie.space/v1/payment-links/6730a1f2c3d4e5f607182930 \
  -H "Authorization: Bearer hks_..."
  • Link ve varsa kısa linki artık açılmaz.
  • Link listeden kalkar, GET isteği 404 döner.
  • Link silinmez, devre dışı bırakılır: panelden yeniden açılabilir.
  • Link üzerinden daha önce ödenmiş siparişler etkilenmez.
  • Zaten silinmiş ya da hiç olmayan bir linki silmek 404 PAYMENT_LINK_NOT_FOUND döner.

DELETE isteğinde Idempotency-Key isteğe bağlıdır.

Hatalar

DurumerrorCodeNe zaman
400EXPIRES_AT_INVALIDexpiresAt gerçek bir tarih değil, geçmişte ya da 365 günden daha ileride
403STORE_NOT_VERIFIEDMağaza doğrulanmamış
404PRODUCT_NOT_FOUNDMağazanızda böyle bir ürün yok
404PAYMENT_LINK_NOT_FOUNDMağazanızda böyle bir link yok ya da silinmiş
409PRODUCT_TYPE_NOT_SUPPORTEDÜrün fiziksel ürün ya da eski tip dijital ürün
409PRODUCT_NOT_PUBLISHEDÜrün taslak, yayından kaldırılmış ya da gizli

Yukarıdaki tabloda olmayan bir alan, örneğin quantity ya da discountCode göndermek 400 döner.

Bu sayfada