Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Pay-by-Link, müşteriye gönderebileceğiniz tek kullanımlık ödeme linki üretir. Müşteri linke tıklayıp banka/hosted checkout sayfasında ödemeyi yapar. Çağrı merkezi, abonelik yenileme, ofis dışı satış senaryoları için idealdir.

​
Akış

​
Endpoint

POST /api/v1/payments/order-link

​
İstek

curl -X POST https://vpos.payven.com.tr/api/v1/payments/order-link \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT" \
  -H "Idempotency-Key: order-1001-link" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ORDER-1001",
    "amount": 15000,
    "currency": "TRY",
    "installment": 1,
    "description": "Sipariş #1001 ödemesi",
    "customerEmail": "musteri@example.com",
    "customerPhone": "+905551234567",
    "expiresAt": "2026-05-04T12:00:00Z",
    "returnUrl": "https://example.com/odeme/sonuc",
    "callbackUrl": "https://api.example.com/webhooks/payven"
  }'
AlanTipZorunluAçıklama
externalIdstring✅Sipariş kimliğiniz
amountint✅Tutar (kuruş)
currencyenum✅TRY, USD, EUR, GBP
installmentint❌Sabit taksit. Boş bırakılırsa müşteri seçer.
descriptionstring⚠️Ödeme sayfasında müşteriye gösterilecek açıklama
customerEmailstring⚠️Otomatik e-posta gönderimi için (opsiyonel)
customerPhonestring⚠️Otomatik SMS için (opsiyonel)
expiresAtstring❌Linkin geçerlilik süresi (varsayılan 24 saat)
returnUrlstring✅Müşterinin son yönlendirileceği URL
callbackUrlstring❌Sunucu-sunucu callback

​
Yanıt

{
  "isSuccess": true,
  "code": "201",
  "data": {
    "id": "8e3f5c12-...",
    "externalId": "ORDER-1001",
    "status": "AwaitingPayment",
    "paymentLink": "https://link.payven.com.tr/pay/abc123def456",
    "shortLink": "https://pyv.tr/abc123",
    "qrCodeUrl": "https://link.payven.com.tr/pay/abc123def456/qr",
    "expiresAt": "2026-05-04T12:00:00Z"
  }
}
AlanAçıklama
paymentLinkTam URL — kendi mesajınızda paylaşabilirsiniz
shortLinkKarakter sınırı düşük olan SMS için kısa versiyon
qrCodeUrlQR kod görseli — fiziksel ortamda kullanım için

​
Müşteriye iletme

Linki kendi tercih ettiğiniz kanaldan iletebilirsiniz:
KanalÖnerilen alan
SMSshortLink (160 karakter sınırı)
E-postapaymentLink
WhatsApp / TelegrampaymentLink
QR kod (mağaza, fiş)qrCodeUrl
customerEmail veya customerPhone doldurursanız Payven otomatik gönderim yapar (panelde aktivasyon gerektirir). Aksi durumda gönderim sizdedir.

​
Tek tek tıklama vs çoklu deneme

Bir link birden fazla deneme için kullanılabilir:
SenaryoDavranış
Müşteri ilk denemede başarılıLink kapanır (status: Completed)
Müşteri kart reddedildi, başka kart denemek istiyorLink aktif kalır, müşteri tekrar deneyebilir
Süre dolduLink Expired durumuna geçer
Manuel iptalDELETE /payments/order-link/{id} ile kapatılabilir

​
Linki iptal etme

DELETE /api/v1/payments/order-link/{id}

curl -X DELETE https://vpos.payven.com.tr/api/v1/payments/order-link/8e3f5c12-... \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT"
İptal edilen linke tıklayan müşteri “ödeme süresi dolmuş” mesajı görür.

​
Webhook olayları

OlayAçıklama
payment.link.createdLink oluşturuldu
payment.link.viewedMüşteri linke tıkladı
payment.succeededÖdeme başarılı
payment.failedMüşteri ödeme yapmaya çalıştı, başarısız
payment.link.expiredSüre doldu

​
Tipik kullanım kalıpları

Operatör müşteriyle telefonda görüşür, sipariş alır. Sonra:
  1. CRM’den POST /payments/order-link çağrısı.
  2. Müşteriye SMS gönderilir.
  3. Operatör müşteriden sonucu beklemeden çağrıyı kapatır.
  4. Webhook ile ödeme bildirildiğinde sipariş onaylanır.
Otomatik yenileme yerine:
  1. Vadeden 3 gün önce customerEmail doldurularak link üretilir.
  2. Payven otomatik mail gönderir.
  3. Müşteri ödemeyi yaptığında abonelik uzatılır.
  1. Kasa ekranında qrCodeUrl gösterilir.
  2. Müşteri telefonuyla okutur.
  3. Hosted checkout sayfasında ödemeyi yapar.
  4. Kasiyer webhook bildirimini bekler.