Skip to main content
Pay-by-Link, müşteriye gönderebileceğiniz banka barındırmalı ödeme linki üretir. Müşteri linke tıklayıp bankanın güvenli sayfasında ödemeyi yapar. Çağrı merkezi, abonelik yenileme, ofis dışı satış senaryoları için idealdir.
Hosted Checkout vs Pay-by-Link — İkisi de barındırmalı sayfa kullanır. Aralarındaki fark:
  • Hosted Checkout → sayfayı Payven barındırır, multi-banka taksit seçimi gösterir.
  • Pay-by-Link → sayfayı banka barındırır (örn. HalkBank Order Link). Tek-banka, tek-link.

​
Akış

​
Endpoint

POST /api/v1/payments/order-link

​
İstek

curl -X POST https://vpos.payven.com.tr/api/v1/payments/order-link \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-link" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id":    "ORDER-1001",
    "amount":         { "amount": 15000, "currency": "TRY" },
    "installment":    1,
    "description":    "Sipariş #1001 ödemesi",
    "customer_email": "musteri@example.com",
    "customer_phone": "+905551234567",
    "return_url":     "https://example.com/odeme/sonuc",
    "callback_url":   "https://api.example.com/webhooks/3d-callback"
  }'
AlanTipZorunlulukAçıklama
amount.amountlong (kuruş)ZorunluTutar
amount.currencyenumZorunluŞu an yalnız "TRY" kabul edilir
installmentintOpsiyonelSabit taksit (varsayılan 1). Banka linkinde müşteriye sunulur.
external_idstringÖnerilirSipariş kimliğiniz
descriptionstringOpsiyonelMüşteriye gösterilecek ödeme açıklaması
customer_emailstringOpsiyonelMüşteri e-posta (raporlama için)
customer_phonestringOpsiyonelMüşteri telefon (raporlama için)
return_urlurlZorunluÖdeme sonrası müşterinin dönmesi gereken URL
callback_urlurlOpsiyonelBankanın callback gönderdiği endpoint (sunucu-sunucu)
extra_propertiesobjectOpsiyonelKonnektör-spesifik özel alanlar

​
Yanıt

{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "processing",
  "extra_properties": {
    "payment_link":      "https://hosted.bank.example.com/pay/abc123def456",
    "provider_order_id": "BANK-ORDER-789",
    "processed_at":      "2026-05-03T13:00:00.123+00:00",
    "expires_at":        "2026-05-04T13:00:00.000+00:00"
  }
}
extra_properties alanıAçıklama
payment_linkMüşteriye gönderilecek tam URL
provider_order_idBankadaki sipariş referans kimliği
processed_atLinkin oluşturulduğu zaman
expires_atLinkin geçerlilik süresi (banka politikasına göre belirlenir, genelde 24 saat)
status: "processing" → link oluşturuldu, müşteri ödeme yapana kadar bu durumda kalır. Müşteri ödediğinde callback ile durum completed/failed olarak güncellenir.

​
Müşteriye iletme

payment_link URL’sini istediğiniz kanaldan iletin. Payven otomatik mail/SMS göndermez — bu sizin sorumluluğunuzdadır.
KanalPratik öneriler
SMSURL kısaltıcı (örn. pyv.tr) ile 160 karakter sınırını aşmayın. URL kısaltmayı sizin sisteminizde yapabilirsiniz.
E-postaTam URL’yi <a href="..."> etiketinde verin.
WhatsApp / TelegramTam URL veya QR olarak gönderin.
QR kodURL’yi 3rd party kütüphane ile QR kod görseline dönüştürüp fiş/ekranda gösterin.

​
Tek tıklama vs çoklu deneme

Banka linkinin davranışı konnektöre özgüdür. Tipik patternler:
SenaryoBanka davranışı
Müşteri ilk denemede başarılıLink tek kullanımlık — ikinci kez çalışmaz
Müşterinin ilk denemesi reddedildiÇoğu banka müşteriye yeniden deneme şansı verir
Süre dolduLink artık çalışmaz — yeni link üretmek gerekir
Final durumu görmek için: GET /api/v1/payments/.

​
Linki “iptal etme”

Mevcut implementasyonda explicit bir DELETE endpoint’i yoktur — banka tarafında link süresini önceden kapatmak için ya:
  • Linkin doğal süresinin dolmasını bekleyin (banka politikası), veya
  • Sipariş tarafında ödemeyi geçersiz işaretleyip yeni süreç başlatın.
Operasyonel iptal süreci için destek ekibimize ulaşın.

​
Webhook olayları

OlayAçıklama
payment.completedMüşteri linkten ödemeyi başarıyla yaptı
payment.failedMüşteri ödeme yaptı ama banka reddetti
3ds.completed / 3ds.failed3DS akışı tetiklendiğinde
Detay: Webhook Olayları.

​
Tipik kullanım kalıpları

Operatör müşteriyle telefonda görüşür, sipariş alır:
  1. CRM’den POST /payments/order-link çağrısı.
  2. payment_link’i alır, kendi SMS / e-posta sisteminden gönderir.
  3. Operatör müşterinin ödeme yapmasını beklemeden çağrıyı kapatabilir.
  4. Webhook ile payment.completed geldiğinde sipariş onaylanır.
Otomatik recurring kullanmıyorsanız:
  1. Vade tarihinden 3 gün önce link üret.
  2. Müşteriye e-posta ile gönder.
  3. Müşteri ödediğinde aboneliği uzat.
  1. Kasa ekranında payment_link’in QR kodunu göster (3rd party QR kütüphanesi ile).
  2. Müşteri telefonuyla okur.
  3. Banka sayfasında ödemeyi yapar.
  4. Kasiyer webhook bildirimini bekler.

​
Konnektör desteği

Pay-by-Link tüm konnektörlerde değil, order_link operasyonunu destekleyen konnektörlerde çalışır. Şu an aktif: HalkBank VPOS. Diğer konnektörler için destek genişlemektedir — güncel liste için konsoldan Ayarlar → Konnektörler ekranını kontrol edin.