Ö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.

Ö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 '{
  "amount": 100,
  "currency": "TRY",
  "description": "Sipariş ORD-1001",
  "expiryDate": "2026-09-20T12:00:00Z",
  "enableInstallment": true,
  "availableInstallments": "1,3,6",
  "contactRequired": false,
  "email": "customer@example.com"
}'

İstek Body

Alan	Tip	Açıklama
`amount`zorunlu	decimal	Tahsil edilecek tutar. Varsayılan: `0`
`cartAmount`	decimal	Sepet tutarı. Belirtilmezse amount ile aynı kabul edilir.
`currency`	enum	Para birimi. Varsayılan: `TRY` `TRYUSDEURGBPJPYCHFRUBAZN`
`description`	string	Link açıklaması.
`orderNumber`	string	Sizin 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.
`expiryDate`	string	Linkin son geçerlilik tarihi (ISO-8601). Geçmiş bir tarih reddedilir.
`enableInstallment`	boolean	Taksit imkanını etkinleştirir. Varsayılan: `true`
`availableInstallments`	string	İzin verilen taksit sayıları, virgülle ayrık (örn. "1,3,6,12"). Verilmezse sınır yok.
`contactRequired`	boolean	Ödeme sayfasında alıcıdan iletişim bilgisi (ad, soyad, telefon zorunlu; e-posta opsiyonel) istenip istenmeyeceği. ADRES İSTEMEZ. Varsayılan: `false`
`allowPartialPayment`	boolean	Kısmi ödemeye izin verir (parçalı/bölünmüş link): link toplam tutara ulaşana dek birden fazla ödemeyle tahsil edilebilir. Varsayılan: `false`
`items`	array	Opsiyonel sepet kalemleri. Katalog kalemi için productVariantId + quantity, katalog dışı kalem için name + unitPrice + quantity gönderin. Kalem toplamı amount ile birebir eşleşmelidir.
`items[].productVariantId`	string	Katalog varyant kimliği. Verilirse fiyat otoritesi varyanttır; varyant işletmenize ait olmalıdır.
`items[].name`	string	Kalem adı. productVariantId boşsa zorunludur.
`items[].unitPrice`	decimal	Birim fiyat. productVariantId boşsa zorunludur ve 0'dan büyük olmalıdır.
`items[].quantity`	integer	Adet. En az 1. Varsayılan: `1`
`items[].specialNote`	string	Kalem bazlı özel not (opsiyonel).
`email`	string	Alıcı e-posta adresi.
`phoneCountryCode`	string	Alıcı telefon ülke kodu.
`phoneNumber`	string	Alıcı telefon numarası.

Yanıt

Alan	Anlamı
`id`	Link kimliği. detail / cancel bu değeri alır.
`paymentUrl`	Müşteriye göndereceğiniz ödeme adresi. Adresi kendiniz kurmanız gerekmez.
`transactionRef`	Link ödendiğinde oluşan işlemin referansı; sorgu / iptal / iade zinciri buradan başlar. Ödenmemiş linkte boştur.
`referenceNumber`	Sistem üretimli referans numarası.
`orderNumber`	Sizin gönderdiğiniz sipariş numaranız.
`amount`	Linkin toplam tutarı.
`paidAmount` / `remainingAmount`	Tahsil edilen ve kalan tutar — kısmi ödemeye açık linklerde anlamlıdır.
`currency`	Para birimi.
`status`	Link durumu (`PENDING`, `COMPLETED`, `REJECTED`, `EXPIRED`, `UNDER_REVIEW`).
`description`	Link açıklaması.
`allowPartialPayment`	Kısmi ödemeye açık mı.
`enableInstallment` / `availableInstallments`	Taksit imkanı ve izin verilen taksit sayıları.
`email` / `phoneCountryCode` / `phoneNumber`	Alıcı iletişim bilgileri.
`expiryDate` / `completedDate` / `createdDate`	Geçerlilik, tamamlanma ve oluşturma tarihleri.

Örnek yanıt (content)

{
  "id": "LINK-55012",
  "referenceNumber": "CLNK-55012",
  "orderNumber": "ORD-1001",
  "paymentUrl": "https://<host>/pay/LINK-55012",
  "transactionRef": null,
  "amount": 100,
  "paidAmount": 0,
  "remainingAmount": 100,
  "currency": "TRY",
  "status": "PENDING",
  "allowPartialPayment": false,
  "enableInstallment": true,
  "availableInstallments": "1,3,6",
  "expiryDate": "2026-09-20T12:00:00Z",
  "completedDate": null,
  "createdDate": "2026-08-17T10:15:30.000Z"
}

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ı amount ile birebir eşleşmelidir; eşleşmezse items.total.mismatch ile 406 döner (beklenen tutar mesajda). Kalemlerin para birimi istekteki currency ile aynı olmalıdır.

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

Hatalar

Mesaj anahtarı	HTTP	Neden
`items.total.mismatch`	406	Kalem toplamı gönderilen amount ile eşleşmiyor.
`items.invalid`	400	Katalog dışı kalemde name veya pozitif unitPrice eksik.
`partner.api.amount.limit.exceeded`	406	Tutar, API anahtarınızın üst sınırını aşıyor.
`partner.api.item.limit.exceeded`	406	Kalem sayısı, API anahtarınızın üst sınırını aşıyor.
`gecerlilik.tarihi.guncel.degil`	400	expiryDate geçmiş bir tarih.

İsteği Dene

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

Mock

amount*cartAmountcurrencydescriptionorderNumberexpiryDateenableInstallmentavailableInstallmentscontactRequiredallowPartialPaymentemailphoneCountryCodephoneNumberitems (JSON)