---
title: Merchant Entegrasyon Rehberi
description: Hosted Checkout, Merchant API, API imzası, idempotency ve webhook kuralları.
---

# 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:

```http
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:

```text
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

```json
{
  "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:

```json
{
  "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:

1. `X-Epara-Webhook-Signature` doğru mu?
2. Timestamp kabul edilen sürede mi?
3. Event id daha önce işlendi mi?
4. Event type destekleniyor mu?
5. 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ı.