ابدأ من إعداد حساب الشريك
تحدد BeanzPay هوية الشريك وبيئاته والباقات وشروطه التجارية وأصل العودة وعنوان إشعارات دورة التاجر. تحفظ المفاتيح في خادم المنصة. استعلم عن عقد الحساب قبل إنشاء أول طلب؛ قبول حساب الشريك لا يمنح اعتمادًا ماليًا لجميع التجار.
GET https://beanzpay.com/api/partner/live/integration
X-Partner-Key: ${BEANZPAY_PARTNER_KEY}
X-Partner-Secret: ${BEANZPAY_PARTNER_SECRET}الشروط التجارية خاصة بكل شريك. استخدم الكتالوج وpricing_revision والاقتباس المحفوظ على الخادم؛ لا تفترض نسبة شريك آخر أو إعفاءه أو باقاته.
رحلة واحدة بمعرفات ثابتة
اقرأ القوائم والمتطلبات
اجلب الباقات وأنواع المنشأة والمستندات الديناميكية. أرسل السعر المتفق عليه قبل الضريبة.
أنشئ الطلب من خادم منصتك
استخدم POST /api/partner/live/merchants واحفظ external_reference وapplication_id وmerchant_id قبل المتابعة.
تابع المستندات والمراجعة والسداد
ارفع كل مستند في خانته، عالج النواقص، وتابع السداد من نتيجة مؤكدة. يبقى التاجر مرتبطًا بالمتجر نفسه.
اترك التوقيع والتفويض للمالك
انقل المالك عبر owner_continuation_url. يحضر المالك للتوقيع والتفويض ثم تستأنف المتابعة بالمعرفات نفسها.
أصدر اعتماد التاجر المصرح به
استخدم اعتماد Native مربوطًا بالتاجر والبيئة والصلاحيات. لا تعِد إصدار مفاتيح في كل مزامنة.
اختر البيئة والاعتماد المناسبين
| السطح | العنوان | الغرض |
|---|---|---|
| Partner Test | /api/partner | اختبار دورة التسجيل؛ لا يصدر مفاتيح دفع |
| Partner Production | /api/partner/live | تسجيل وإدارة التجار الحقيقيين المصرح بهم |
| Native Test / Live | /api/merchant/v1 | البيئة يحددها اعتماد التاجر وأهليته |
وجود واجهة Test للتسجيل لا يثبت وجود ملف دفع تجريبي. اقرأ /account و/features باستخدام اعتماد Native فعلي ومفوض. أدوار موظفي منصتك تبقى مسؤولية منصتك، وصلاحيات Native تخص العمليات الممنوحة على حساب التاجر.
احفظ العملية قبل إرسالها
ينشئ خادمك الدفع عبر Native مع Idempotency-Key محفوظ. تؤكد إشعارات Native أو المطابقة المصادق عليها النتيجة. رابط العودة للعميل لا يكفي لإثبات السداد. يدعم الاسترداد الكامل والجزئي وفق أهلية الحساب، مع سجل طفل مستقل لكل استرداد.
POST /api/merchant/v1/payments
Authorization: Bearer ${BEANZPAY_MERCHANT_TOKEN}
Idempotency-Key: ${SAVED_PAYMENT_KEY}
GET /api/merchant/v1/refunds?idempotency_key=${SAVED_REFUND_KEY}
POST /api/merchant/v1/refunds/{refund}/reconcile
{}إذا كانت النتيجة مجهولة، استعد العملية الأصلية واستعلم عنها؛ لا تنشئ طلبًا ماليًا بديلًا بمفتاح جديد. عند تبديل بوابة الدفع تبقى قراءة العمليات القديمة واستردادها على البوابة والحساب الأصليين.
افصل قناة دورة التاجر عن قناة المال
| القناة | وظيفتها | التحقق |
|---|---|---|
| Partner lifecycle | الطلب والمستندات والتفعيل والكتالوج وطلبات التشغيل | مخطط الشريك وسره المخصص وعقد الحساب |
| Native financial 3.0.0 | الدفع والفشل والاسترداد والإلغاء المؤكد | الجسم الخام والتوقيت ومعرف الحدث والتاجر والبيئة والمرجع والمبلغ والعملة |
X-BeanzPay-Webhook-ID = X-BeanzPay-Event-ID = event_id
وقت محاولة التسليم في الهيدر مستقل عن occurred_at الثابت. احفظ الأحداث ومنع التكرار قبل تجهيز رد 2xx. استعد الإشعار المالي المفقود من سجل Native وإعادة التسليم أو reconcile.
طلبات التشغيل من منصتك إلى BeanzPay
أرسل طلب Apple Pay أو تشغيل وإيقاف طريقة دفع أو حساب المزود أو تفعيل قدرة أو تعديل رسوم أو تذكرة دعم عبر operational-requests. تراجع BeanzPay الطلب وتراسل المزود يدويًا وتثبت القرار والأثر الفعلي. المهلة الافتراضية لإنهاء الطلب المكتمل ثلاثة أيام عمل بالرياض، ويظهر التأخر والتصعيد.
في Apple Pay يحمل موصلك ملف ربط النطاق العام المربوط بالطلب، يثبته على النطاق الفعلي، ثم يرسل بصمته. تركيب الملف وحده لا يثبت جاهزية الدفع. الاشتراكات تحتاج إعداد حساب التاجر وتفويضه؛ الرصيد الرسمي والتسويات وPayout وAuth/Capture تبقى ضمن القدرات المشروطة المثبتة في /features.
ملفات الربط الجاهزة
الملفات عامة دون مفاتيح أو حسابات جاهزة. تمنح بيانات الاعتماد لكل شريك وتاجر عبر قناة خاصة بعد استيفاء الموافقات.
اختبر الموصل قبل إعلان اكتمال الربط
تغطي خطة القبول التسجيل والتوقيع والتفويض وعزل التجار والبيئات، الدفع الناجح والفاشل والمتأخر، منع التكرار، الإشعارات الخاطئة، الاسترداد الجزئي والمتزامن والنتيجة المجهولة، تبديل البوابة وتدوير الاعتماد. الفحص الصحي أو نجاح تنزيل الدليل ليس قبولًا ماليًا.
فواتير BeanzPay مستندات سداد باسم التاجر؛ يصدر نظام التاجر فاتورته الضريبية.