مقدمة وتعريف بالخدمة #

بوابة الساقي للدفع الإلكتروني

ابدأ تكامل الدفع عبر رابط: صادِق من خادمك، وأنشئ رابط دفع مستضافاً، ثم تحقّق من حالة الدفع قبل إتمام طلب العميل.

البدء السريع المصادقة

توفّر واجهة بوابة الساقي للدفع RESTful طلبات واستجابات بصيغة JSON. يشرح هذا الدليل نموذج الدفع عبر رابط: يوجّه تطبيقك العميل إلى صفحة الساقي المستضافة لإدخال بيانات البطاقة، ويتولى خادمك إنشاء الرابط والتحقق من النتيجة. احتفظ ببيانات الاعتماد ورمز الوصول على الخادم، ولا تعتمد على إعادة التوجيه في المتصفح وحدها لإثبات الدفع.

آلية الربط والتكامل #

يتبع التكامل عبر رابط الدفع أربع خطوات.

المسار بنظرة سريعة #

Create Token  ──▶  Generate Payment Link  ──▶  Cardholder pays (hosted page)  ──▶  Check Payment Status
   (auth)              (returns paymentLink)            (success / fail URL)              (final result)

بيئات التشغيل #

يجري التطوير والاختبار على بيئة الاختبار. وعند الانتقال إلى الإنتاج يتغيّر العنوان الأساسي وبيانات الاعتماد فقط، أمّا المسارات وصيغ الطلبات فمتطابقة في البيئتين.

بطاقة الاختبار

المصادقة والأمان #

تتطلّب نقاط النهاية المحميّة رمز وصول من نوع Bearer يُؤخذ من نقطة إنشاء رمز الوصول. أرسله في ترويسة Authorization مع كل طلب محمي:

Authorization: Bearer ACCESS_TOKEN_STRING

أفضل ممارسات الأمان #

• يجب إرسال جميع الطلبات عبر HTTPS.
• يجب حفظ اسم المستخدم وكلمة المرور ورمز الوصول في خادم التاجر فقط.
• رمز الوصول صالح لمدّة 24 ساعة افتراضيًا، ويجب طلب رمز جديد قبل انتهائه.
• يجب استخدام RequestId جديد لكل عملية دفع.

نظرة عامة على الـ API #

ينشئ نموذج «الدفع عبر رابط» رابط دفع مستضافًا آمنًا. يُدخل حامل البطاقة بياناته على صفحة الساقي المستضافة، مما يُبقيك خارج نطاق امتثال PCI.

إنشاء رمز الوصول #

ينشئ رمز وصول JWT للعميل، ويُعيد معه clientId. يجب إرسال الرمز كترويسة Bearer على نقاط النهاية المحميّة.

جسم الطلب

curl -X POST https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken \
  -H "Content-Type: application/json" \
  -d '{
    "UserName": "client_username",
    "Password": "client_password",
    "ExpireDuration": 1440
  }'

const res = await fetch("https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    UserName: "client_username",
    Password: "client_password",
    ExpireDuration: 1440
  })
});
const data = await res.json();
// store data.access_token and data.clientId
console.log(data.access_token, data.clientId);

import requests

res = requests.post(
    "https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken",
    json={
        "UserName": "client_username",
        "Password": "client_password",
        "ExpireDuration": 1440,
    },
)
data = res.json()
print(data["access_token"], data["clientId"])

{
  "access_token": "ACCESS_TOKEN_STRING",
  "clientId": 29
}

إنشاء رابط الدفع #

ينشئ رابط دفع مستضافًا للعميل. يتطلّب رمز Bearer؛ ويجب أن يطابق {client_id} قيمة clientId المضمّنة في الرمز.

معاملات الرابط

جسم الطلب

curl -X POST https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/1024 \
  -H "Authorization: Bearer ACCESS_TOKEN_STRING" \
  -H "Content-Type: application/json" \
  -d '{
    "RequestId": "REQ-987654321",
    "InvoiceId": "INV-00021",
    "amount": 25000,
    "Currency": "IQD",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail",
    "linkExpireMinutes": 60
  }'

