Ödeme Linki Oluştur

POST/partner/1.0/payment/link/create
Gerekli scope: collection:linkIdempotency-Key zorunlu

Alıcıya gönderilebilecek bir tahsilat (ödeme) linki oluşturur. Ödeme sonrası opsiyonel olarak ürün kalemlerinden otomatik sipariş oluşturulabilir.

Yanıttaki paymentUrl müşteriye göndereceğiniz adrestir. Link ödendiğinde transactionRef dolar; o andan sonra işlem uçları ile sorgulanır, gerekirse iade edilir.

Bu uç işletmenizde tahsilat linki (CHECKOUT_LINK) modülünün satın alınmış olmasını gerektirir.

Örnek

curl -X POST https://<host>/partner/1.0/payment/link/create \
  -H "X-Api-Key: ..." \
  -H "X-Timestamp: ..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: create-ORD-1001" \
  -H "Content-Type: application/json" \
  -d '{
  "orderNumber": "ORD-1001",
  "amount": 1229.9,
  "cartAmount": 1279.9,
  "currency": "TRY",
  "description": "Sipariş ORD-1001 (50 TL kupon indirimi)",
  "expiryDate": "2026-12-31T12:00:00Z",
  "enableInstallment": true,
  "availableInstallments": "1,3,6",
  "contactRequired": true,
  "email": "customer@example.com",
  "items": [
    {
      "name": "Deri Ceket",
      "unitPrice": 1000,
      "quantity": 1,
      "vat": 20
    },
    {
      "name": "Kemer",
      "unitPrice": 115,
      "quantity": 2,
      "vat": 20
    },
    {
      "name": "Kargo",
      "unitPrice": 49.9,
      "quantity": 1,
      "vat": 20
    }
  ]
}'

İstek Body

AlanTipAçıklama
amountzorunludecimalTahsil edilecek tutar. 0'dan büyük, en fazla 2 ondalık basamaklı ve en fazla 999999.99 olmalıdır.
cartAmountdecimalSepet tutarı (kalem toplamı). Belirtilmezse amount ile aynı kabul edilir. amount değerinden küçük olamaz; amount ondan küçükse fark ödeme sayfasında indirim olarak görünür.
currencyenumPara birimi.
Varsayılan: TRY
TRYUSDEURGBPJPYCHFRUBAZN
descriptionstringLink açıklaması.
orderNumberstringSizin kendi sipariş numaranız. Link ödendiğinde işlem kaydına yazılır ve transaction/search ile bu numaradan aranabilir. Göndermezseniz sistem üretimli bir referans kullanılır ve ödeme kendi siparişinizle eşleşemez.
expiryDatestringLinkin son geçerlilik tarihi (ISO-8601). Gönderilmezse oluşturma anından 3 gün sonrası kullanılır. Geçmiş bir tarih reddedilir.
enableInstallmentbooleanTaksit imkanını etkinleştirir.
Varsayılan: true
availableInstallmentsstringİzin verilen taksit sayıları, virgülle ayrık (örn. "1,3,6,12"). Verilmezse sınır yok.
contactRequiredbooleanÖdeme sayfasında alıcıdan iletişim bilgisi (ad, soyad, telefon zorunlu; e-posta opsiyonel) istenip istenmeyeceği. ADRES İSTEMEZ.
Varsayılan: false
allowPartialPaymentbooleanKısmi ödemeye izin verir (parçalı/bölünmüş link): link toplam tutara ulaşana dek birden fazla ödemeyle tahsil edilebilir.
Varsayılan: false
itemsarrayOpsiyonel sepet kalemleri. Katalog kalemi için productVariantId + quantity, katalog dışı kalem için name + unitPrice + quantity gönderin. Kalem toplamı cartAmount ile (verilmezse amount ile) birebir eşleşmelidir.
items[].productVariantIdstringKatalog varyant kimliği. Verilirse fiyat otoritesi varyanttır; varyant işletmenize ait olmalıdır.
items[].namestringKalem adı. productVariantId boşsa zorunludur.
items[].unitPricedecimalBirim fiyat. productVariantId boşsa zorunludur ve 0'dan büyük olmalıdır.
items[].quantityintegerAdet. En az 1.
Varsayılan: 1
items[].vatdecimalKDV oranı (%) — tutar DEĞİL (ör. 0, 1, 10, 20). unitPrice KDV dahildir; toplama eklenmez, kalem kırılımına yazılır. 0–100 arası olmalıdır. Katalog kaleminde varyantın oranı kullanılır, bu alan yok sayılır.
Varsayılan: 0
items[].specialNotestringKalem bazlı özel not (opsiyonel).
emailstringAlıcı e-posta adresi. Verilirse geçerli bir adres olmalıdır.
phoneCountryCodestringAlıcı telefon ülke kodu.
phoneNumberstringAlıcı telefon numarası. Verilirse phoneCountryCode ile birlikte geçerli bir cep telefonu olmalıdır.

Yanıt

