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

هذا الدليل لمطوري التجار الذين يريدون التكامل مع 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 يجب أن تحمل ترويسات التوقيع:

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:

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

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

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

{
  "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 التحقق من:

X-Epara-Webhook-Signature صحيح.
timestamp داخل نافذة الوقت المقبولة.
event id لم يعالج من قبل.
event type مدعوم.
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.