---
title: دليل تكامل التاجر
description: Hosted Checkout وMerchant API والتوقيع وIdempotency وقواعد Webhook.
---

# دليل تكامل التاجر

هذا الدليل لمطوري التجار الذين يريدون التكامل مع Epara. التاجر الصغير يمكنه البدء عبر Payment Links دون كود. التجار الأكبر يستخدمون Merchant API وHosted Checkout وWebhooks للأتمتة.

## خيارات التكامل

| الخيار | من يستخدمه؟ | متى يستخدم؟ |
| --- | --- | --- |
| Payment Link | تاجر بلا فريق هندسي | تحصيل عبر WhatsApp أو Instagram أو SMS أو البريد. |
| Hosted Checkout | تاجر لديه موقع أو تطبيق | عندما تريد أن تستضيف Epara صفحة الدفع الآمنة. |
| Merchant API | تاجر لديه backend | عند أتمتة الطلبات والفواتير والاسترداد والتحويلات والتقارير. |
| QR / Code Payment | متجر فيزيائي أو تحصيل ميداني | عندما يدفع العميل عند الكاشير أو في الموقع. |
| Webhooks | تاجر لديه نظام طلبات | عندما يجب أن تصل أحداث payment/refund/payout/dispute إلى نظام التاجر. |

## البيئات

| Environment | الهدف | حركة المال |
| --- | --- | --- |
| test | تكامل وتجربة وQA وcredential تجريبي | لا توجد أموال حقيقية. |
| live | نشاط حقيقي للتاجر والمستهلك | سجلات حقيقية في provider وLedger. |

بيانات test وlive منفصلة. لا يمكن لـtest credential إنشاء live payments.

## قاعدة الطلب الأساسية

طلبات Merchant API يجب أن تحمل ترويسات التوقيع:

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

## نموذج التوقيع

Epara توقع method وpath وtimestamp وnonce وAPI version وbody hash. هذا يثبت:

- الطلب جاء من خادم Merchant.
- body لم يتغير أثناء النقل.
- nonce لم يستخدم من قبل.
- فرق الوقت مقبول.
- Merchant يستخدم API version المتوقع.

مثال 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

كل طلب ينشئ حالة دائمة أو يحرك المال يجب أن يحمل `Idempotency-Key`.

| العملية | مطلوب؟ | السبب |
| --- | --- | --- |
| Payment create/capture | نعم | لا يجب إنشاء نفس الدفع مرتين. |
| Refund create | نعم | لا يجب تنفيذ نفس الاسترداد مرتين. |
| Payout request | نعم | لا يجب تحويل المال للتاجر مرتين لنفس الطلب. |
| Payment Link create | نعم | retry يجب أن يعيد نفس الرابط. |
| Read/list requests | لا | لا تنشئ حالة دائمة أو حركة مالية. |

## مثال إنشاء Payment Link

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

استجابة ناجحة:

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

## Webhook events

لا يجب أن يعتمد Merchant فقط على redirect URLs. النتيجة النهائية الموثوقة تأتي من webhooks موقعة.

| Event | متى يحدث؟ |
| --- | --- |
| `checkout.session.completed` | عند اكتمال Hosted Checkout بنجاح. |
| `payment.captured` | عندما يصبح Payment حركة نهائية في Ledger. |
| `payment.failed` | عندما لا يكتمل الدفع. |
| `refund.succeeded` | عند اكتمال الاسترداد. |
| `payout.paid` | عندما يؤكد Provider دفع Payout. |
| `dispute.opened` | عند فتح dispute أو chargeback. |

## تحقق Webhook

على Merchant التحقق من:

1. `X-Epara-Webhook-Signature` صحيح.
2. timestamp داخل نافذة الوقت المقبولة.
3. event id لم يعالج من قبل.
4. event type مدعوم.
5. object id يخص السجل المتوقع في نظام Merchant.

## نموذج الأخطاء

| HTTP status | المعنى |
| --- | --- |
| 400 | payload غير صالح أو حقل مطلوب ناقص. |
| 401 | credential مفقود أو التوقيع غير صحيح. |
| 403 | scope لا يسمح بالعملية. |
| 404 | object غير موجود أو لا يخص Merchant. |
| 409 | تعارض idempotency أو حالة object. |
| 422 | منع بسبب قاعدة أعمال أو حد أو risk أو verification. |
| 429 | rate limit. |
| 500 | خطأ داخلي في المنصة. يمكن retry مع idempotency. |

## Checklist التكامل

- تم إنشاء test API credential.
- تم إكمال test payment link أو checkout session.
- Webhook endpoint يتحقق من التوقيع.
- تم اختبار retry وidempotency.
- تم اختبار refund.
- تمت الموافقة على payout destination وschedule.
- live API credential منفصل عن test.
- تم اختبار live webhook endpoint.
- اكتمل merchant go-live review.