AlanAnlamı
idLink kimliği. detail / cancel bu değeri alır.
paymentUrlMüşteriye göndereceğiniz ödeme adresi. Adresi kendiniz kurmanız gerekmez.
transactionRefLink ödendiğinde oluşan işlemin referansı; sorgu / iptal / iade zinciri buradan başlar. Ödenmemiş linkte boştur.
referenceNumberSistem üretimli referans numarası.
orderNumberSizin gönderdiğiniz sipariş numaranız.
amountLinkin toplam (tahsil edilecek) tutarı.
cartAmountGönderdiğiniz sepet tutarı (kalem toplamı); amount'tan büyükse fark indirimdir. Gönderilmediyse boştur.
paidAmount / remainingAmountTahsil edilen ve kalan tutar — kısmi ödemeye açık linklerde anlamlıdır.
currencyPara birimi.
statusLink durumu (PENDING, COMPLETED, REJECTED, EXPIRED, UNDER_REVIEW).
descriptionLink açıklaması.
allowPartialPaymentKısmi ödemeye açık mı.
enableInstallment / availableInstallmentsTaksit imkanı ve izin verilen taksit sayıları.
email / phoneCountryCode / phoneNumberAlıcı iletişim bilgileri.
expiryDate / completedDate / createdDateGeçerlilik, tamamlanma ve oluşturma tarihleri.
items[]Sepet kalemleri: productVariantId (katalog kaleminde), name, unitPrice (indirimli birim fiyat, KDV dahil), quantity, vat (KDV oranı %). Ürün gönderilmediyse alan dönmez.
Örnek yanıt (content)
{
  "id": "LINK-55012",
  "referenceNumber": "CLNK-55012",
  "orderNumber": "ORD-1001",
  "paymentUrl": "https://<host>/pay/LINK-55012",
  "transactionRef": null,
  "amount": 1229.9,
  "cartAmount": 1279.9,
  "paidAmount": 0,
  "remainingAmount": 1229.9,
  "currency": "TRY",
  "status": "PENDING",
  "description": "Sipariş ORD-1001 (50 TL kupon indirimi)",
  "allowPartialPayment": false,
  "enableInstallment": true,
  "availableInstallments": "1,3,6",
  "email": "customer@example.com",
  "expiryDate": "2026-12-31T12:00:00Z",
  "completedDate": null,
  "createdDate": "2026-08-17T10:15:30.000Z",
  "items": [
    {
      "productVariantId": null,
      "name": "Deri Ceket",
      "unitPrice": 1000,
      "quantity": 1,
      "vat": 20
    },
    {
      "productVariantId": null,
      "name": "Kemer",
      "unitPrice": 115,
      "quantity": 2,
      "vat": 20
    },
    {
      "productVariantId": null,
      "name": "Kargo",
      "unitPrice": 49.9,
      "quantity": 1,
      "vat": 20
    }
  ]
}

Sepet Kalemleri

items iki tip kalem kabul eder:

  • Katalog kalemi — productVariantId + quantity. Fiyat sunucudaki varyant kaydından okunur; istekte fiyat göndermezsiniz ve varyant işletmenize ait olmalıdır.
  • Katalog dışı kalem — productVariantId boş bırakılır, name + unitPrice + quantity gönderilir. Katalogu olmayan entegratörler (hizmet bedeli, fatura, kurs ücreti) için.

Her iki tipte de kalem toplamı cartAmount ile (gönderilmezse amount ile) birebir eşleşmelidir; eşleşmezse items.total.mismatch ile 406 döner (beklenen ve gönderilen tutar mesajda). Katalog kaleminde varyantın para birimi istekteki currency ile aynı olmalıdır (items.must.same.currency).

İndirim: cartAmount kalem toplamı, amount tahsil edilecek tutardır. amount daha küçük olabilir; fark ödeme sayfasında "İndirim" satırı olarak görünür. cartAmount, amount değerinden küçük olamaz (checkout.link.cart.amount.invalid). Fark yoksa cartAmount göndermeyin.

Kargo / ek bedel: ayrı bir katalog dışı kalem olarak gönderin, ör. {"name": "Kargo", "unitPrice": 49.90, "quantity": 1}.

KDV: katalog dışı kalemde vat KDV oranıdır (%), tutar değil; unitPrice KDV dahildir ve toplama ayrıca eklenmez. Katalog kaleminde oran ürün varyantından alınır.

Katalog ürününüzde fiyat gönderilmez, yalnız varyant ve adet: {"productVariantId": "<variantId>", "quantity": 2}. Aynı sepette katalog ve katalog dışı kalemler birlikte kullanılabilir.

Anahtar başına kalem tavanı tanımlıysa (link.max_items) aşılması partner.api.item.limit.exceeded üretir.

Hatalar

Mesaj anahtarıHTTPNeden
items.total.mismatch406Kalem toplamı cartAmount (verilmezse amount) ile eşleşmiyor.
items.must.same.currency406Katalog varyantının para birimi istekteki currency ile aynı değil.
items.invalid400Katalog dışı kalemde name boş, unitPrice eksik / 0 veya negatif ya da vat 0–100 dışında.
checkout.link.cart.amount.invalid400cartAmount 0'dan büyük değil ya da amount değerinden küçük.
amount.invalid400amount eksik, 0'dan büyük değil ya da 2'den fazla ondalık basamak içeriyor.
email.not.valid406email geçerli bir adres değil.
phone.number.not.valid406phoneNumber geçerli bir cep telefonu değil.
partner.api.amount.limit.exceeded406Tutar, API anahtarınızın üst sınırını aşıyor.
partner.api.item.limit.exceeded406Kalem sayısı, API anahtarınızın üst sınırını aşıyor.
gecerlilik.tarihi.guncel.degil400expiryDate geçmiş bir tarih.

İsteği Dene

İsteği Dene
Önizleme modu — değerler kod örneklerini günceller, gerçek istek atılmaz.
Mock