مبتدئ10 دقيقة قراءة
وضع Public Key
وضع Public Key مخصص لتكاملات المتصفح. يستخدم الواجهة الأمامية public_key للحصول على رمز جلسة قصير المدة، ثم ينشئ الطلبات ويتحقق من حالتها دون كشف API Key.
تدفق التكامل
- أنشئ Public Key من لوحة التاجر وفعّل تكامل الواجهة الأمامية.
- اضبط قائمة النطاقات المسموح بها.
- يستدعي المتصفح /api/v1/sdk/token باستخدام Public Key.
- استخدم رمز الجلسة الناتج لاستدعاء /api/v1/sdk/orders.
- حوّل المستخدم إلى payment_url أو استعلم عن حالة الطلب.
الوضع الحالي لا يتطلب توقيع المعلمات في الواجهة الأمامية. يوصى باستخدام JavaScript SDK أو استدعاء واجهات token و orders يدويًا.
الحصول على Public Key
- سجّل الدخول إلى لوحة PonponPay.
- افتح صفحة "Frontend Integration".
- فعّل تكامل الواجهة الأمامية.
- أنشئ وانسخ Public Key بصيغة pub_xxx.
قائمة النطاقات المسموح بها
لا يمكن استخدام Public Key إلا من النطاقات المسموح بها. يتحقق الخادم من Origin أو Referer.
- اسمح بـ localhost في بيئة التطوير فقط.
- استخدم النطاقات الحقيقية في الإنتاج.
- تدعم النطاقات الفرعية بالصيغة *.example.com.
إذا كانت الصفحة داخل iframe أو WebView أو صفحة وسيطة، فقد لا يتم إرسال Origin بشكل ثابت. تحقق من Origin و Referer قبل الإطلاق.
الموصى به: JavaScript SDK
npm install @ponponpay/sdkتهيئة العميل
import { PonponPayClient } from '@ponponpay/sdk/browser';
const client = new PonponPayClient({
publicKey: 'pub_your_public_key',
baseUrl: 'https://api.ponponpay.com'
});إنشاء طلب
const order = await client.createOrder({
currency: 'USDT',
network: 'tron',
amount: 100,
orderId: 'ORDER_123456',
notifyUrl: 'https://your-site.com/webhook',
redirectUrl: 'https://your-site.com/success'
});
window.location.href = order.paymentUrl;الاستعلام عن الحالة
const status = await client.getOrderStatus(order.tradeId);
console.log(status.status);لمزيد من تفاصيل SDK راجع قسم JavaScript SDK أو README في المستودع.
تكامل API يدوي
1. الحصول على رمز قصير المدة
const tokenRes = await fetch('https://api.ponponpay.com/api/v1/sdk/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
public_key: 'pub_your_public_key',
timestamp: Date.now()
})
});
const tokenData = await tokenRes.json();
const token = tokenData.data.token;2. إنشاء طلب باستخدام الرمز
const orderRes = await fetch('https://api.ponponpay.com/api/v1/sdk/orders', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify({
currency: 'USDT',
network: 'tron',
amount: 100,
order_id: 'ORDER_123456',
notify_url: 'https://your-site.com/webhook',
redirect_url: 'https://your-site.com/success'
})
});
const orderData = await orderRes.json();
window.location.href = orderData.data.payment_url;3. الاستعلام عن حالة الطلب
const statusRes = await fetch(
'https://api.ponponpay.com/api/v1/sdk/orders/T20240101120000123456/status',
{
headers: {
Authorization: `Bearer ${token}`
}
}
);
const statusData = await statusRes.json();
console.log(statusData.data.status);حدود القدرات
| القدرة | مدعوم | الوصف |
|---|---|---|
| إنشاء طلب | ✅ | مدعوم عبر واجهات الطلب باستخدام token. |
| الاستعلام عن الحالة | ✅ | للطلبات التابعة للتاجر المرتبط بـ Public Key فقط. |
| واجهات الإدارة الكاملة | ❌ | لا يتم كشفها للمتصفح في وضع Public Key. |
| كشف API Key في المتصفح | ❌ | لا تفعل ذلك أبدًا. استخدم Public Key فقط. |
ملاحظات الأمان
- يمكن أن يكون Public Key عامًا، لكنه يعمل فقط من النطاقات المسموح بها.
- رموز الجلسة قصيرة المدة ويجب تجديدها قبل انتهاء الصلاحية.
- يتحقق الخادم من timestamp والنطاق وحدود الواجهة الأمامية.
- استخدم HTTPS دائمًا في الإنتاج.
إذا كنت تحتاج واجهات إدارة من الخادم، استخدم وضع API Key.