---
title: Stripe
description: اربط Stripe بـ NexCMP لمدفوعات البطاقات، وApple Pay، وGoogle Pay، وLink، وAlipay — مفاتيح API، وwebhook، وتسجيل النطاق، والدفع التجريبي.
url: https://nexcmp.com/ar/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Stripe

> **المكان في لوحة التحكم:** Finance › Payment channels › Stripe (`/payments/stripe`). المفاتيح والرسوم: Finance › Payment channels › Fees & limits (`/payments/fees`).

## الوظيفة {#what-it-does}

يقبل Stripe مدفوعات البطاقات لشحن المحفظة. وبنفس الحساب يمكنك أيضاً توفير **Apple Pay**، و**Google Pay**، و**Link**، و**Alipay**، والسماح للعملاء بـ **حفظ البطاقة** لـ [الشحن التلقائي](https://nexcmp.com/ar/docs/billing/auto-top-up/). استخدمه القناة الأساسية للعملاء الدوليين.

## المتطلبات {#requirements}

| العنصر | المتطلب |
|---|---|
| حساب Stripe | حساب Stripe قادراً على قبول المدفوعات بـ **USD**. يتم خصم قيمة Alipay بالعملة JPY ويجب تفعيلها من قِبل Stripe لحسابك. |
| المفاتيح | مفتاح سرّي (`sk_live_...` أو `sk_test_...`) ومفتاح قابل للنشر (`pk_live_...` أو `pk_test_...`). النموذج يقبل فقط المفاتيح التي تحمل هذه البادئات. |
| الشبكة | يجب أن تكون لوحتك قابلة للوصول عبر HTTPS من الإنترنت (حيث يستدعي Stripe الـ webhook) ويجب أن تصل إلى `api.stripe.com` على المنفذ 443. |
| النطاق (المحافظ فقط) | يجب أن يخدم النطاق المخصص للعملاء `/.well-known/apple-developer-merchantid-domain-association` — وتقوم NexCMP بذلك نيابة عنك. |
| الاعتمادات | لا يوجد. |

::: info حسابات Stripe المشتركة
تعالج NexCMP فقط أحداث الـ webhook للمدفوعات التي أنشأتها بنفسها، لذا يمكنك استخدام حساب Stripe يخدم تطبيقاً آخر أيضاً.
:::

## تجهيز البنية التحتية {#prepare-the-infrastructure}

على جانب Stripe:

1. سجّل الدخول إلى [Stripe Dashboard](https://dashboard.stripe.com). قم بتشغيل أو إيقاف **Test mode** لتحديد ما إذا كنت تجري تشغيلاً تجريبياً أو تنتقل للإنتاج المباشر. مفاتيح أحد الوضعين لا تعمل أبداً مع الوضع الآخر.
2. افتح **Developers › API keys**. انسخ **Publishable key**، واكشف عن **Secret key** ثم انسخه. حافظ على سرية المفتاح السري.
3. (اختياري) افتح **Settings › Payment methods** وفعّل **Alipay** إذا كنت تريد توفيرها.
4. لا تحتاج إلى **إنشاء** الـ webhook يدوياً — يمكن لـ NexCMP إنشاؤه نيابة عنك (انظر الخطوة 5 أدناه). إذا كنت تفضل القيام بذلك يدوياً، أنشئ نقطة نهاية في **Developers › Webhooks** باستخدام عنوان URL والأحداث المدرجة في [Webhook](#webhook).

## الربط في NexCMP {#connect-in-nexcmp}

1. افتح **Finance › Payment channels › Stripe** (`/payments/stripe`).
2. في بطاقة **API keys**، اختر **Mode** (`live` أو `test`)، والصق **Secret key** و**Publishable key**.
3. انقر على **Save**. تُكتب المفاتيح في ملف تكوين على الخادم لا يمكن قراءته إلا بواسطة حساب خدمة NexCMP. ولا تُرسل أبداً مرة أخرى إلى المتصفح؛ وبعد ذلك تعرض الصفحة آخر 4 أحرف فقط.
4. انقر على **Check**. يعرض مربع الحوار الاتصال، والوضع، والرصيد المتاح والمعلق، ومعرف الحساب، وما إذا كانت عمليات الشخص مفعلة، وما إذا كان الـ webhook موجوداً وما إذا كانت Alipay متاحة. الخط الأحمر يعني أن هذا الجزء بحاجة إلى اهتمام.
5. في بطاقة **Webhook**، انقر على **Create webhook** وأكّد ذلك. تطلب NexCMP من Stripe إنشاء نقطة النهاية مع كل حدث مطلوب وتملأ حقل **Webhook signing secret** (`whsec_...`) تلقائياً. عنوان URL المملوء مسبقاً في الحقل هو `https://<your-domain>/v1/billing/stripe/webhook`، على سبيل المثال `https://cloud.example.com/v1/billing/stripe/webhook`.
6. افتح **Fees & limits** (`/payments/fees`)، واجعل **Card (Stripe)** مفعلاً، واضبط **Stripe fee %** و**Stripe fixed fee (cents)** على تعريفتك الحقيقية وانقر على **Save channels & fees**. راجع [Payment channels](https://nexcmp.com/ar/docs/billing/payment-channels/#switches-and-fees-fees-limits).

![صفحة Stripe مع تعبئة الوضع والمفتاح السري والمفتاح القابل للنشر بقيم تجريبية](https://nexcmp.com/ar/docs/images/billing/stripe-01-keys.webp)


### Webhook {#webhook}

تبقى الراية الحمراء "Missing webhook_secret" ظاهرة حتى يتم حفظ سر التوقيع. وبدونها **لا يتم تسجيل** عمليات شحن المحفظة عبر Stripe، حتى لو تلقى Stripe الأموال.

| العنصر | القيمة |
|---|---|
| URL | `https://<your-domain>/v1/billing/stripe/webhook` |
| الأحداث | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` |
| التوقيع | Stripe `Stripe-Signature` رأس الصفحة، HMAC-SHA256، سماحية 300 ثانية. الطلبات ذات التوقيع غير الصحيح تتلقى HTTP 400. |
| منع التكرار | يتم تخزين كل معرّف حدث مرة واحدة؛ ولن يؤدي التسليم المتكرر أبداً إلى إضافة رصيد مرتين. |

إذا قمت بالتحديث من إصدار قام بتسجيل عدد أقل من الأحداث، فانقر فوق **Create webhook** مرة أخرى — يتم الاحتفاظ نقطة النهاية القديمة، لذا احذفها يدوياً في لوحة تحكم Stripe لاحقاً.

يوضح صفوف **24h events** و**Latest event** في بطاقة Webhook ما إذا كانت Stripe تتصل باللوحة أم لا. يتم سرد الأحداث الفردية في **Payment channels › Gateway events** (`/payments/events`، علامة التبويب Stripe)، حيث يمكن عرض كل حدث (**Payload**) أو إعادة إرساله (**Replay**).

### Apple Pay وGoogle Pay وLink {#apple-pay-google-pay-and-link}

1. في بطاقة **Wallets (Apple Pay · Google Pay · Link) & Alipay**، يتم ملء حقل **Customer app Domain registered with Stripe** مسبقاً باسم مضيف موقعك (على سبيل المثال `cloud.example.com`).
2. انقر على **Register / verify domain** وأكد. تقوم NexCMP بتسجيل النطاق في نطاقات طرق الدفع الخاصة بـ Stripe وتطلب من Stripe التحقق منه.
3. تظهر النتيجة حالة **Apple Pay** و**Google Pay** و**Link**. يظهر Apple Pay فقط عندما تكون الحالة `active`.
4. في **Fees & limits** أبقِ خيار **Apple Pay · Google Pay · Link** مفعلاً.

![بطاقة المحفظة توضح النطاق المسجل وحالات Apple Pay وGoogle Pay وLink](https://nexcmp.com/ar/docs/images/billing/stripe-03-wallets.webp)

::: tip بقاء Apple Pay غير نشط
يتطلب Apple Pay أن يستجيب ملف ارتباط النطاق برمز HTTP 200 على نطاقك العام. إذا وضعت Cloudflare أو وكيل آخر في المقدمة، فلا تقم بحظر `/.well-known/`.
:::

### Alipay {#alipay}

خدمة Alipay اختيارية. قم بتفعيلها في **Stripe Dashboard › Settings › Payment methods**، وانقر على **Check** وانتظر حتى يظهر الحوار أن Alipay متاحة، ثم قم بتشغيل **Alipay (Stripe, JPY display)** في **Fees & limits**. اضبط **Alipay fee %**، و**Alipay fixed fee**، و**¥/USD rate** (50–500)، و**FX spread %** (0–20). قم بتحديث سعر الصرف ¥/USD بانتظام؛ حيث تحذر الصفحة عندما يكون أقدم من 7 أيام.

## التحقق {#verify}

1. في وضع الاختبار، سجّل الدخول إلى البوابة كعميل اختبار، وافتح **Billing**، وانقر على **Deposit**، واختر **Card** وقم بدفع الحد الأدنى باستخدام بطاقة اختبار Stripe `4242 4242 4242 4242` (أي تاريخ مستقبلي، وأي رمز CVC).
2. يرتفع الرصيد في غضون ثوانٍ ويظهر الدفع ضمن **Finance › Billing › Top-ups** بالحالة *Completed*.
3. افتح **Payment channels › Gateway events › Stripe**: يجب أن ترى `checkout.session.completed` أو `payment_intent.succeeded` مع وقت تمت معالجته.
4. بالعودة إلى صفحة Stripe، يكون حقل **24h events** أعلى من 0.

قبل الإطلاق الفعلي، قم بتحويل **Mode** إلى `live`، والصق مفاتيح التشغيل الفعلي وانقر على **Create webhook** مرة أخرى (فإن ويب هوك وضعي الاختبار والتشغيل الفعلي منفصلان).

## الحدود والملاحظات {#limits-notes}

- **المبالغ والعملات.** المحافظ بالدولار الأمريكي. تُخصم مدفوعات البطاقات والمحافظ والروابط بالدولار الأمريكي؛ بينما يُعرض Alipay للعميل بالين الياباني ويُحوَّل حسب سعرك.
- **الرسوم.** لا يتم قراءة رسوم Stripe الفعلية تلقائياً؛ نسبة الرسوم التي تعينها تحدد ما يراه العميل وما يُضاف إلى المحافظ. اختر **Customer pays top-up fee** ضمن *Fees & limits* لتحميل الرسوم إضافياً.
- **المرتجعات البطاقة.** عند تحديد العميل خيار *Save card for auto top-up*، تُحفظ البطاقة في Stripe وليس على خادرك. راجع [Saved payment methods](https://nexcmp.com/ar/docs/billing/saved-payment-methods/).
- **الاستردادات.** الاسترداد إلى البطاقة هو عملية من خطوتين: ينشئ المسؤول طلب استرداد لدفعة مكتملة (**Finance › Billing › Top-ups**، إجراء الاسترداد على الدفعة) ثم يوافق عليه ضمن **Finance › Payouts › Card refunds** (`/billing/payouts`). استردادات Alipay غير متزامنة؛ والفاشلة منها (`refund.failed`) تعيد المبلغ المحتجز إلى المحافظ.
- **النزاعات.** في حالة `charge.dispute.created` NexCMP، يقوم النظام بحظر حساب العميل، وإيقاف خدماته مدفوعة الأتاوة مسبقاً (دون حذف أي شيء) وإرسال تنبيه للمسؤول. إذا فزت بالنزاع (`charge.dispute.closed`)، يُعاد اعتماد المبلغ في المحافظ.
- **المدفوعات المعلقة.** إذا لم يصل طلب Webhook أبدًا، يتحقق NexCMP من المدفوعات التي ظلت معلقة لأكثر من 10 دقائق مقابل Stripe من تلقاء نفسه ويقوم بإتمامها. يتم تجاهل المدفوعات الأقدم من 7 أيام.
- يمكن لـ **Resellers** ربط حساب Stripe الخاص بهم (webhook `https://<their-domain>/v1/billing/stripe/webhook/r/<id>`)؛ انظر [Resellers](https://nexcmp.com/ar/docs/customers/resellers/).

## استكشاف الأخطاء وإصلاحها {#troubleshooting}

| العَرَض | السبب | الحل |
|---|---|---|
| "يجب أن تبدأ المفتاح السري بـ sk_live_/sk_test_" | تم لصق مفتاح خاطئ | الصق المفتاح السري من **Developers › API keys**. |
| "المفتاح السري لا يتطابق مع وضع البث المباشر/الاختبار" | وضع التشغيل والمفتاح غير متطابقين | اجعل **Mode** يطابق بادئة المفتاح. |
| "يجب أن يبدأ المفتاح القابل للنشر بـ pk_" | مفتاح خاطئ | استخدم المفتاح القابل للنشر. |
| يقول الفحص إن الاتصال فشل | مفتاح خاطئ، أو تم إلغاء المفتاح، أو لا يمكن للخادم الوصول إلى `api.stripe.com` | أعد لصق المفتاح؛ واختبره باستخدام `curl -I https://api.stripe.com` من الخادم. |
| لافتة حمراء "Missing webhook_secret" | لم يتم حفظ سر التوقيع | انقر فوق **Create webhook** أو الصق سر `whsec_...` من لوحة تحكم Stripe وانقر فوق **Save**. |
| تم خصم الأموال ولكن الرصيد لم يتغير | لم يتم تسليم Webhook أو فشل التوقيع | تحقق من أن عنوان URL ينتهي بـ `/v1/billing/stripe/webhook`، وأن السر يطابق نقطة النهاية، وأعد تشغيل الحدث في **Gateway events**. في Stripe، افتح نقطة النهاية وانظر في محاولات التسليم (HTTP 400 يعني وجود سر توقيع خاطئ). |
| فشل "Create webhook" | عنوان URL ليس HTTPS أو لا يمكن الوصول إليه | استخدم نطاقك العام `https://`. |
| حالة Apple Pay غير نشطة | النطاق غير مصادق عليه | انقر فوق **Register / verify domain** مرة أخرى بعد أن يستجيب ملف ربط النطاق برمز 200. |
| Alipay غير متوفر في مربع حوار التحقق | غير مفعل في Stripe | قم بتفعيله في لوحة تحكم Stripe، ثم انقر فوق **Check**. |
| لا يرى العميل نموذج البطاقة | **Card (Stripe)** معطل أو لا يوجد مفتاح سري | قم بتفعيله في **Fees & limits** واحفظ المفاتيح. |