كيف تعمل مدفوعات واجهة برمجة التطبيقات لمقدمي الخدمة

واجهة برمجة التطبيقات للدفع هي عقد بين طلبك ومزود الخدمة الذي يحول «إنشاء الدفع» و «تأكيد» 3DS, «أموال الإرجاع» و «الدفع للعميل» و «الحصول على الحالة» إلى مكالمات موثوقة وقابلة للتكرار. تحت غطاء المحرك توجد عشرات القواعد: الترميز، والخصوصية، وخطافات الويب، ومكافحة الاحتيال، وقوائم الانتظار، وجيش تحرير السودان، والتدقيق. فيما يلي خريطة عملية لكيفية عمل هذا بالنسبة لمعظم مقدمي الخدمة.

النموذج الأساسي: ما هي الكيانات التي تكاد تكون دائمًا

الدفع/الرسم - محاولة الشطب (الإذن + الاستيلاء أو الشراء الفوري).

طريقة الدفع - البطاقة (PAN/token)، الحساب المصرفي/الاسم المستعار، المحفظة، الطريقة المحلية.

العميل - العميل/الكيان الدافع (اختياري أحيانا).

المدفوعات/التحويلات - المدفوعات الصادرة للعميل/التاجر.

رد/عكس - العودة إلى الدفعة الأصلية (الحلقة المغلقة).

حدث Webhook - إشعار الحالة غير المتزامنة.

Dispute/Chargeback - conflict on pay network (for cards).

الطلب/الفاتورة - سياق العمل حول الدفع.

التوثيق والأمن

مفاتيح واجهة برمجة التطبيقات/OAuth 2. 0/mTLS - للخادم إلى الخادم.

رموز العملاء هي رموز يمكن التخلص منها في المقدمة (حتى لا تتألق الأسرار).

ترميز البطاقة - يذهب PAN إلى المزود ؛ أنت فقط تخزن الرمز.

PCI DSS - إذا رأيت PAN، فأنت في منطقة PCI ؛ ومن الأفضل تجنب واستخدام الحقول المستضيفة/القروض الخاصة.

خطوط الويب الخاصة بتوقيع HMAC - التحقق من أن الحدث جاء من المزود.

بنية المنطقة المزدوجة - الجبهة العامة (JS/SDK) والخلفية الخاصة (المفاتيح، منطق المخاطر).

الفراغ والطوابير والاتساق

Idempotency-Key in header: تكرار الطلب (مع مهلة) لا يخلق نسخة مكررة.

Outbox/Saga معك: تم الاتفاق على «إرسال دفعة → الكتابة إلى دفتر الأستاذ → انتظار خطاف الويب».

Retrai مع التراجع - فقط للأخطاء المؤقتة. المصفوفة القابلة للإعادة/غير القابلة للإعادة مطلوبة.

نقاط النهاية النموذجية (المخططات والتدفق)

1) البطاقات (Visa/Mastercard، إلخ)

البريد/المدفوعات - إنشاء دفعة («المبلغ»، «العملة»، «الدفع _ الطريقة _ الرمزية»، «التقاط» = خطأ/صحيح).

POST/payments/{ id }/تأكيد - шаг 3-D Secure 2 (نتيجة التحدي/إعادة التوجيه).

POST/payments/{ id }/capture - التقاط بعد الإذن (جزئي/كامل).

PUST/payments/{ id }/return - return (in parts, reque to the original amount).

GET/payments/{ id} - статус (مصرح به، تم التقاطه، فشل، requires_action).

3-D Secure/SCA: سيعيد المزود "requires _ action" + "client _ secret'/URL للتحدي. بعد تأكيد العميل، ستعيد الجبهة النتيجة إلى ظهرك → تسحب '/تؤكد '.

2) A2A/الخدمات المصرفية المفتوحة (الدفع حسب البنك)

POST/payments → response from «redirect _ url» to customer's bank.

العميل مصرح به من قبل البنك → مدفوعات الويب. نجحت/فشلت ".

GET/payments/{ id} - الوضع النهائي (غالبًا ما يكون غير متزامن فقط).

3) الأساليب المحلية (PIX و PayID و FPX و iDEAL وما إلى ذلك)

POST/payments → get 'qr _ code '/' deeplink '/' copy _ code'.

أظهر للمستخدم، انتظر خطاف الويب حول التسجيل.

تعتبر مهلات الرمز و TTLs جزءًا من العقد.

4) المدفوعات

البريد/المدفوعات («المبلغ»، «العملة»، «الوجهة _ الرمزية» или «البطاقة _ الرمزية »/« البنك _ الاسم المستعار»).