const res = await fetch(
  `https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/${clientId}`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      RequestId: "REQ-987654321",
      InvoiceId: "INV-00021",
      amount: 25000,
      Currency: "IQD",
      successUrl: "https://example.com/success",
      failUrl: "https://example.com/fail",
      linkExpireMinutes: 60
    })
  }
);
const { paymentLink } = await res.json();
// redirect the customer to paymentLink

import requests

res = requests.post(
    f"https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/{client_id}",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "RequestId": "REQ-987654321",
        "InvoiceId": "INV-00021",
        "amount": 25000,
        "Currency": "IQD",
        "successUrl": "https://example.com/success",
        "failUrl": "https://example.com/fail",
        "linkExpireMinutes": 60,
    },
)
print(res.json()["paymentLink"])

{
  "status": true,
  "paymentId": "e6e6fdd0-15a3-4782-9d0d-d1996cda99fe",
  "requestId": "REQ-987654321",
  "invoiceId": "INV-00021",
  "expiry": "2026-06-05T12:51:52.77+03:00",
  "amount": 25000,
  "stanID": "672691",
  "paymentLink": "https://pg-t.alsaqi.net/e6e6fdd0-15a3-4782-9d0d-d1996cda99fe"
}

التحقق من حالة الدفع #

يُعيد الحالة الحالية للدفع. يتطلّب رمز Bearer. يمكنك الاستعلام عبر paymentId أو RequestId أو InvoiceId.

أمّا نقطة النهاية الثانية CheckPaymentStatusByRequestId فمخصّصة للاستعلام عبر RequestId، وتُعيد الاستجابة نفسها.

{ "PaymentId": "4e8185b2-8134-4bc7-aca4-59ee87a45910" }

{ "RequestId": "REQ-987654321" }

{ "InvoiceId": "INV-00021" }

حقول الاستجابة

أمثلة الاستجابة #

{
  "status": true,
  "linkStatus": 2,
  "message": "Approved",
  "paymentId": "170acac1-3eb9-498c-8623-845139eb204a",
  "requestId": "ZO-1780503160412-1020",
  "rrn": "000030614276",
  "cardMasked": "403208******2567",
  "cardHolderName": "GDGBDHFHFN",
  "expiry": "2026-06-17T16:32:40.49",
  "paidDate": "2026-06-03T19:12:52.863",
  "createDate": "2026-06-03T19:12:40.49",
  "totalAmount": 1,
  "respCode": null,
  "errorMessage": null
}

{
  "status": false,
  "linkStatus": 4,
  "message": "Declined",
  "paymentId": "fee05441-0c8c-414a-a756-b532629cb9d3",
  "requestId": "ZO-1779611550221-821",
  "invoiceId": "test-0000350",
  "rrn": "000030617015",
  "cardMasked": "403208******2567",
  "cardHolderName": "AHMED ALI",
  "expiry": "2026-06-07T08:52:30.257",
  "paidDate": "2026-05-24T11:35:11.933",
  "createDate": "2026-05-24T11:32:30.257",
  "totalAmount": 1,
  "respCode": "AB",
  "errorMessage": "رمز CVV2 غير صالح",
  "isReversal": false
}

الاسترجاع والعكس #

الاسترجاع اليدوي #

لا يمكن استرجاع المبلغ عبر الـ API. لاسترجاع مبلغ عملية مكتملة، يتواصل التاجر مع دعم الساقي ويرسل paymentId و rrn.

رموز الأخطاء والحالات #

مرجع حالات الرابط #

يُطابِق حقل linkStatus في كل استجابة حالة إحدى القيم التالية.

رموز استجابة المعالج الشائعة #

مجموعة Postman #

يُحمِّل التاجر المجموعة من الزر أسفل هذا القسم ويستوردها إلى Postman، ثم يُدخل userName و password في تبويب «Variables». باقي القيم تُنسخ من الاستجابات كما في الجدول التالي.

متغيّرات المجموعة

تحميل مجموعة Postman

سجل التغييرات والتحديثات #