للمطوّرين
التكامل في أربع خطوات
REST API وJSON وطلبات موقّعة. التوثيق مع أمثلة Node.js متاح دون تسجيل.
- الخطوة 1
وقّع الطلب
HMAC-SHA256 للطابع الزمني والطريقة والمسار وتجزئة المحتوى. يبقى المفتاح على خادمك فقط.
X-Shop-Id: shop_… X-Timestamp: 1793400000 X-Signature: hex(HMAC-SHA256(secret_key, timestamp ⏎ METHOD ⏎ path ⏎ sha256(body))) - الخطوة 2
أنشئ دفعة
المبلغ بأصغر وحدة للعملة. تكرار الطلب بنفس Idempotency-Key يُرجع الدفعة نفسها.
POST /v1/payments Idempotency-Key: 4f1c… { "orderId": "A-1001", "amount": 24990, "currency": "EUR", "returnUrl": "https://shop.example/thanks" } - الخطوة 3
وجّه العميل للدفع
تعرض صفحة الدفع الطرق حسب البلد والعملة، وتستقبل الدفعة وتعيد العميل إليك.
→ 201 { "id": "pay_…", "status": "created", "checkoutUrl": "https://pay…/c/…" } - الخطوة 4
استقبل الـ webhook
تحقق من التوقيع وعلّم الطلب كمدفوع. إن لم يصل رد 2xx نعيد المحاولة لمدة يومين.
POST https://shop.example/payos/webhook X-Payos-Signature: v1=… { "type": "payment.succeeded", "data": { "orderId": "A-1001", … } }