GET/payouts/{ id} - статусы («اصطف»، «أرسل»، «دفع»، «فشل»).

الدفع لخطابات الويب. المدفوعة/الفاشلة هي مصدر الحقيقة.

الحلقة المغلقة: يفضل الدفع للمصدر (العكس) قبل البدائل.

خطافات الويب: «مصدر الحقيقة»

الأحداث: الدفع. معلقة/مأذون بها/مسجلة/فاشلة "، الدفع. requires_action'، 'استرداد. نجح «،» دفع تعويضات. دفعت '،' نزاع. ، إلخ.

التسليم: مع التراجعات الموقعة من قبل HMAC، غالبًا «مرة واحدة على الأقل» → إبقاء المعالج خفيًا.

أفضل الممارسات: معالجة الويب → تحديث دفتر الأستاذ → الرد 2xx. أي منطق تجاري بعد ذلك غير متزامن.

معالجة الأخطاء والحالة

رموز HTTP: نجاح «2xx» ؛ خطأ العميل «4xx» (التحقق من الصحة، الغش/الفشل المصرفي، الرمز غير الصحيح) ؛ «5xx» - المزود.

Причины отказов: «أموال غير كافية»، «لا تشرف»، «بطاقة مسروقة»، «حدود _ تجاوزت»، «مخاطر _ رفض»، «بنك _ غير متاح».

نوافذ إعادة: لـ 3DS - لا يمكنك التراجع إلى ما لا نهاية ؛ بالنسبة لـ A2A - إعادة توجيه/رمز TTLs صالحة ؛ للمدفوعات - التراجع.

مضاد الروم والمخاطر

بصمات الجهاز والبيانات السلوكية - عبر JS/SDK الخاص بالمزود أو طبقتك الخاصة.

القوائم: مخاطر BIN، قوائم الأساليب السوداء/البيضاء/ASN/البلدان.

البوابات القابلة للتعديل: حدود على الأدوات الجديدة، التبريد، السرعة، فحص عتبة RG/AML.

السياسات: «تمرير/تصعيد/تعليق/كتلة» بناءً على تسجيل + قواعد.

ميزات على القضبان

البطاقات: الإذن مقابل المقاصة (يمكن تحويل المبلغ)، 3DS2، العوائد على المعاملة الأصلية، النزاعات/استرداد التكاليف.

A2A/Open الأعمال المصرفية: إعادة التوجيه/تدفق الموافقة، ارتفاع حبوب منع الحمل، انخفاض التكلفة ؛ كل شيء غير متزامن ويعتمد بشكل كبير على البنك.

سريع محلي: QR/alias، خطاف ويب فوري، TTL وتجميع صارم.

OCT/Push-to-Card (مدفوعات البطاقة): تحتاج إلى رموز بطاقة، ودعم Fast Funds من المصدر، بدون 3DS.

التحرير والتوافق

إصدارات واجهة برمجة التطبيقات: «/v1 »،« إصدارات البيانات »في الرأس أو phicheflags.

التغييرات المتوافقة مع الخلف: الحقول غير المدمرة فقط.

Deprections: الجدول الزمني لسحب النسخ القديمة، وأدلة الهجرة، وكتابات الويب المكررة أثناء الهجرة.

إمكانية الرصد وجيش تحرير السودان

المقاييس: p95 وقت الإذن/الدفع، سعر الموافقة حسب BIN/bank/method، حصة retrays، webooks-lag.

Logs: corrence by 'request _ id', 'idempotency _ key', 'payment _ id'.

التنبيهات: زيادة في الرفض لبنك/بلد معين، وزيادة في المهلات، وتكرار الأحداث.

الاجتياح والتمويل

دفتر الأستاذ: مدخل مزدوج، سجلات غير قابلة للتغيير، حالات «مصرح بها/مسجلة/مستردة».

تجميع ثلاثي الجوانب: دفتر الأستاذ الخاص بك ↔ خطافات الويب ↔ تقارير المزود/المصرف.

المراجع: احتفظ بـ «مزود _ مرجع»، «شبكة _ مرجع»، «مدفوعات _ مرجع» - وهذا يوفر الدعم.

صندوق الرمل وإصدار الشهادات والإنتاج

Sandbox: اختبار الرموز/البطاقات/البنوك، محاكاة 3DS/redirects، «الأزرار» لحالات خطاف الويب.

حالات الاختبار: النجاح/الفشل، تحدي 3DS، مهلة المزود، شبكة ويب مكررة، التقاط/استرداد جزئي، إعادة توجيه الإلغاء، فشل الدفع.

