التحويل البنكي (فيتنام)

أين في لوحة المسؤول: Finance › Payment channels › VN bank transfer (/payments/bank). سعر الصرف: Finance › Payment channels › Exchange rates (/payments/fx).

الوظيفة

يتيح للعملاء شحن محفظة الدولار الأمريكي (USD) عبر تحويل بنكي عادي بالدونغ الفيتنامي. يعرض NexCMP رمز VietQR وتفاصيل الحساب ورمز تحويل (transfer memo) فريداً؛ يراقب Sepay حسابك البنكي ويستدعي خطاف ويب (webhook) عند وصول الأموال، ليقوم NexCMP بعد ذلك بتقييد المبلغ في المحفظة. استخدم هذه الميزة إذا كنت تبيع للعملاء في فيتنام.

يُعرض فقط في الواجهة الفيتنامية

لا يُعرض خيار البنك الفيتنامي للعميل إلا عندما يتم عرض البوابة باللغة Vietnamese. فالعملاء الذين يستخدمون أي لغة أخرى لن يروه أبداً.

المتطلبات

العنصر	المتطلب
الحساب البنكي	حساب بنكي فيتنامي (أو حساب افتراضي من Sepay، VA) متصل بحساب Sepay على my.sepay.vn.
Sepay	حساب Sepay مع تفعيل تكامل خطاف الويب (webhook).
سعر الصرف	يجب أن يتوفر سعر صرف بين الدولار الأمريكي والدونغ الفيتنامي: قم بتحديثه أولاً ضمن Exchange rates. بدون سعر الصرف، ستستجيب القناة بـ fx_unavailable ولن يتمكن العملاء من بدء عملية التحويل.
الشبكة	يجب أن تكون لوحة التحكم الخاصة بك قابلة للوصول عبر بروتوكول HTTPS لكي يتمكن Sepay من استدعاء https://<your-domain>/v1/billing/sepay/webhook.
الاعتمادات	العملة أسعار الصرف.

تجهيز البنية التحتية

على جانب Sepay:

1. في موقع my.sepay.vn قم بربط حسابك البنكي (أو أنشئ حساباً افتراضياً VA) وتأكد من ظهور المعاملات.
2. حدد بادئة الرمز (memo prefix) — من 2 إلى 5 أحرف لاتينية كبيرة، على سبيل المثال PAY. ينشئ NexCMP الرمز بحيث يتكون من البادئة متبوعة بـ 8 أرقام عشوائية (على سبيل المثال PAY48210937). يجب ألا تحتوي البادئة على ORD، ويجب عدم استخدامها من قبل أي نظام آخر يتلقى أموالاً في نفس الحساب.
3. إذا كان حساب Sepay الخاص بك يستخدم هنية رمز الدفع (payment code structure)، قم بتسجيل نفس البادئة هناك لكي يتعرف Sepay على الرمز.
4. أنشئ خطاف الويب (webhook) لاحقاً، بعد أن تمنحك صفحة NexCMP عنوان URL والمفتاح (الخطوة 7 أدناه).

الربط في NexCMP

1. افتح Finance › Payment channels › Exchange rates وانقر على Update exchange rates إذا لم يتم تخزين أي سعر صرف.

2. افتح Finance › Payment channels › VN bank transfer (/payments/bank).

3. في قسم Receiving account املأ ما يلي:

   الحقل	مثال	القاعدة
   البنك	VCB Vietcombank	اختر من القائمة؛ سيتم ملء رمز BIN تلقائياً.
   رقم الحساب	0123456789	4–24 رقماً أو حرفاً لاتينياً كبيراً.
   الحساب الافتراضي (VA — اختياري)		إذا تم تحديده، يقوم العملاء بالتحويل إلى الحساب الافتراضي ويظهر ذلك في رمز الاستجابة السريعة (QR).
   اسم صاحب الحساب	NGUYEN VAN A	بدون علامات تشكيل، أحرف لاتينية كبيرة UPPERCASE، من 2 إلى 60 حرفاً.
   بادئة رمز التحويل	PAY	2–5 أحرف لاتينية كبيرة، بدون ORD.

