واجهة Checkout#

Povito Checkout صفحة دفع مستضافة للتجّار في العراق. يُنشئ خادمك جلسة دفع (checkout session)، وتوجّه المتسوّق إلى الرابط url الذي يعود إليك، فيتحقّق المتسوّق من رقم هاتفه ويدفع عبر زين كاش أو FIB أو بطاقة أو الدفع عند الاستلام، ثم تُبلغك Povito بالنتيجة — عبر webhook، وبشكل موثوق عبر GET /checkout/sessions/{id}.

• البداية السريعةأنشئ جلسة، وجّه المتسوّق، تحقّق من الدفع، واستقبل الـ webhook. خمس دقائق مع curl.
• صفحة الدفع المستضافةكل خيارات الجلسة: التعبئة المسبقة، ما تجمعه من المتسوّق، اللغات، الانتهاء، روابط العودة، الهوية البصرية.
• طرق الدفع ENتدفّقات التحويل والعرض والخصم والدفع خارج المنصّة؛ الدفع عند الاستلام؛ توجيه البطاقات؛ العرض بالدولار.
• Webhooksالتحقّق من التوقيع بلغات Node وPHP وPython وDart. إعادة المحاولة وإعادة الإرسال ومعالجة الأحداث دون تكرار.
• الاختبارمفاتيح الاختبار، بوابة الدفع التجريبية، رقم الهاتف ورمز التحقّق التجريبيان، أداة اختبار الـ webhook.
• مرجع API ENمولَّد من عقد OpenAPI. تفاعلي، أو ثابت بدون JavaScript.

شكل التكامل#

1. أنشئ جلسة من خادمك بمفتاحك السرّي: POST /v1/checkout/sessions مع المبلغ وبنود الطلب ومعرّفك الخاص reference_id ورابط النجاح success_url. تحصل على id وurl.
2. وجّه المتسوّق إلى url (https://checkout.povito.com/c/…). تتولّى Povito التحقّق من الهاتف، وجمع الاسم والعنوان، واختيار طريقة الدفع، والتسليم إلى مزوّد الدفع.
3. يعود المتسوّق إلى success_url مع إضافة session_id وreference_id فقط — لا شيء غيرهما. لا يحمل الرابط أي حالة دفع أبداً.
4. تحقّق عبر GET /v1/checkout/sessions/{id} ونفّذ الطلب حين تكون payment_status تساوي paid (أو requires_offline_collection للدفع عند الاستلام).
5. عالج الحدث checkout.session.completed على نقطة الـ webhook الخاصة بك للحالات التي لا يعود فيها المتسوّق إطلاقاً. تعامل معه كتنبيه لتنفيذ الخطوة 4.

ثلاثة أمور قبل أن تبدأ#

المبالغ أعداد صحيحة بأصغر وحدة للعملة، والدينار العراقي ليست له وحدة أصغر. 45000 تعني خمسة وأربعين ألف دينار. أما الدولار فبالسنت: 3435 تعني 34.35 دولاراً. تُرفض الكسور العشرية والنصوص.

الـ webhook تلميح، والجلسة هي الحقيقة. تطبّق Povito القاعدة نفسها على مزوّدي الدفع الذين تتعامل معهم: لا يُعدّ أي دفع مكتملاً عند وصول استدعاء من المزوّد حتى تتحقّق Povito من واجهة الحالة الخاصة بالمزوّد نفسه ويتطابق المبلغ المحصَّل مع المبلغ المعروض. افعل الشيء نفسه: عند وصول webhook، استدعِ GET للجلسة ثم تصرّف.

مفتاحان، وواجهتان. المفاتيح السرّية povito_ck_… تبقى على خادمك وتفتح واجهة التاجر. المفاتيح القابلة للنشر povito_pk_… آمنة في المتصفّح أو التطبيق ولا تفتح إلا /v1/public/*، وهي ما تستخدمه الصفحة المستضافة (وفي المرحلة الثانية، المكوّن المضمَّن).

العناوين الأساسية#

وضع الاختبار هو وضعٌ للمفتاح لا مضيفٌ منفصل: مفتاح povito_ck_test_… على المضيف نفسه يُنشئ كائنات livemode: false لا تشارك بيانات الإنتاج صفّاً واحداً.

الحالة#

Povito Checkout في المرحلة الأولى من ADR-CHK-001: واجهة التاجر والصفحة المستضافة ووضع الاختبار والـ webhooks والاستردادات مبنية ومغطّاة باختبار شامل، ولا يُعدّ أي مسار مكتملاً إلا بعد تشغيله فعلياً (بوابة الإكمال في Povito). المكوّن المضمَّن، والبطاقات المحفوظة، وواجهة ملفّات العملاء من المرحلة الثانية وموسومة بذلك في كل مكان من هذه الوثائق.

تبيع على بوفيتو؟#

واجهة الشركاء تزامن كتالوجك ومخزونك وأسعارك وطلباتك من نظامك الخاص.