Merchant Entegrasyon Rehberi

Bu sayfa merchant geliştiricisinin Epara'ya doğru ve güvenli bağlanması için hazırlanmıştır. Merchant dashboard üzerinden no-code Payment Link kullanılabilir; daha büyük merchant'lar Merchant API, Hosted Checkout ve Webhooks ile otomasyon kurar.

Entegrasyon seçenekleri

Seçenek	Kim kullanır?	Ne zaman seçilir?
Payment Link	Teknik ekibi olmayan merchant	WhatsApp, Instagram, SMS veya e-posta ile hızlı tahsilat.
Hosted Checkout	Web sitesi veya uygulaması olan merchant	Ödeme sayfasını Epara'nın güvenli host etmesi istendiğinde.
Merchant API	Backend sistemi olan merchant	Sipariş, fatura, refund, payout ve rapor akışları otomatikleştiğinde.
QR / Code Payment	Fiziksel dükkan veya saha tahsilatı	Müşteri kasada QR/kod ile ödeme yapacaksa.
Webhooks	Sipariş sistemi olan merchant	Payment success, refund, payout veya dispute event'leri merchant sistemine düşecekse.

Ortamlar

Environment	Amaç	Para hareketi
test	Entegrasyon, demo, QA, test credential	Gerçek para hareketi yoktur.
live	Gerçek merchant ve consumer işlemleri	Ledger ve provider üzerinden gerçek finansal kayıt oluşur.

Test ve live credential birbirinden ayrı tutulmalıdır. Test credential ile live payment oluşturulamaz.

API temel kuralı

Merchant API request'leri şu başlıkları taşımalıdır:

POST /api/merchant/payment-links HTTP/1.1
Host: api.epara.example
Content-Type: application/json
X-Epara-Key-Id: key_test_...
X-Epara-Timestamp: 2026-06-16T12:00:00Z
X-Epara-Nonce: 0f7d8a1a-6f0b-4c9d-9f92-8d865bb2a111
X-Epara-Signature: hmac_sha256_signature
X-Epara-API-Version: 2026-06-14.basra
Idempotency-Key: plink_school_2026_001

İmza mantığı

Epara request body hash, path, method, timestamp, nonce ve API version bilgisini canonical string içinde imzalar. Amaç:

Request gerçekten merchant server'dan mı geldi?
Body yolda değişti mi?
Aynı nonce tekrar kullanıldı mı?
Timestamp kabul edilen drift penceresinde mi?
Merchant doğru API version ile mi konuşuyor?

Örnek canonical string:

POST
/api/merchant/payment-links
2026-06-16T12:00:00Z
0f7d8a1a-6f0b-4c9d-9f92-8d865bb2a111
2026-06-14.basra
sha256:6fd0a4...

Idempotency

Para hareketi veya kalıcı object oluşturan her request Idempotency-Key taşımalıdır.

İşlem	Idempotency gerekli mi?	Neden
Payment create/capture	Evet	Aynı ödeme iki kez oluşmamalı.
Refund create	Evet	Aynı iade iki kez yapılmamalı.
Payout request	Evet	Merchant'a iki kez transfer çıkmamalı.
Payment Link create	Evet	Retry durumunda aynı link dönmeli.
Read/list requests	Hayır	Para veya kalıcı object yaratmaz.

Örnek Payment Link oluşturma

{
  "merchantId": "mrc_demo_market",
  "title": "School fee - June 2026",
  "amount": 255000,
  "currency": "IQD",
  "referencePrefix": "SCH-2026",
  "allowedMethods": ["card", "consumer_wallet", "local_method"],
  "successUrl": "https://merchant.example/success",
  "cancelUrl": "https://merchant.example/cancel"
}

Başarılı response:

{
  "id": "plink_school_2026",
  "status": "active",
  "hostedUrl": "https://pay.epara.example/pay/school-fee",
  "amount": { "amount": 255000, "currency": "IQD" }
}

Webhook eventleri

Merchant sisteminin güvenilir olması için ödeme sonucunu sadece redirect URL üzerinden okumaması gerekir. Asıl kesin bilgi signed webhook ile gelmelidir.

Event	Ne zaman gelir?
`checkout.session.completed`	Hosted Checkout başarıyla tamamlandığında.
`payment.captured`	Payment final ledger hareketine dönüştüğünde.
`payment.failed`	Payment tamamlanamadığında.
`refund.succeeded`	Refund başarıyla tamamlandığında.
`payout.paid`	Payout provider tarafından başarılı bildirildiğinde.
`dispute.opened`	Payment için dispute veya chargeback dosyası açıldığında.

Webhook doğrulama

Webhook payload'ı da imzalanır. Merchant şu kontrolleri yapmalıdır:

X-Epara-Webhook-Signature doğru mu?
Timestamp kabul edilen sürede mi?
Event id daha önce işlendi mi?
Event type destekleniyor mu?
Object id merchant sisteminde beklenen kayda denk geliyor mu?

Hata modeli

HTTP status	Anlam
400	Payload geçersiz veya zorunlu alan eksik.
401	API credential eksik veya imza doğrulanamadı.
403	Credential scope bu işleme yetmiyor.
404	Object bulunamadı veya merchant'a ait değil.
409	Idempotency veya object state conflict.
422	Business rule, limit, risk veya verification engeli.
429	Rate limit.
500	Platform internal error. Retry yapılabilir ama idempotency korunmalıdır.

Merchant entegrasyon checklist

Test API credential oluşturuldu.
Test payment link veya checkout session başarıyla tamamlandı.
Webhook endpoint signed event doğruluyor.
Retry/idempotency test edildi.
Refund akışı test edildi.
Payout destination ve schedule onaylandı.
Live API credential ayrı tutuldu.
Live webhook endpoint test edildi.
Merchant go-live review tamamlandı.