Pay-by-Link (Ödeme Linki)

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"
  }'

Alan	Tip	Zorunluluk	Açıklama
`amount.amount`	long (kuruş)	Zorunlu	Tutar
`amount.currency`	enum	Zorunlu	Şu an yalnız `"TRY"` kabul edilir
`installment`	int	Opsiyonel	Sabit taksit (varsayılan `1`). Banka linkinde müşteriye sunulur.
`external_id`	string	Önerilir	Sipariş kimliğiniz
`description`	string	Opsiyonel	Müşteriye gösterilecek ödeme açıklaması
`customer_email`	string	Opsiyonel	Müşteri e-posta (raporlama için)
`customer_phone`	string	Opsiyonel	Müşteri telefon (raporlama için)
`return_url`	url	Zorunlu	Ödeme sonrası müşterinin dönmesi gereken URL
`callback_url`	url	Opsiyonel	Bankanın callback gönderdiği endpoint (sunucu-sunucu)
`extra_properties`	object	Opsiyonel	Konnektö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_link`	Müşteriye gönderilecek tam URL
`provider_order_id`	Bankadaki sipariş referans kimliği
`processed_at`	Linkin oluşturulduğu zaman
`expires_at`	Linkin 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.

Kanal	Pratik öneriler
SMS	URL kısaltıcı (örn. `pyv.tr`) ile 160 karakter sınırını aşmayın. URL kısaltmayı sizin sisteminizde yapabilirsiniz.
E-posta	Tam URL’yi `<a href="...">` etiketinde verin.
WhatsApp / Telegram	Tam URL veya QR olarak gönderin.
QR kod	URL’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:

Senaryo	Banka 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 doldu	Link 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ı

Olay	Açıklama
`payment.completed`	Müşteri linkten ödemeyi başarıyla yaptı
`payment.failed`	Müşteri ödeme yaptı ama banka reddetti
`3ds.completed` / `3ds.failed`	3DS akışı tetiklendiğinde

Detay: Webhook Olayları.

Tipik kullanım kalıpları

Çağrı merkezi

Operatör müşteriyle telefonda görüşür, sipariş alır:

CRM’den POST /payments/order-link çağrısı.
payment_link’i alır, kendi SMS / e-posta sisteminden gönderir.
Operatör müşterinin ödeme yapmasını beklemeden çağrıyı kapatabilir.
Webhook ile payment.completed geldiğinde sipariş onaylanır.

Abonelik yenileme

Otomatik recurring kullanmıyorsanız:

Vade tarihinden 3 gün önce link üret.
Müşteriye e-posta ile gönder.
Müşteri ödediğinde aboneliği uzat.

QR kodla mağaza ödemesi

Kasa ekranında payment_link’in QR kodunu göster (3rd party QR kütüphanesi ile).
Müşteri telefonuyla okur.
Banka sayfasında ödemeyi yapar.
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.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Akış

Endpoint

İstek

Yanıt

Müşteriye iletme

Tek tıklama vs çoklu deneme

Linki “iptal etme”

Webhook olayları

Tipik kullanım kalıpları

Konnektör desteği

​Akış

​Endpoint

​İstek

​Yanıt

​Müşteriye iletme

​Tek tıklama vs çoklu deneme

​Linki “iptal etme”

​Webhook olayları

​Tipik kullanım kalıpları

​Konnektör desteği

Akış

Endpoint

İstek

Yanıt

Müşteriye iletme

Tek tıklama vs çoklu deneme

Linki “iptal etme”

Webhook olayları

Tipik kullanım kalıpları

Konnektör desteği