4. في قسم Webhook authentication اختر Auth method: HMAC-SHA256 (موصى به) أو API key، وأدخل Webhook key / HMAC secret (من 8 إلى 200 حرف). اختياري، أدخل userapi token من Sepay؛ فهو يُستخدم فقط لتسوية التحويلات التي ضاع خطاف الويب الخاص بها.

5. في قسم Channel & limits اضبط الحدود (القيم الافتراضية بين قوسين): Min / order (10,000 VND)، Max / order (200,000,000 VND)، Order expiry (120 دقيقة، 15–1440)، Max pending orders / account (3، 1–10)، Reconcile every (10 دقائق)، واختيارياً، Allowed webhook IPs (مفصولة بفواصل؛ الفراغ يعني تسجيل عنوان IP فقط).

6. انقر فوق Save. تختفي لافتة التنبيه الحمراء "Sepay not configured" بمجرد أن تصبح بيانات الحساب والاسم والبادئة والمفتاح صحيحة.

7. انسخ Webhook URL to paste into my.sepay.vn (تظهر على شكل https://<your-domain>/v1/billing/sepay/webhook) باستخدام Copy. في Sepay، افتح تكامل webhook، والصق عنوان URL، واختر نفس نوع المصادقة والمفتاح، وفعّل حدث "money in".

8. انقر على Test connection. ثم قم بتفعيل Enable Sepay for clients (main site) وانقر على Save.

أمان الويب هوك

الطريقة	ما يجب أن يرسله Sepay
HMAC-SHA256	الترويسة X-SePay-Signature: sha256=<hex>، المحسوبة عبر "<X-SePay-Timestamp>.<raw body>"؛ قد تختلف الطابع الزمني بما لا يتجاوز 300 ثانية.
مفتاح API	الترويسة Authorization: Apikey <key>.

يتم التحقق من الترويسات فقط (وليس المتن أو نص الاستعلام أبداً) وتكون المقارنة في وقت ثابت. يتم استخدام الواردات فقط (transferType = in) للحساب أو الحساب الافتراضي (VA) المُكوَّن لديك. يتم تخزين كل معاملة Sepay مرة واحدة، لذا فإن طلب الويب هوك المُعاد لا يُقيد الرصيد مرتين أبداً. يجيب NexCMP بـ 200 {"success":true} حتى عند تجاهل المعاملة عمداً، ويُرجع HTTP 5xx للأخطاء المؤقتة فقط لكي يقوم Sepay بإعادة المحاولة.

كيف يدفع العميل

1. في Billing › Deposit (الواجهة الفيتنامية) يختار العميل خيار التحويل المصرفي الفيتنامي والمبلغ، ثم ينقر على زر إنشاء التحويل.
2. يقوم NexCMP بتحويل مبلغ الدولار الأمريكي بالسعر المخزّن (بما في ذلك الهامش وخطوة التقريب التي حددتها في Exchange rates) ويقرب مبلغ الدونغ الفيتنامي للأعلى إلى خطوة التقريب.
3. يرى العميل رمز الاستجابة السريعة (VietQR، يتم توليده محلياً) متضمناً رقم الحساب، والبنك، والمبلغ، وبيان التحويل.
4. بعد التحويل، يستدعي Sepay الويب هوك، ويقوم NexCMP بتقييد floor(VND received × 100 / rate) سنتاً. يتم تثبيت سعر الصرف عند إنشاء الطلب؛ وإذا وصلت الأموال بعد انتهاء صلاحية الطلب، يتم استخدام السعر الأعلى بين السعر المُثبّت والسعر الحالي.
5. تنتهي صلاحية الطلبات بعد Order expiry؛ وتعمل عملية المطابقة كل Reconcile every دقيقة كشبكة أمان (تتطلب رمز userapi).

التحقق

1. أنشئ طلباً تجريبياً كعميل على الواجهة الفيتنامية. وتأكد من أن المبلغ، والحساب، وبيان التحويل صحيحة.
2. قم بتحويل أصغر مبلغ مسموح به مع بيان التحويل الدقيق.
3. خلال دقيقة، تُظهر البوابة الإيداع كمكتمل ويرتفع رصيد المحفظة؛ وتُظهر بطاقة State في صفحة البنك وقت آخر ويب هوك.
4. افتح Finance › Billing › Top-ups وتأكد من إدراج الدفعة مع مبلغ الدونغ الفيتنامي المستلم.

الحدود والملاحظات

• الحد الأدنى. الحد الأدنى بالدونغ الفيتنامي الذي يراه العميل هو الأكبر بين Min / order والقيمة بالدونغ الفيتنامي لـ minimum top-up.
• الطلبات المعلقة. يمكن للعميل امتلاك Max pending orders / account من الطلبات المفتوحة كحد أقصى (الافتراضي 3).
• نفس بيان التحويل مرتين. إجراء تحويل مرتين بنفس بيان التحويل ينشئ دفعة ثانية مكتملة بالسعر الحالي.
• لا يوجد استرداد تلقائي إلى الحساب المصرفي.
• الرسوم. لا تحتوي القناة على بند رسوم ثابتة في Fees & limits؛ ويعتبر هامش السعر هو التعديل الوحيد.
• يمكن لـ Resellers تكوين حساباتهم الخاصة؛ وينتهي رابط الويب هوك الخاص بهم بـ /v1/billing/sepay/webhook/r/<id>.

التحويلات غير المطابقة

الأموال التي وصلت إلى الحساب ولكنها لا تحمل بيان تحويل صالح تظهر في Unmatched transactions في أسفل الصفحة (قم بالتصفية باستخدام All channel owners أو Master). تحقق من مرجع البنك مع العميل، ثم انقر على Assign وحدد الحساب. يتم إيداع المبلغ في المحفظة بالسعر الحالي.

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

العَرَض	السبب	الحل
لافتة "Sepay not configured"	البنك، الحساب، اسم صاحب الحساب، البادئة، أو المفتاح مفقود أو غير صالح	أكمل بطاقتي Receiving account و Webhook authentication.
لافتة "USD/VND rate blocked" (fx_unavailable)	لا يوجد سعر صرف مخزّن	من Exchange rates › Update exchange rates.
prefix: 2–5 capital letters, no ORD	بادئة غير صالحة	استخدم 2–5 حروف كبيرة بدون ORD.
خطأ account_name	علامات تشكيل أو حروف صغيرة	استخدم حروفاً كبيرة بدون علامات تشكيل، أو أرقاماً، أو مسافات، أو نقاط، أو شرطات.
webhook_secret: 8–200 characters	المفتاح قصير جداً	استخدم 8 أحرف قابلة للطباعة على الأقل.
العميل لا يرى الخيار	ليست بالواجهة الفيتنامية، أو الخيار معطل، أو لا توجد صسرة	تحقق من اللغة والمفتاح والصسرة.
دفع العميل ولكن لم يتم إيداع أي شيء	لم يُستلم الويب هوك، أو تغيرت المذكرة، أو المبلغ خاطئ	تحقق من سجل الويب هوك الخاص بـ Sepay؛ ستكون النقلة ضمن Unmatched transactions إذا كانت المذكرة خاطئة.
يُرجع الويب هوك 401 أو 403	عدم تطابق طريقة المصادقة أو المفتاح	استخدم نفس الطريقة والمفتاح في Sepay وNexCMP.
العميل يرى "Too many pending requests"	تم الوصول إلى حد الطلبات المعلقة	ينتهون أو ينتظرون انتهاء الصلاحية.