> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> تحقق من الحالة الحالية لدفع باستخدام كود مرجعه

<div dir="rtl">
  ## نظرة عامة

  تحقق من حالة الدفع في الوقت الفعلي باستخدام مرجع الدفع. ضروري لمعالجة الطلبات والاستعلام عن الحالة والتحقق من المدفوعات.

  <Info>
    **الكشف التلقائي عن البيئة**: يتحقق هذا الـ endpoint تلقائياً من معاملات الإنتاج (SATIM) والـ sandbox بناءً على مكان إنشاء الدفع.
  </Info>

  ## معاملات المسار

  <ParamField path="ref" type="string" required>
    كود مرجع الدفع (التنسيق: `OCPL-XXXXXX-YYYY`)

    <Note>
      هذا هو `paymentRef` الذي يُعاد عند إنشاء رابط الدفع
    </Note>
  </ParamField>

  ## الاستجابة

  <ResponseField name="success" type="boolean">
    يشير إلى نجاح العملية
  </ResponseField>

  <ResponseField name="data" type="object">
    معلومات حالة الدفع

    <Expandable title="خصائص data">
      <ResponseField name="status" type="string">
        حالة الدفع الحالية - `PENDING` - الدفع لم يُبدأ بعد أو قيد المعالجة - `CONFIRMED` - الدفع ناجح - `FAILED` - فشل الدفع أو انتهت صلاحية الرابط
      </ResponseField>

      <ResponseField name="message" type="string">
        وصف قابل للقراءة للحالة
      </ResponseField>

      <ResponseField name="paymentRef" type="string">
        كود مرجع الدفع
      </ResponseField>

      <ResponseField name="transactionDetails" type="object">
        معلومات إضافية عن المعاملة (عند التوفر)

        <Expandable title="خصائص transactionDetails">
          <ResponseField name="amount" type="number">
            مبلغ الدفع بالدينار الجزائري
          </ResponseField>

          <ResponseField name="currency" type="string">
            كود العملة (دائماً `"DZD"`)
          </ResponseField>

          <ResponseField name="isSandbox" type="boolean">
            ما إذا كانت معاملة sandbox
          </ResponseField>

          <ResponseField name="createdDate" type="string">
            طابع زمني لإنشاء المعاملة (ISO 8601)
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="meta" type="object">
    بيانات وصفية للاستجابة

    <Expandable title="خصائص meta">
      <ResponseField name="timestamp" type="string">
        طابع زمني للاستجابة (ISO 8601)
      </ResponseField>

      <ResponseField name="requestId" type="string">
        معرف طلب فريد للدعم
      </ResponseField>
    </Expandable>
  </ResponseField>

  ## شرح قيم الحالة

  <AccordionGroup>
    <Accordion title="PENDING" icon="clock">
      **عند رؤية هذه الحالة:**

      * لم يبدأ العميل عملية الدفع بعد
      * الدفع قيد المعالجة من قِبل البنك
      * الرابط تم إنشاؤه للتو ولم يُستخدم بعد

      **ما يجب فعله:**

      * استمر في الاستعلام عن تحديثات الحالة
      * اعرض "الدفع معلق" للعميل
      * لا تُنفِّذ الطلب بعد
    </Accordion>

    <Accordion title="CONFIRMED" icon="circle-check">
      **عند رؤية هذه الحالة:** - اكتمل الدفع بنجاح - ستُضاف الأموال إلى رصيد OneClick الخاص بك

      **ما يجب فعله:**

      * ضع علامة على الطلب كمدفوع في نظامك
      * نفِّذ الطلب/قدِّم الخدمة
      * أرسل تأكيداً للعميل
    </Accordion>

    <Accordion title="FAILED" icon="circle-xmark">
      **عند رؤية هذه الحالة:**

      * تم رفض الدفع أو فشل
      * انتهت صلاحية رابط الدفع (20 دقيقة)
      * ألغى العميل الدفع

      **ما يجب فعله:**

      * ضع علامة على الطلب كفاشل/ملغى
      * أنشئ رابط دفع جديداً إذا أراد العميل إعادة المحاولة
      * لا تُنفِّذ الطلب
    </Accordion>
  </AccordionGroup>

  ## انتهاء صلاحية الرابط

  <Warning>
    تنتهي صلاحية روابط الدفع بعد **20 دقيقة** من الإنشاء إذا لم يُبدأ أي دفع. بعد انتهاء الصلاحية ستكون الحالة `FAILED`.
  </Warning>

  <RequestExample>
    ```bash cURL theme={null}
    curl --request GET \
      --url https://api.oneclickdz.com/v3/ocpay/checkPayment/OCPL-A1B2C3-D4E5 \
      --header 'X-Access-Token: YOUR_API_KEY'
    ```

    ```javascript JavaScript theme={null}
    const response = await fetch(
      "https://api.oneclickdz.com/v3/ocpay/checkPayment/OCPL-A1B2C3-D4E5",
      {
        method: "GET",
        headers: {
          "X-Access-Token": "YOUR_API_KEY",
        },
      }
    );

    const data = await response.json();
    console.log("Payment Status:", data.data.status);
    console.log("Message:", data.data.message);
    ```

    ```python Python theme={null}
    import requests

    ref = "OCPL-A1B2C3-D4E5"
    url = f"https://api.oneclickdz.com/v3/ocpay/checkPayment/{ref}"
    headers = {
        "X-Access-Token": "YOUR_API_KEY"
    }

    response = requests.get(url, headers=headers)
    data = response.json()

    print(f"Payment Status: {data['data']['status']}")
    print(f"Message: {data['data']['message']}")
    ```

    ```php PHP theme={null}
    <?php
    $ref = 'OCPL-A1B2C3-D4E5';
    $url = "https://api.oneclickdz.com/v3/ocpay/checkPayment/{$ref}";
    $headers = [
        'X-Access-Token: YOUR_API_KEY'
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    $data = json_decode($response, true);

    echo "Payment Status: " . $data['data']['status'] . "\n";
    echo "Message: " . $data['data']['message'] . "\n";
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json دفع مؤكد (200) theme={null}
    {
      "success": true,
      "data": {
        "status": "CONFIRMED",
        "message": "Payment confirmed successfully",
        "paymentRef": "OCPL-A1B2C3-D4E5",
        "transactionDetails": {
          "amount": 5000,
          "currency": "DZD",
          "isSandbox": false,
          "createdDate": "2025-01-15T10:30:00Z"
        }
      },
      "meta": {
        "timestamp": "2025-01-15T10:35:00Z",
        "requestId": "req_abc123xyz"
      }
    }
    ```

    ```json دفع معلق (200) theme={null}
    {
      "success": true,
      "data": {
        "status": "PENDING",
        "message": "Payment not yet initiated",
        "paymentRef": "OCPL-A1B2C3-D4E5",
        "transactionDetails": {
          "amount": 5000,
          "currency": "DZD",
          "isSandbox": false
        }
      },
      "meta": {
        "timestamp": "2025-01-15T10:32:00Z",
        "requestId": "req_abc123xyz"
      }
    }
    ```
  </ResponseExample>

  ## مثال التكامل

  إليك كيفية تنفيذ التحقق من الحالة في نظام الطلبات الخاص بك:

  ```javascript theme={null}
  async function checkOrderPayment(orderId) {
    // Get payment ref from your database
    const order = await db.orders.findOne({ id: orderId });

    if (!order || !order.paymentRef) {
      throw new Error("Order not found or no payment link");
    }

    // Check payment status
    const response = await fetch(
      `https://api.oneclickdz.com/v3/ocpay/checkPayment/${order.paymentRef}`,
      {
        headers: { "X-Access-Token": process.env.ONECLICK_API_KEY },
      }
    );

    const data = await response.json();

    // Update order status based on payment status
    switch (data.data.status) {
      case "CONFIRMED":
        await db.orders.update(orderId, {
          status: "paid",
          paidAt: new Date(),
        });
        await fulfillOrder(orderId);
        break;

      case "FAILED":
        await db.orders.update(orderId, {
          status: "payment_failed",
        });
        break;

      case "PENDING":
        // Keep polling
        break;
    }

    return data.data;
  }
  ```

  ## الخطوات التالية

  <CardGroup cols={2}>
    <Card title="إنشاء رابط دفع" icon="link" href="/ar/api-reference/ocpay/create-link">
      تعلم كيفية إنشاء روابط الدفع
    </Card>

    <Card title="دليل التكامل" icon="book" href="/ar/ocpay-guides/overview">
      دليل تكامل Navio الكامل
    </Card>
  </CardGroup>
</div>