Ö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.
Link oluşturma
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.
| Alan | Anlamı |
|---|---|
id | Linkin id değeri; GET ve DELETE /payment-links/{id} endpoint'lerinde kullanılır. |
url | Alıcıya göndereceğiniz adres. |
productId | Linkin sattığı dijital ürün. |
maxUses | Linkin 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. |
isMaxUsesApplied | useCount, maxUses değerine ulaşınca true olur. Bu durumdaki link artık açılmaz. maxUses yoksa her zaman false. |
status | expiresAt gelene kadar active, sonra expired. maxUses değerine bakmaz: isMaxUsesApplied değerini de kontrol edin. |
createdAt, expiresAt | ISO 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:
| Alan | Değer | Ne 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:
| Alan | Anlamı |
|---|---|
isLink | Sipariş bir link üzerinden geldiyse true. |
linkId | Siparişin geldiği linkin id değeri. |
merchantOrderId | Eklediyseniz kendi sipariş numaranız; eklemediyseniz null. |
orderId | hikie 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-9876543210URL'de zaten parametre varsa ? yerine & kullanın. Ardından her order.paid
olayında:
- Webhook imzasını doğrulayın.
- Bu
orderIddaha önce işlendiyse tekrar teslim etmeden200dönün. merchantOrderIdile taslak siparişinizi bulun ve ödenmiş yapın.- Ürünü teslim edin ya da erişimi açın.
Geçerlilik
expiresAtvermezseniz link 30 gün geçerlidir. Seçtiğiniz tarih gelecekte ve en çok 365 gün ileride olmalıdır, aksi halde400 EXPIRES_AT_INVALIDdöner. Bu tarihten sonra link açılmaz.maxUsesyoksa 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
useCountbir artar.maxUsesdeğerine ulaşınca link artık açılmaz veisMaxUsesAppliedtrueolur. - Açılışlar sayıldığı için linki birden fazla açan bir alıcı birden fazla hak
harcar.
maxUsesbelirlerken pay bırakın ve onu satış saymak için kullanmayın: satışları siparişlerinizden ya daorder.paidwebhook'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.
Link oluştururken kurallar
- 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ün409 PRODUCT_TYPE_NOT_SUPPORTEDdö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_FOUNDdö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.
| Sorgu | Açıklama |
|---|---|
page | 1'den başlar. Varsayılan 1. |
limit | 1 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,
GETisteği404dö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_FOUNDdöner.
DELETE isteğinde Idempotency-Key isteğe bağlıdır.
Hatalar
| Durum | errorCode | Ne zaman |
|---|---|---|
400 | EXPIRES_AT_INVALID | expiresAt gerçek bir tarih değil, geçmişte ya da 365 günden daha ileride |
403 | STORE_NOT_VERIFIED | Mağaza doğrulanmamış |
404 | PRODUCT_NOT_FOUND | Mağazanızda böyle bir ürün yok |
404 | PAYMENT_LINK_NOT_FOUND | Mağazanızda böyle bir link yok ya da silinmiş |
409 | PRODUCT_TYPE_NOT_SUPPORTED | Ürün fiziksel ürün ya da eski tip dijital ürün |
409 | PRODUCT_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.