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

# الدفع عبر الويب

> بِع عناصر المتجر بمال حقيقي على Windows وmacOS وLinux وWebGL عبر Stripe أو Tap أو Moyasar.

في البناء الذي لا متجر هاتف فيه (Windows وmacOS وLinux وWebGL)، يُدفع ثمن العنصر بالمال الحقيقي عبر بوابة
الدفع الخاصة بك: Stripe أو Tap أو Moyasar. يدفع اللاعب في صفحة البوابة داخل المتصفح، ويذهب المال مباشرة إلى
حسابك لدى البوابة. وتستدعي لعبتك الدالة نفسها التي تستدعيها لأي عنصر: `Shop.PurchaseAsync(item.Id)`.

```
Player taps Buy ──▶ checkout opens ──▶ player pays on the gateway's page ──▶ gateway tells Flock ──▶ item delivered
```

لا يُسلَّم شيء حتى تؤكد البوابة الدفع. وتُغلَق عملية الدفع التي لم تُدفع بعد ساعة، ولا يُحتسب شيء.

> [!NOTE]
>
> يحتاج الدفع عبر صفحة ويب إلى حزمة تطوير Flock لـ Unity بالإصدار 1.98.0 أو أحدث، ولا يحتاج إلى أي حزمة أخرى.
> وعلى Android وiOS تدفع الاستدعاءات نفسها عبر متجر الهاتف بدلًا منه: راجع
> [الشراء داخل التطبيق](https://docs.qwacks.com/ar/guides/real-money-purchases.md).

**1. اربط بوابتك بـ Flock**

افتح **Monetization > Payments** في لوحة تحكم Flock واربط البوابة التي تبيع عبرها بمفاتيحك الخاصة. تبقى
المفاتيح على خادم Flock ولا تصل إلى جهاز اللاعب أبدًا. استخدم مفاتيح **الاختبار** في البوابة أثناء التطوير:
تُعلَّم مشترياتها على أنها اختبار وتُستبعد من إيراداتك.

> [tab] Stripe
>
> | الحقل | ما تُدخله |
> | - | - |
> | Secret key | المفتاح السري لحسابك في Stripe (`sk_test_…` أثناء الاختبار) |
> | Webhook secret | سرّ التوقيع للـ webhook أدناه (`whsec_…`) |
>
> في Stripe، تحت **Developers > Webhooks**، أضف عنوانًا هو
> `https://api-flock.qwacks.com/v1/shop/webhook/<your game id>/stripe` مع هذه الأحداث:
> `checkout.session.completed` و`checkout.session.expired` و`payment_intent.payment_failed`
> و`charge.refunded` و`charge.dispute.closed`، ثم الصق سرّ توقيعه في Flock.
> ومن دونه يُسلَّم الدفع رغم ذلك، خلال نحو 15 دقيقة بدل أن يُسلَّم فورًا.
>
> يحتسب Stripe الدفع بعملة العنصر، ويرفض سعرًا أقل من أدنى مبلغ يحتسبه بعملة حسابك (لحساب يسوّي بالدرهم:
> 2.00 درهم).

> [tab] Tap Payments
>
> | الحقل | ما تُدخله |
> | - | - |
> | Secret key | المفتاح السري لحسابك في Tap (`sk_test_…` أثناء الاختبار) |
> | Publishable key | المفتاح المنشور لحسابك في Tap |
>
> يعطي Flock بوابة Tap عنوان الإشعار لكل دفعة، فلا شيء عليك تسجيله. ويحتسب Tap الدفع بعملة العنصر نفسها.

> [tab] Moyasar
>
> | الحقل | ما تُدخله |
> | - | - |
> | Secret key | المفتاح السري لحسابك في Moyasar (`sk_test_…` أثناء الاختبار) |
> | Publishable key | المفتاح المنشور لحسابك في Moyasar |
> | Webhook secret | الرمز السري للـ webhook أدناه |
>
> في لوحة تحكم Moyasar، أضف webhook على العنوان
> `https://api-flock.qwacks.com/v1/shop/webhook/<your game id>/moyasar`، واختر رمزًا سريًا، والصق الرمز
> نفسه في Flock. وإن رُفضت بطاقة اللاعب فله أن يجرّب أخرى في الصفحة نفسها: يبقى الشراء مفتوحًا حتى يُدفع أو
> تنتهي ساعته.
>
> لا يحتسب Moyasar إلا بالريال السعودي: يُحوَّل السعر بالدولار الأمريكي بسعر صرف Flock، وتُرفض أي عملة
> أخرى.

> [!WARNING]
>
> الاسترداد أو النزاع الذي يُجرى في لوحة تحكم Stripe أو Moyasar نفسها لا يصل إلى Flock بعد: يبقى الشراء مدفوعًا،
> ويحتفظ اللاعب بما منحه.

اربط بوابة واحدة، أو سمِّ البوابة المستخدمة في اللعبة حين تكون أكثر من بوابة مفعّلة (أدناه).

**2. سعّر العناصر بالمال الحقيقي**

سعّر العنصر بإحدى **Real Currencies** في إعداد العملات، كما تفعل لعنصر المتجر. والسعر هو ما تحتسبه البوابة:
799 بالريال تعني 7.99 ريال. ولا يحتاج العنصر إلى معرّف منتج في متجر للدفع عبر صفحة ويب.

**3. اربطه في لعبتك**

اربطه مرة واحدة بعد بدء حزمة التطوير. وفي بناءات Windows وmacOS وLinux وWebGL يربط `FlockStore` الدفع عبر
صفحة ويب تلقائيًا:

```csharp theme={null}
FlockStore store;

async void Start()
{
    store = await FlockStore.ConnectAsync(new FlockStoreOptions
    {
        // Your own pages, where the player's browser lands after paying or giving up.
        ReturnUrl = "https://yourgame.example/paid",
        CancelUrl = "https://yourgame.example/cancelled"
    });

    // Every paid checkout, the ones PurchaseAsync answers included: refresh what the screen shows here.
    store.PurchaseCompleted += (item, result) => RefreshTheShop();
}
```

| الخيار | ما يفعله |
| - | - |
| `PaymentProvider` | البوابة المستخدمة حين تكون أكثر من بوابة مفعّلة: `PaymentProviders.Stripe` أو `Tap` أو `Moyasar`. وإن تُرك فارغًا استُخدمت البوابة المفعّلة الوحيدة للعبة. ويضع بناء Mac App Store هنا `PaymentProviders.AppleAppStore` ليبيع عبر App Store بدلًا من ذلك |
| `ReturnUrl` و`CancelUrl` | حيث يصل المتصفح بعد الدفع وبعد التراجع |
| `OpenPaymentPage` | تفتح أنت صفحة الدفع بدلًا من فتحها في علامة تبويب جديدة (راجع WebGL أدناه) |
| `CheckEvery` | كم مرة تُقرأ عملية الدفع المنتظرة؛ كل 3 ثوانٍ افتراضيًا |

تكون قيمة `store.IsWebCheckout` صحيحة في هذه البناءات، ويعطي `store.GetPrice(item.Id).Text` سعر العنصر نفسه
لتعرضه؛ ولا تكون قيمة `GetPrice` هي `null` أبدًا في الدفع عبر صفحة ويب. ويُكتب الرقم بتنسيق جهاز اللاعب، فما
`SAR 7.99` إلا مثال على شكله.

## الشراء

```csharp theme={null}
try
{
    PurchaseResult bought = await FlockClient.Instance.Shop.PurchaseAsync(item.Id);
    // Paid: bought.Granted lists what it delivered. Read the wallet and inventory again.
}
catch (FlockStoreException e) when (e.Reason == FlockStoreFailureReasons.Expired)
{
    // Left unpaid for the hour a checkout stays open: nothing was charged.
}
catch (FlockStoreException e)
{
    // PaymentDeclined: the gateway declined the payment or the player gave up. Nothing was charged.
}
```

يفتح `PurchaseAsync` عملية دفع، ثم صفحتها، وينتظر حتى تُدفع أو تُرفض أو تنتهي مهلتها. ولا تُفتح عملية دفع
مرتين أبدًا: إن لم يصل رد، فشل الاستدعاء بدل أن يحاول مجددًا.

* **إذا غادر اللاعب اللعبة** قبل الدفع: تبقى عملية الدفع مفتوحة على الخادم. ويُعثر عليها مجددًا عند تسجيل
  دخول اللاعب التالي، ويُبلغ عنها `PurchaseCompleted` حين تُدفع.
* **إذا دُفعت واللعبة مغلقة:** يسلّمها Flock رغم ذلك، وتظهر في المحفظة والمخزون، لكن لا يُطلق
  `PurchaseCompleted` لها.
* **إلغاء الاستدعاء** (برمز الإلغاء الخاص به) يوقف الانتظار لا عملية الدفع: فحين تُدفع يُبلغ عنها
  `PurchaseCompleted`.
* **تسجيل الخروج** ينهي الانتظار، ويُعثر على عملية الدفع مجددًا عند تسجيل دخول ذلك اللاعب التالي.

## WebGL

لا يفتح المتصفح علامة تبويب جديدة إلا لوقت قصير بعد نقرة اللاعب. وتُفتح صفحة الدفع حالما تجهز عملية الدفع،
بعد نحو ثانية ونصف من النقرة في اختباراتنا، وقد فتحها متصفح مبني على Chromium (Chrome وEdge). ويسمح Firefox
بوقت مماثل، أما Safari فيسمح بنحو ثانية واحدة، فقد يحجب علامة التبويب.

ولـ Safari، اعرض زر **ادفع الآن** خاصًا بك يفتح الصفحة فور النقر عليه:

```csharp theme={null}
string paymentPage;

store = await FlockStore.ConnectAsync(new FlockStoreOptions
{
    OpenPaymentPage = url => { paymentPage = url; ShowPayNowButton(); }
});

// The Pay now button's click:
void OnPayNow() => Application.OpenURL(paymentPage);
```

## اختبر قبل الإطلاق

اربط مفاتيح الاختبار في البوابة، ثم اشترِ بإحدى بطاقات الاختبار لديها (بطاقة Stripe
`4242 4242 4242 4242` مع أي تاريخ مستقبلي وأي رمز تحقق؛ وبطاقات Tap وMoyasar في وثائقهما). تُسلَّم عملية
الشراء التجريبية كأي عملية أخرى، وتُعلَّم على أنها اختبار، وتُستبعد من إيراداتك. واترك عملية دفع دون دفع لترى
أنها تُغلق بحالة `Expired` بعد الساعة.

## حين يفشل شيء

تقول `Message` لكل فشل ما الذي حدث، وكيف تصلحه في سطر `Fix:`.

| الرمز | ما حدث | ما تفعله |
| - | - | - |
| `ShopRealCurrencySettlementUnavailable` | لا بوابة ويب مربوطة أو مفعّلة للعبة | اربط واحدة تحت **Monetization > Payments**، أو فعّل **Active** من جديد |
| `ShopWebhookProviderUnknown` | أكثر من بوابة مفعّلة ولم تسمِّ اللعبة أيًّا منها، أو سمّت متجرًا | اضبط `FlockStoreOptions.PaymentProvider`، أو أوقف البقية مؤقتًا |
| `PaymentProviderProviderNotFound` | البوابة التي سمّيتها غير مربوطة أو موقوفة مؤقتًا | اربطها، أو فعّل **Active** من جديد |
| `PaymentProviderCheckoutFailed` | لم تفتح البوابة عملية الدفع | اقرأ سبب البوابة: مفاتيح ترفضها، أو عملة لا تقبلها، أو سعر أقل من أدنى مبلغ تحتسبه |
| `ShopNotARealCurrencyItem` | العنصر مسعّر بعملة اللعبة | يُشترى من المحفظة؛ ويفعل `PurchaseAsync` ذلك تلقائيًا |
| `ShopItemNotForSale` | العنصر أو متجره متوقف | اقرأ المتجر مجددًا: لم يعد مدرجًا |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.