> ## 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="ltr">
  ## نظرة عامة

  يدفع فاتورة واحدة من عملية اكتشاف بحالة `READY`. تختار `billId` واحدًا من `bills[]` الخاصة بتلك المعاملة؛ ثم تحمل المعاملة نفسها الدفعة حتى تبلغ حالة نهائية.

  <Warning>
    **`200` إقرار بالاستلام، وليس نتيجة.** فهو يعني أن الدفعة قُبِلت وأنها الآن قيد التنفيذ. أما ما إذا كانت الأموال قد تحركت فعلًا فلا يُعرف إلا من `status` الخاص بالمعاملة — استعلم دوريًا حتى تبلغ `SUCCESS` أو `FAILED` أو `REFUNDED`.
  </Warning>

  هذا هو الاستدعاء الذي يحرّك الأموال. كل ما تحتاجه من جانبك — سجل الطلب والمبلغ وتفويض عميلك — ينبغي أن يكون محفوظًا بالفعل قبل أن ترسله.

  ## متن الطلب

  <ParamField body="transactionId" type="string" required>
    عملية الاكتشاف المطلوب الدفع مقابلها. يجب أن تكون سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة، ويجب أن تكون المعاملة حاليًا بحالة `READY`.
  </ParamField>

  <ParamField body="billId" type="string" required>
    قيمة `billId` لأحد العناصر في `bills[]` الخاصة بتلك المعاملة. 100 حرف كحد أقصى.

    انسخها من الاستجابة — لا تُنشئها بنفسك.
  </ParamField>

  <ParamField body="ref" type="string" required>
    مرجع **جديد** لهذه الدفعة. 100 حرف كحد أقصى، وفريد بين معاملاتك النشطة لدى هذا الشريك.

    يجب أن يختلف عن `ref` الذي استخدمته للاكتشاف؛ إعادة استخدام تلك القيمة تُجيب بـ `403 DUPLICATED_REF`.
  </ParamField>

  <Note>
    تحتفظ المعاملة بالمرجع `ref` الذي أُنشئت به. مرجع الاكتشاف الأصلي ذاك هو ما تُعيده هذه الـ endpoint، وما يبحث عنه [الحصول على المعاملة بالمرجع](/ar/api-reference/bill-payment/check-by-ref)، وما يظهر على المعاملة من الآن فصاعدًا.
  </Note>

  ## الاستجابة

  <ResponseField name="success" type="boolean" required>
    `true` عندما تُقبَل الدفعة.
  </ResponseField>

  <ResponseField name="data" type="object" required>
    <Expandable title="properties">
      <ResponseField name="transactionId" type="string" required>
        المعاملة نفسها، وهي تحمل الدفعة الآن.
      </ResponseField>

      <ResponseField name="ref" type="string" required>
        مرجع `ref` الاكتشاف الخاص بالمعاملة.
      </ResponseField>

      <ResponseField name="status" type="string" required>
        دائمًا `PROCESSING` عند هذه النقطة.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="meta" type="object" required>
    <Expandable title="properties">
      <ResponseField name="timestamp" type="string" required>
        وقت الاستجابة، ISO 8601 بتوقيت UTC.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="requestId" type="string" required>
    معرّف الربط، يُرسل أيضًا في ترويسة الاستجابة `X-Request-Id`.
  </ResponseField>

  ## الأمثلة

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://billapi.oneclickdz.com/v3/bills/pay \
      -X POST \
      -H "Content-Type: application/json" \
      -H "X-Access-Token: YOUR_API_KEY" \
      -d '{
        "transactionId": "68b2f4c1a7d3e9f204c81a55",
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "ref": "pay-inv-2026-0042"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://billapi.oneclickdz.com/v3/bills/pay", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
      },
      body: JSON.stringify({
        transactionId: "68b2f4c1a7d3e9f204c81a55",
        billId: "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        ref: "pay-inv-2026-0042",
      }),
    });

    const body = await response.json();

    if (!body.success) {
      throw new Error(`${body.error.code}: ${body.error.message}`);
    }

    // Accepted — in flight. Poll until the status is final.
    console.log(body.data.status); // "PROCESSING"
    ```

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

    response = requests.post(
        'https://billapi.oneclickdz.com/v3/bills/pay',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')
        },
        json={
            'transactionId': '68b2f4c1a7d3e9f204c81a55',
            'billId': 'sbx_bill_68b2f4c1a7d3e9f204c81a55_0',
            'ref': 'pay-inv-2026-0042'
        }
    )

    body = response.json()

    if not body['success']:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

    # Accepted — in flight. Poll until the status is final.
    print(body['data']['status'])  # "PROCESSING"
    ```

    ```php PHP theme={null}
    <?php
    $payload = [
        'transactionId' => '68b2f4c1a7d3e9f204c81a55',
        'billId'        => 'sbx_bill_68b2f4c1a7d3e9f204c81a55_0',
        'ref'           => 'pay-inv-2026-0042'
    ];

    $ch = curl_init('https://billapi.oneclickdz.com/v3/bills/pay');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$body['success']) {
        throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
    }

    // Accepted — in flight. Poll until the status is final.
    echo $body['data']['status']; // "PROCESSING"
    ?>
    ```
  </CodeGroup>

  ### استجابة النجاح

  ```json theme={null}
  {
    "success": true,
    "data": {
      "transactionId": "68b2f4c1a7d3e9f204c81a55",
      "ref": "disc-inv-2026-0042",
      "status": "PROCESSING"
    },
    "meta": {
      "timestamp": "2026-08-31T10:15:38.410Z"
    },
    "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
  }
  ```

  بمجرد أن تبلغ المعاملة الحالة `SUCCESS`، يُرجع [الحصول على المعاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id) الحقلين `operationId` و`receiptUrl` إلى جانب `selectedBill` و`total`.

  ## استجابات الخطأ

  <AccordionGroup>
    <Accordion title="400 — خطأ في التحقق">
      **المتن لم يطابق المخطط.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "ERR_VALIDATION",
          "message": "transactionId must be 24 characters long",
          "details": ["transactionId must be 24 characters long"]
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      الأسباب الشائعة: `transactionId` ليس من 24 حرفًا سداسيًا عشريًا، أو غياب `billId`، أو غياب `ref`، أو `ref` أطول من 100 حرف.

      **ما العمل:** صحّح الطلب. لا تعد إرساله دون تغيير أبدًا.
    </Accordion>

    <Accordion title="401 — رمز وصول مفقود أو غير صالح">
      **المفتاح غائب أو مرفوض.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INVALID_ACCESS_TOKEN",
          "message": "The provided access token is invalid."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** تحقق من المفتاح عبر [التحقق من مفتاح API](/ar/api-reference/bill-payment/validate-key). لم يُخصم أي مبلغ.
    </Accordion>

    <Accordion title="403 — مرجع مكرر">
      **المرجع `ref` مستخدم بالفعل مع هذا الشريك.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "DUPLICATED_REF",
          "message": "A transaction with this ref already exists for this partner."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      السبب الأكثر شيوعًا هو إعادة استخدام مرجع `ref` الاكتشاف في الدفع. أرسل قيمة مختلفة، مثلًا `pay-` قبل معرّف طلبك.

      **ما العمل:** قبل إعادة المحاولة، تحقق من الحالة الحالية للمعاملة عبر [الحصول على المعاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id). إذا كانت بالفعل `PROCESSING`، فقد نفذت دفعتك ولا شيء لإعادة إرساله.
    </Accordion>

    <Accordion title="404 — غير موجودة أو غير قابلة للدفع">
      **المعاملة غير موجودة ضمن حسابك، أو أنها ليست في حالة قابلة للدفع، أو أن `billId` ليس من ضمن فواتيرها.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "NOT_FOUND",
          "message": "Transaction is not in a payable state, or the bill was not found."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      الحالات الثلاث كلها تُجيب بـ `404` — بما في ذلك معاملة تعود إلى شريك آخر، حتى لا تؤكد واجهة API أبدًا وجود معاملة تخص غيرك.

      **ما العمل:** أعد قراءة المعاملة. إذا لم تعد `status` هي `READY`، فقد بدأت الدفعة بالفعل؛ استعلم عنها دوريًا بدلًا من إرسال دفعة أخرى.
    </Accordion>

    <Accordion title="409 — الفاتورة مدفوعة مسبقًا">
      **هذه الفاتورة بعينها سُدِّدت بالفعل.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "BILL_ALREADY_PAID",
          "message": "This bill has already been paid."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** تعامل معها كنتيجة ناجحة تملكها بالفعل. ابحث عن المعاملة المدفوعة في [قائمة المعاملات](/ar/api-reference/bill-payment/list-transactions) واستخدم إيصالها. لا تحمّل عميلك المبلغ مرتين.
    </Accordion>

    <Accordion title="409 — دفعة قيد التنفيذ">
      **دفعة أخرى للفاتورة نفسها لم تنتهِ بعد.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "PAYMENT_IN_PROGRESS",
          "message": "A payment for this bill is currently in progress."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** استعلم دوريًا عن المعاملة الجارية بالفعل. إرسال هذا مجددًا لن يجعلها تنتهي أسرع.
    </Accordion>

    <Accordion title="503 — الشريك غير متاح">
      **تعذّر الوصول إلى مُصدِر الفواتير، أو أنه موقوف حاليًا.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "PARTNER_UNAVAILABLE",
          "message": "Partner temporarily unavailable — please try again later."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** لم يُخصم أي مبلغ. لا تزال عملية الاكتشاف بحالة `READY`، لذا يمكنك دفع `billId` نفسه لاحقًا — بالمرجع `ref` نفسه، فهو لم يُستهلك قط.
    </Accordion>

    <Accordion title="503 — المصادقة غير متاحة">
      **لم نتمكن من التحقق من مفتاحك في الوقت المحدد. مفتاحك ليس هو المشكلة.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "AUTH_UNAVAILABLE",
          "message": "Authentication is temporarily unavailable. Please retry shortly."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** انتظر مدة `Retry-After` (5 ثوانٍ) وأعد إرسال الطلب نفسه. لم يصل الطلب أبدًا إلى مسار الدفع، لذا فإعادة إرساله آمنة.
    </Accordion>

    <Accordion title="503 — الخدمة غير متاحة">
      **واجهة Bill Payment API في صيانة مُخطط لها.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "The service is temporarily unavailable. Please retry shortly."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** التزم بـ `Retry-After` وأعد المحاولة.
    </Accordion>

    <Accordion title="500 — خطأ داخلي">
      **حدث خلل من جانبنا.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "An unexpected error occurred."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** **لا تعد إرسال الدفعة.** اقرأ المعاملة أولًا — إذا كانت `PROCESSING`، فالدفعة قيد التنفيذ. تواصل مع الدعم مع ذكر `requestId` إذا كانت الحالة غير واضحة.
    </Accordion>
  </AccordionGroup>

  ## ما الذي تدفعه

  كل فاتورة في عملية اكتشاف تحمل حقولها المالية الخاصة.

  | الحقل    | المعنى                                              |
  | -------- | --------------------------------------------------- |
  | `amount` | المبلغ المستحق لمُصدِر الفواتير، بالدينار الجزائري  |
  | `fee`    | رسوم خدمة OneClickDz مقابل دفعها، بالدينار الجزائري |
  | `total`  | `amount + fee` — المبلغ الذي يُخصم من رصيدك         |

  الرسوم نسبة مئوية من المبلغ، محصورة بين حد أدنى وحد أقصى، **تُضبط لكل مُصدِر فاتورة على حدة**:

  | مُصدِر الفاتورة   | النسبة | الحد الأدنى | الحد الأقصى |
  | ----------------- | ------ | ----------- | ----------- |
  | `ADE`             | 0.5%   | 30 DZD      | 60 DZD      |
  | `SONELGAZ`        | 0.5%   | 30 DZD      | 60 DZD      |
  | `Algérie Télécom` | 0.5%   | 10 DZD      | 50 DZD      |

  بما أن 0.5% من فاتورة اعتيادية تقل كثيرًا عن الحد الأدنى، تُحتسب معظم المدفوعات بالحد الأدنى تمامًا. هذه القيم إعدادات قابلة للتعديل، لذا اقرأ `fee` من الاستجابة بدلًا من إعادة حسابه. يظهر `total` على المعاملة بمجرد اختيار فاتورة.

  بالنسبة لفاتورة ADE البالغة 443.39 دينار جزائري أعلاه: نسبة 0.5% تساوي 2.22، وهي أقل من الحد الأدنى البالغ 30 دينارًا، لذا تكون قيمة `fee` هي 30.00 وقيمة `total` هي 473.39.

  ## قبل الاستدعاء

  <Steps>
    <Step title="احفظ سجلك الخاص أولًا">
      اكتب طلبك — العميل و`transactionId` و`billId` و`amount` و`fee` و`total` والمرجع `ref` الذي أنت على وشك استخدامه — قبل أن يغادر الطلب عمليتك. إذا ضاعت الاستجابة، فذلك السجل هو ما يمكّنك من العثور على الدفعة مجددًا.
    </Step>

    <Step title="أكّد المبلغ مع عميلك">
      يأتي `amount` و`fee` من عملية الاكتشاف. اعرض قيمة `total` التي أنت على وشك خصمها، لا تقديرًا تقريبيًا.
    </Step>

    <Step title="أرسل الدفعة">
      استدعاء واحد، بمرجع `ref` جديد لدى هذا الشريك.
    </Step>

    <Step title="استعلم دوريًا حتى الحالة النهائية">
      `SUCCESS` أو `FAILED` أو `REFUNDED`. تعامل مع `UNKNOWN` على أنها «تابع الاستعلام»، لا على أنها فشل.

      → [الاستعلام الدوري عن الحالة](/ar/bill-payment-guides/4-status-polling)
    </Step>
  </Steps>

  ## الحواجز التي تحميك

  ثلاث قواعد تمنع تحرك المال نفسه مرتين. الثلاث جميعها تُجيب قبل خصم أي مبلغ.

  | الحاجز           | الاستجابة                 | المعنى                                          |
  | ---------------- | ------------------------- | ----------------------------------------------- |
  | مرجع مكرر        | `403 DUPLICATED_REF`      | هذا `ref` يخص بالفعل معاملة نشطة لدى هذا الشريك |
  | مدفوعة مسبقًا    | `409 BILL_ALREADY_PAID`   | هذه الفاتورة سُدِّدت بنجاح بالفعل               |
  | دفعة قيد التنفيذ | `409 PAYMENT_IN_PROGRESS` | دفعة أخرى لهذه الفاتورة لم تنتهِ بعد            |

  <Warning>
    لا واحدة من هذه الثلاث سبب لإعادة المحاولة بمرجع `ref` مختلف. كل منها يعني أن العمل إما أُنجز بالفعل أو أنه قيد التنفيذ بالفعل — ابحث عنه بدلًا من إرساله من جديد.
  </Warning>

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

  <CardGroup cols={2}>
    <Card title="اكتب قبل أن ترسل" icon="database">
      احفظ سجل طلبك، بما فيه `ref`، قبل إرسال الطلب. عندها تصبح الاستجابة الضائعة قابلة للاسترجاع.
    </Card>

    <Card title="مرجع واحد لكل استدعاء" icon="fingerprint">
      استخدم `ref` مختلفًا للاكتشاف وآخر للدفع. يكفي وضع `disc-` و`pay-` قبل معرّف طلبك.
    </Card>

    <Card title="لا تعد الإرسال عند انتهاء المهلة أبدًا" icon="triangle-exclamation">
      اقرأ المعاملة أولًا. انتهاء مهلة الشبكة لا يعني أن الدفعة لم تحدث.
    </Card>

    <Card title="اخصم انطلاقًا من total" icon="calculator">
      اخصم من عميلك قيمة `total` التي أرجعتها واجهة API، لا قيمة حسبتها بنفسك.
    </Card>
  </CardGroup>

  ## Endpoints ذات الصلة

  <CardGroup cols={3}>
    <Card title="اكتشاف الفواتير" icon="magnifying-glass-dollar" href="/ar/api-reference/bill-payment/discover-bills">
      اعثر على ما هو قابل للدفع
    </Card>

    <Card title="الحصول على المعاملة بالمعرّف" icon="id-card" href="/ar/api-reference/bill-payment/check-by-id">
      استعلم دوريًا عن النتيجة
    </Card>

    <Card title="تنزيل الإيصال" icon="file-arrow-down" href="/ar/api-reference/bill-payment/get-receipt">
      إثبات الدفع
    </Card>

    <Card title="الحصول على المعاملة بالمرجع" icon="tag" href="/ar/api-reference/bill-payment/check-by-ref">
      استعد استجابة ضائعة
    </Card>

    <Card title="دفع الفواتير" icon="money-bill-transfer" href="/ar/bill-payment-guides/3-paying-bills">
      الشرح الكامل
    </Card>

    <Card title="الاستعلام الدوري عن الحالة" icon="arrows-rotate" href="/ar/bill-payment-guides/4-status-polling">
      مُستعلِم دوري بجودة الإنتاج
    </Card>
  </CardGroup>
</div>