7 نقاط نهاية

روابط الدفع

مبلغ ووصف ورابط تُرسلونه. يدفع الزبون على صفحة تستضيفها ChariPay — ولا تستضيفون أنتم أي بيانات بطاقة.

عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.

بكلمات بسيطة

صفحة أداء جاهزة للمشاركة — بلا موقع إلكتروني.

متى تستعملونها

لفاتورة أو عرض سعر أو بيع عن بُعد أو استخلاص عبر واتساب أو دفع في الوكالة. وهو أسرع إدماج: استدعاء واحد يكفي للاستخلاص.

كيف تدمجونها

1أنشئوا الرابط بالمبلغ ووصفٍ له؛ وأضيفوا externalId الخاص بكم لتتمكنوا من إعادة الاستدعاء بأمان.
2شاركوا الرابط الذي تستلمونه — أو رمز QR الخاص به، أو الملصق PDF الجاهز للطباعة للاستخلاص في عين المكان.
3للاستخلاص نقدًا، أنشئوا الرابط بـpaymentMethod: CASH: يتلقى المؤدّي رمزًا (cashinCode) يقدّمه في الوكالة، ويؤكد لكم ويب هوك payment.succeeded الاستخلاص — بنفس آلية البطاقة.
4استقبلوا ويب هوك نجاح الدفع وطابقوه مع طلبكم عبر externalId الذي زوّدتمونا به.
5ألغوا الرابط إن لم تتمّ البيعة: الرابط الملغى لا يمكن دفعه بعد ذلك.

بطاقة اختبار السندبوكس

تعمل السندبوكس على مسارات حقيقية مقابل بيئة اختبار: المسارات حقيقية، أما المال فلا. وبطاقة واحدة فقط مقبولة فيها.

هذا الـ PAN هو الوحيد المقبول. أي رقم آخر — بما فيه 4242… الخاص بمنصات أخرى — يُرفض عند المنبع — عادةً بخطأ 502 — مع الرمز الثابت BAAS_CHARI_ERROR. إن واجهتم هذا الخطأ أثناء الاختبار، فتحققوا أولًا من البطاقة المُدخلة.

POST/v1/payment-links/{reference}/sendإرسال رابط دفع عبر البريد الإلكتروني
POST/v1/payment-links/{reference}/cancelإلغاء رابط دفع
GET/v1/payment-linksعرض روابط الدفع
POST/v1/payment-linksإنشاء رابط دفع
GET/v1/payment-links/{reference}/qrرمز QR لرابط الدفع
GET/v1/payment-links/{reference}/posterملصق رابط الدفع (PDF)
GET/v1/payment-links/{reference}استرجاع رابط دفع

POST202

إرسال رابط دفع عبر البريد الإلكتروني

يرسل رابط الدفع عبر البريد الإلكتروني إلى العنوان المحدد، أو إلى بريد الزبون المسجّل في الرابط إذا لم يُرسل أي متن للطلب. يُرجع 202 Accepted.

المخطط · SendPaymentLinkRequest

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب
`email`	string	body	اختياري	البريد الإلكتروني للمستلم؛ عند إغفاله يُستخدم البريد الإلكتروني للزبون المحفوظ في الرابط.

POST

إلغاء رابط دفع

يعطّل الرابط بحيث لا يمكن دفعه بعد ذلك. Idempotent (عدم التكرار)؛ يُعيد الرابط المحدّث.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب	مرجع رابط الدفع.

GET

عرض روابط الدفع

يُعيد روابط الدفع الخاصة بالمستدعي لبيئة المفتاح، الأحدث أولًا، على شكل Page مقسّمة إلى صفحات.

الحقل	النوع	الموضع	مطلوب	الوصف
`origin`	enum	query	اختياري	التصفية حسب مصدر الإنشاء (API أو DASHBOARD).القيم `APIDASHBOARD`
`pageable`	Pageable	query	مطلوب

POST200

إنشاء رابط دفع

يُنشئ رابط دفع قابلًا لإعادة الاستخدام (أو لاستخدام واحد). قدّموا externalId اختياريًا خاصًا بكم (فريدًا لكل تاجر) لجعل الإنشاء غير قابل للتكرار (idempotent): يؤدي externalId مكرر إلى إعادة الرابط الموجود مع 200 OK بدلًا من إنشاء رابط جديد. يُعيد الرابط بما في ذلك payUrl الموجّه إلى المشتري.

المخطط · CreatePaymentLinkRequest

الحقل	النوع	الموضع	مطلوب	الوصف
`Idempotency-Key`	string	header	اختياري	مفتاح Idempotency اختياري؛ إعادة إرسال القيمة نفسها تُعيد النتيجة الأولى.
`amount`	number	body	مطلوب	المبلغ المراد تحصيله، بالدرهم (الوحدة الرئيسية).
`description`	string	body	مطلوب	وصف قصير يُعرض للمشتري.
`singleUse`	boolean	body	اختياري	true = يُستهلك الرابط بعد عملية دفع ناجحة واحدة؛ false = قابل لإعادة الاستخدام. القيمة الافتراضية true.
`paymentMethod`	enum	body	اختياري	وسيلة الدفع المعروضة افتراضياً في صفحة الدفع المستضافة. القيمة الافتراضية CARD.القيم `CARDCASH`
`customerName`	string	body	اختياري	اسم المشتري (اختياري).
`customerEmail`	string	body	اختياري	البريد الإلكتروني للمشتري، اختياري.
`customerPhone`	string	body	اختياري	هاتف المشتري، اختياري (E.164).
`expiresAt`	string (date-time)	body	اختياري	تاريخ انتهاء اختياري (ISO-8601 UTC). يجب أن يكون في المستقبل.
`acceptUrl`	string	body	اختياري	يُعاد توجيه المشتري إلى هنا بعد نجاح الدفع (https:// فقط).
`declineUrl`	string	body	اختياري	يُعاد توجيه المشتري إلى هنا بعد فشل الدفع أو رفضه (https:// فقط).
`notificationUrl`	string	body	اختياري	وجهة ويب هوك خاصة بهذا الرابط (https:// فقط)، إضافةً إلى نقاط النهاية المسجّلة.
`externalId`	string	body	اختياري	معرّف اختياري يوفره المستدعي، فريد لكل تاجر. إنشاء رابط بـ externalId موجود مسبقاً يُرجع الرابط الموجود (إعادة إرسال Idempotent).
`metadata`	object	body	اختياري	كائن metadata حر اختياري، يُعاد كما هو عند القراءة وفي ويب هوك الدفع عند أداء الرابط.

GET200

رمز QR لرابط الدفع

يُرجع رمز QR بصيغة PNG يشفّر payUrl الخاص بالرابط والموجّه إلى المشتري.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

GET200

ملصق رابط الدفع (PDF)

تُرجع ملصقًا بحجم A4 قابلًا للطباعة (PDF) يتضمّن رمز QR والمبلغ، لعرضه عند صندوق الدفع.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

GET

استرجاع رابط دفع

تجلب رابط دفع واحدًا بواسطة مرجعه.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب	مرجع رابط الدفع.

تحدّثوا إلى مختص دمج

سؤال حول الدمج؟

يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.

اتصلوا بنا