المطورون
واجهة API، في صفحة واحدة
واجهة REST بصيغة JSON للدفع بالبطاقة ونقدًا في المغرب. مفاتيح الاختبار تصلك مع حسابك، والتوثيق يقدّم كل مثال بـ 10 لغات.
I. البدء السريع
أول دفعة، في ثلاث خطوات
في وضع الاختبار: لا تتحرك أي أموال حقيقية، وصفحة البطاقة محاكاة.
I.
احصل على مفتاح الاختبار
سجّل: يظهر مفتاحك السري للاختبار مرة واحدة، في تلك اللحظة. احفظه في متغيّر بيئة على خادمك.
export APX_SECRET_KEY="apx_sk_test_…"II.
أنشئ جلسة دفع
مبلغ بالسنتيم، والعملة، ووسائل الدفع، والعنوان الذي يعود إليه عميلك. الجواب يحمل عنوان الصفحة: وجّه عميلك إليه.
curl https://pay-api.adpromax.com/v1/checkout/sessions \ -u "$APX_SECRET_KEY:" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: checkout-order-1042" \ -d '{ "amount": 25000, "currency": "mad", "payment_method_types": ["card"], "success_url": "https://shop.example.com/thanks", "cancel_url": "https://shop.example.com/cart", "metadata": { "order_id": "1042" } }'III.
اعرف النتيجة عبر webhook
عند نجاح الدفعة نرسل
payment_intent.succeededإلى نقطة النهاية لديك. تحقّق من التوقيع على الجسم الخام، ثم نفّذ الطلب.العودة إلى صفحة النجاح ليست دليلًا على الدفع: سلّم الطلب عند وصول الـ webhook.
import { Buffer } from 'node:buffer' import { createServer } from 'node:http' import { verifySignature } from './verify-signature.mjs' createServer(async (request, response) => { const chunks = [] for await (const chunk of request) chunks.push(chunk) // The exact bytes: verify them before parsing. const rawBody = Buffer.concat(chunks) const header = request.headers['x-adpromaxpay-signature'] ?? '' const secret = process.env.APX_WEBHOOK_SECRET if (!verifySignature(rawBody, header, secret)) { response.writeHead(400).end() return } const event = JSON.parse(rawBody.toString('utf8')) if (event.type === 'payment_intent.succeeded') { const paymentIntent = event.data.object // Fulfil the order that holds this payment intent, once. console.log('paid', paymentIntent.id) } response.writeHead(200).end() }).listen(4242)
II. الكائنات
ستة كائنات، أسماؤها تدلّ عليها
لكل كائن معرّف يبدأ بنوعه، فيقول سطر السجل من أول نظرة عمّ يتحدث.
pi_…
نية الدفع
دفعة واحدة، من إنشائها إلى نتيجتها. تمرّ بحالات قليلة، والكود لديك يقرأ الحالة بدل أن يخمّنها.
cs_…
جلسة الدفع
زيارة لصفحة الدفع المستضافة من أجل طلب واحد. تحمل عنوان الصفحة ونية الدفع التي تسدّدها.
cus_…
العميل
من يدفع: بريد إلكتروني واسم ورقم هاتف. اختياري، ويجمع دفعات الشخص الواحد.
re_…
الاسترداد
مال يُعاد عن دفعة بالبطاقة، كليًّا أو جزئيًّا.
evt_…
الحدث
سجلّ لشيء حدث. والأحداث هي ما تسلّمه الـ webhooks.
we_…
نقطة نهاية الـ webhook
عنوان على خادمك، والأحداث التي يريد استقبالها.
III. Webhooks
موقّعة، ويُعاد إرسالها
الـ webhook طلب HTTPS نرسله إلى خادمك عند حدوث شيء. كل إرسال موقّع، وما لم يُجب عنه خادمك يُعاد إرساله.
- توقيع في ترويسة واحدة: HMAC-SHA256 للوقت وللجسم الخام
- يُرفض الإرسال الأقدم من خمس دقائق، فلا يمكن إعادة تشغيل إرسال مُلتقَط
- إعادة المحاولة وفق جدول يمتدّ نحو ثلاثة أيام
- كل محاولة مدرجة في لوحة التحكم، مع زر لإعادة إرسالها
- حدث نموذجي للتحقق من عنوانك، في وضع الاختبار
X-AdProMaxPay-Signature: t=1790851200,v1=d2e39688034d…9a9879e
IV. عدم التكرار
أعد إرساله، دون أن يتكرّر
قد تنقطع الشبكة بعد أن ننجز العمل وقبل أن تقرأ الجواب. أعد إرسال الطلب نفسه مع Idempotency-Key نفسها فيعود إليك الجواب الأول: لا شيء يُنفَّذ مرة ثانية.
- إلزامي مع كل طلب يحرّك مالًا
- يُحفظ 24 ساعة، لكل مؤسسة ولكل وضع
- الجواب المُعاد يقول ذلك، في ترويسة
V. الأخطاء
أخطاء تعرف ما تفعل بها
الطلب الذي يفشل يجيب بكائن خطأ. الكود لديك يتفرّع بحسب نوعه ورمزه؛ أما الرسالة فهي للبشر.
- سبعة أنواع، من الطلب الخاطئ إلى البطاقة المرفوضة
- رمز ثابت لكل سبب، وله صفحته في التوثيق
- معرّف طلب في كل جواب، لتجده في سجلات الطلبات
- رسائل بالإنجليزية أو الفرنسية أو العربية، بحسب ما يطلبه طلبك
VI. الحدود
حدود تراها بعينك
تحدّ واجهة API عدد الطلبات التي ترسلها المؤسسة في الدقيقة، حتى لا تبطئ اندفاعةُ ربطٍ واحد بقية المستخدمين. ولوضع الاختبار حدوده الخاصة.
- ثلاث ترويسات في كل جواب تخبرك أين أنت
- الرفض يخبرك كم تنتظر
- لوحة التحكم تعرض الحدود المطبَّقة عليك، وتتيح طلب المزيد
VII. المفاتيح
مفاتيح، للاختبار وللوضع المباشر
المفتاح يخبر واجهة API أيّ مؤسسة أنت وفي أي وضع تعمل. مفاتيح الاختبار تعمل فور التسجيل؛ والمفاتيح المباشرة تعمل بعد تفعيل حسابك.
- يظهر المفتاح السري مرة واحدة، عند إنشائه
- جدّد مفتاحًا، فيبقى القديم يعمل للمدة التي تختارها
- مفتاح الاختبار لا يرى إلا بيانات الاختبار، والمفتاح المباشر لا يرى إلا البيانات المباشرة
VIII. الأمثلة
كل مثال، بـ 10 لغات
اختر لغة في التوثيق، فتتبعها كل الصفحات.
- curl
- Node.js
- TypeScript
- Python
- PHP
- Ruby
- Go
- Java
- C#
- Rust
خذ مفاتيح الاختبار، وأرسل أول طلب
تصلك مع حسابك. لا تتحرك أي أموال حقيقية في وضع الاختبار.