Go-live: مفاتيح الدفع، نطاقات الشباك، IP-allowist، تمكين مكافحة الاحتيال، وضع حدود وتنبيهات.

أمثلة مصغرة (تخطيطية)

إنشاء الدفع (بطاقة)


البريد/v1/المدفوعات
{
"المبلغ": 9232، "العملة": "EUR"، "payment_method_token": "pm_tok_123," "capture": true, "metadata": {"order _ id": "ORD-1001"}
}
→ 200 {«id»: «pay_abc,» «status»: «requires_action,» next_action": {«type»: «redirect», «url»: «...»}}

Webhook عن التسجيل الناجح


وظائف/وصلات شبكية
{
"نوع": "دفع. تم التقاطها، «البيانات»: {«id»: «pay _ abc»، «المبلغ»: 9232، «العملة»: «EUR»، «البيانات الوصفية»: {«order _ id»: «ORD-1001»}}
}

المدفوعات


POST/v1/payouts
{
"المبلغ": 5000، "العملة": "اليورو"، "destination_token": "dest_tok_456," "البيانات الوصفية": {"المستخدم _ المعرف":" u _ 77"}
}

قائمة التنفيذ المرجعية

1. البنية الرئيسية: أسرار الخادم بشكل منفصل، أسرار العميل - لمرة واحدة.

2. الخصوصية: في كل مكالمة كتابية + معالجات الويب الخادعة.

3. خطافات الويب: توقيع HMAC، retrai، قائمة انتظار المهام، المراقبة المتأخرة.

4. 3DS/SCA وإعادة التوجيه: التعامل مع الإلغاءات/المهلات، ومحاولة الصديق UX مرة أخرى.

5. أنتيفرود/حدود: السرعة، تفاصيل جديدة، قوائم سوداء، عتبات RG/AML.

6. دفتر الأستاذ والتسوية: دخول مزدوج، تسوية ثلاثية الجوانب، تنبيهات شاذة.

7. التنسيق: مزود احتياطي، قواعد التوجيه حسب BIN/country/augh.

8. الرصد: توافق لوحات القيادة على سعر الفائدة/p95/retrays، وتنبيهات المصارف/الطرق.

9. Legal/PCI: ترميز، سياسة إرجاع، حلقة مدفوعات مغلقة.

10. خطة التدهور: قناة تبديل القتل، قوائم الانتظار، الوضع اليدوي للعمليات الحرجة.

الأخطاء المتكررة

تخزين PAN على جانبه بدون PCI والرموز.

لا → ازدواجية المدفوعات/المدفوعات مع مهلة.

المنطق على الاستجابات المتزامنة دون مراعاة خطوط الويب.

مزود واحد للسوق، لا يوجد احتياطي/سلاسل تعاقبية.

لا توجد معالجة 3DS/إعادة توجيه → صناديق إعادة التدوير المفقودة.

حزمة ضعيفة → المعاملات «المجمدة» و «المفقودة».

عدم وجود اتحادات وتنبيهات واضحة → المشكلة التي يراها العميل، وليس أنت.

الأسئلة الشائعة المصغرة

أيهما أكثر موثوقية: الحالة المتزامنة أم شبكة الويب ؟

الخطاف هو مصدر الحقيقة ؛ الاستجابة المتزامنة - فقط «الإجراء المقبول/المطلوب».

هل يمكنك الاستغناء عن 3DS ؟

يعتمد على التنظيم/المخاطر. في الجماعة الأوروبية/المملكة المتحدة - تعتبر SCA إلزامية ؛ بالنسبة للمخاطر العالية، فإن التصعيد أفضل.

كيفية زيادة معدل الموافقة ؟

BIN/bank/method orchestration، السكك الحديدية المحلية، retras الذكية، الأوصاف الصحيحة، مكافحة الاحتيال منخفضة FPR.

لماذا الدفع «ليس فوريًا» ؟

يعتمد على السكك الحديدية (OST/A2A/local) وبنك المستلم والحدود. دعونا نحصل على نافذة SLA صادقة وتدفق الحالة.

مدفوعات API ليست فقط "إنشاء دفعة. "هذا الانضباط: المصادقة الآمنة → الترميز → الخصوصية → خطافات الويب غير المتزامنة → دفتر الأستاذ والطي → مكافحة الاحتيال/مكافحة غسل الأموال → التنسيق والمراقبة. قم ببناء العملية وفقًا لهذا المخطط، واحتفظ بقنوات احتياطية و UX شفافة - وستكون طبقة الدفع الخاصة بك سريعة ويمكن التنبؤ بها ومقاومة لإخفاقات البنوك ومقدمي الخدمات.