المطوّرون
ثلاثة استدعاءات وWebhook.
Gateway هو checkout مستضاف، لذا جاء التكامل صغيرًا عن قصد: أنشئ طلبًا، ووجّه العميل إلى الصفحة، ثم تحقّق من النتيجة الموقّعة. هذا كل ما في الأمر — واجهة الدفع ومنطق الطرق و3-D Secure والمحافظ والإيصالات علينا بناؤها وإبقاؤها محدّثة.
الصورة العامة
ما الذي ستتكامل معه.
- REST عبر HTTPS
- JSON في الطلب وJSON في الرد
- مفاتيح API من نوع Bearer
- مفاتيح Idempotency
- Webhooks موقّعة
- الحماية من إعادة الإرسال
- وضعا الاختبار والإنتاج
- SDK لـ iOS وAndroid
- إضافات المتاجر
- حقول مضمّنة
البدء السريع
من الصفر إلى طلب مدفوع.
المسار الكامل عند نجاح العملية. المبالغ بأصغر وحدة للعملة، والمراجع من عندك، ورابط checkout هو ما توجّه العميل إليه. يُصدر عنوان API الأساسي مع مفاتيح sandbox — صدّره باسم PROTOCORE_API_BASE وستعمل الاستدعاءات أدناه كما هي.
إنشاء الطلب
استدعاء واحد يتضمن المبلغ والعملة ومرجعك الخاص. مفتاح idempotency من توليدك — الطلب المُعاد يرجع الطلب الأصلي ولا ينشئ طلبًا ثانيًا.
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'وجّه العميل إلى checkout
يتضمن الرد رابط checkout على مضيف checkout الخاص بك — الصادر مع sandbox، أو نطاقك الخاص بعد ربطه بنا. وجّه العميل إليه، أو افتحه عبر SDK؛ ففي تلك الصفحة توجد الطرق والمحافظ و3-D Secure، فلا شيء لتبنيه من جانبك.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}تحقّق من النتيجة الموقّعة
عند اكتمال الدفع يصل حدث موقّع إلى نقطة النهاية لديك. تحقّق من التوقيع بمقارنته بسرّ webhook قبل أن تثق بأي شيء، ثم نفّذ الطلب بحسب المرجع الذي تعرفه مسبقًا.
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}المرجع
نقاط النهاية التي ستستخدمها فعلًا.
في الوثائق المزيد، لكن هذه المجموعة هي ما لا تتجاوزه معظم التكاملات.
Webhooks
ما يصل إلى الواجهة الخلفية لديك.
يحمل كل حدث مرجع الطلب الذي أنشأته، فيكفي أن يكون معالجك switch على النوع وبحثًا في بياناتك.
تحقّق من التوقيع قبل أن تثق بالمحتوى.
يحمل كل إرسال طابعًا زمنيًا وتوقيع HMAC على المحتوى الخام. قارن في زمن ثابت، وارفض ما يتجاوز نافذة التسامح لديك، واعتبر معرّف الحدث المكرر معالجًا مسبقًا — نعيد المحاولة عند أي رد غير 2xx، لذا ينبغي أن يكون معالجك idempotent أيضًا.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}الضمانات
الخصائص التي يمكنك البناء عليها.
إنشاء idempotent
يأخذ كل إنشاء طلب مفتاح idempotency. الطلب المُعاد — بعد انتهاء مهلة أو نشر جديد أو إعادة تسليم من الطابور — يعيد الطلب الأصلي بدل أن يخصم مرتين.
أحداث موقّعة ومحمية من إعادة الإرسال
تحمل Webhooks توقيع HMAC مؤرّخًا ومعرّف حدث ثابتًا. تُعاد المحاولات تدريجيًا حتى ترد نقطة النهاية لديك بـ 2xx، فلا تضيع دفعة بسبب نافذة نشر.
مرجع واحد من البداية إلى النهاية
المرجع الذي تحدّده عند الإنشاء يظهر في checkout والإيصال وwebhook والدفعة وأي استرداد لاحق. لا معرّف ثانيًا تحتاج إلى مطابقته بين الأنظمة.
وضع الاختبار يسلك المسار البرمجي نفسه
تشغّل مفاتيح الاختبار التدفقات نفسها على جلسات اختبار. ما ينجح في الاختبار هو ما يُطلق — الفرق في المفاتيح التي ترسلها، لا في نقاط النهاية التي تستدعيها.
بيانات الاختبار
كيف تختبر المسارات التي تهمّ.
خلف كل مسار أدناه بطاقة اختبار، تجدها مع مفاتيحك عند إصدار بيئة الـ sandbox. الأرقام خاصة بكل بيئة ولا تُنشر هنا، لتبقى صحيحة مع تغيّر نطاقات اختبار الشبكات. السلوك حتمي في كل الأحوال: يسهل أن يتحقق الاختبار من الرفض كما يتحقق من النجاح.
احصل على المفاتيح وابدأ.
merchant تجريبي في sandbox مع مفاتيح API وأسرار webhook وكل الطرق مفعّلة، إضافةً إلى المرجع الكامل، ليتمكن فريقك من التكامل قبل توقيع أي شيء.