Ödeme Linki Oluştur
/partner/1.0/payment/link/createcollection:linkIdempotency-Key zorunluAlı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
| Alan | Tip | Açıklama |
|---|---|---|
amountzorunlu | decimal | Tahsil edilecek tutar. 0'dan büyük, en fazla 2 ondalık basamaklı ve en fazla 999999.99 olmalıdır. |
cartAmount | decimal | Sepet 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. |
currency | enum | Para birimi. Varsayılan: TRYTRYUSDEURGBPJPYCHFRUBAZN |
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). Gönderilmezse oluşturma anından 3 gün sonrası kullanılır. 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ı cartAmount ile (verilmezse 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[].vat | decimal | KDV 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[].specialNote | string | Kalem bazlı özel not (opsiyonel). |
email | string | Alıcı e-posta adresi. Verilirse geçerli bir adres olmalıdır. |
phoneCountryCode | string | Alıcı telefon ülke kodu. |
phoneNumber | string | Alıcı telefon numarası. Verilirse phoneCountryCode ile birlikte geçerli bir cep telefonu olmalıdır. |
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 (tahsil edilecek) tutarı. |
cartAmount | Gönderdiğiniz sepet tutarı (kalem toplamı); amount'tan büyükse fark indirimdir. Gönderilmediyse boştur. |
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. |
items[] | Sepet kalemleri: productVariantId (katalog kaleminde), name, unitPrice (indirimli birim fiyat, KDV dahil), quantity, vat (KDV oranı %). Ürün gönderilmediyse alan dönmez. |
{
"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 —
productVariantIdboş bırakılır,name+unitPrice+quantitygö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ı | HTTP | Neden |
|---|---|---|
items.total.mismatch | 406 | Kalem toplamı cartAmount (verilmezse amount) ile eşleşmiyor. |
items.must.same.currency | 406 | Katalog varyantının para birimi istekteki currency ile aynı değil. |
items.invalid | 400 | Katalog dışı kalemde name boş, unitPrice eksik / 0 veya negatif ya da vat 0–100 dışında. |
checkout.link.cart.amount.invalid | 400 | cartAmount 0'dan büyük değil ya da amount değerinden küçük. |
amount.invalid | 400 | amount eksik, 0'dan büyük değil ya da 2'den fazla ondalık basamak içeriyor. |
email.not.valid | 406 | email geçerli bir adres değil. |
phone.number.not.valid | 406 | phoneNumber geçerli bir cep telefonu değil. |
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. |