⚡ PayLink SY

توثيق API — PayLink SY

دليل المطوّر لربط متجرك بالمنصة

نظرة عامة

كل الطلبات والاستجابات بصيغة JSON.
المصادقة عبر ترويسة X-Api-Key (أو باراميتر api_key).
تحقق تلقائي بدون هاش: الزبون يحوّل المبلغ المطلوب بالضبط لعنوانك، والمنصة تكتشف الدفعة وتؤكّدها تلقائياً — لا حاجة لإدخال رقم عملية.
حجز المبلغ: لا يمكن إنشاء فاتورتين فعّالتين بنفس المبلغ على نفس العنوان — المبلغ يُحجز حتى تكتمل أو تنتهي الفاتورة.
نافذة الدفع: 20 دقيقة لكل فاتورة.

الرابط الأساسي (Base URL):

https://paylinksy.com/api/index.php

كيف يعمل الدفع (تلقائي)

متجرك ينشئ فاتورة بمبلغ محدّد وعنوان الاستلام (create).
يعرض متجرك للزبون: العنوان + المبلغ بالضبط + عدّاد.
الزبون يحوّل المبلغ المطلوب بالضبط إلى العنوان.
متجرك يستعلم عن الحالة كل ~15 ثانية (status) — والمنصة تراقب العنوان وتؤكّد تلقائياً أول ما تصل الدفعة.
عند status: paid → الدفعة مؤكّدة. بدون أي رقم عملية.

مهم: يجب أن يحوّل الزبون المبلغ بالضبط (بما فيه الكسور إن وجدت) حتى تتم المطابقة.

بداية سريعة

اربط محفظتك وولّد مفتاح API من لوحة التحكم.
أرسل المفتاح في ترويسة X-Api-Key مع كل طلب.
أنشئ فاتورة (create)، اعرض العنوان والمبلغ للزبون، ثم تابع الحالة (status) حتى paid.

المصادقة

أرسل مفتاحك في الترويسة مع كل طلب:

curl "https://paylinksy.com/api/index.php?resource=status" \ -H "X-Api-Key: YOUR_API_KEY"

POST

1) إنشاء فاتورة

?resource=invoice&action=create

الحقل	إلزامي	الوصف
`service`	نعم	الخدمة: `usdt` أو `binance`
`network`	لـ usdt	الشبكة: `trc20` أو `bep20` (مطلوبة مع usdt فقط)
`amount`	نعم	المبلغ المطلوب
`to_address`	لـ usdt	عنوان محفظتك المستلِمة (مع usdt فقط)
`metadata`	لا	بيانات متجرك (order_id…) — JSON

curl -X POST "https://paylinksy.com/api/index.php?resource=invoice&action=create" \ -H "X-Api-Key: YOUR_API_KEY" \ -d "service=usdt" \ -d "network=trc20" \ -d "amount=100" \ -d "to_address=TXXXXXXXXXXXXXXXXX"

للدفع عبر Binance Pay: استخدم service=binance بدون network أو to_address — تُطابَق الدفعة تلقائياً على حسابك المربوط.

الاستجابة تحوي public_ref (معرّف الفاتورة) وexpires_at.

إذا كان نفس المبلغ محجوزاً لفاتورة فعّالة أخرى على نفس العنوان، تُرجع المنصة success: false مع reserved_minutes (الوقت المتبقّي) — اطلب من الزبون الانتظار أو استخدم مبلغاً مختلفاً.

GET

2) حالة الفاتورة

?resource=invoice&action=status&public_ref=...

النقطة الأهم: يستعلم عنها متجرك كل ~15 ثانية ضمن النافذة. كل استعلام يشغّل مراقبة العنوان، فأول ما تصل الدفعة المطابقة تصبح الحالة paid تلقائياً.

قيم status:

القيمة	المعنى
`pending`	بانتظار وصول الدفعة — تابع الاستعلام
`paid`	✅ وصلت الدفعة وتأكّدت تلقائياً
`expired`	انتهت مدة الفاتورة
`cancelled`	أُلغيت الفاتورة

POST

3) إلغاء فاتورة

?resource=invoice&action=cancel

الحقل المطلوب: public_ref

GET

4) جلب رصيد عنوان

?resource=usdt&action=balance&network=...&address=...

أكواد HTTP

الكود	المعنى
400	طلب ناقص أو معامل غير صالح
401	مفتاح API مفقود
402	انتهى الاشتراك / لا رصيد
403	مفتاح موقوف أو API معطّل للحساب
404	غير موجود
429	تجاوز حد الطلبات
503	الموقع تحت الصيانة / متوقف