PonponPay
مبتدئ10 دقيقة قراءة

وضع Public Key

وضع Public Key مخصص لتكاملات المتصفح. يستخدم الواجهة الأمامية public_key للحصول على رمز جلسة قصير المدة، ثم ينشئ الطلبات ويتحقق من حالتها دون كشف API Key.

تدفق التكامل

  1. أنشئ Public Key من لوحة التاجر وفعّل تكامل الواجهة الأمامية.
  2. اضبط قائمة النطاقات المسموح بها.
  3. يستدعي المتصفح /api/v1/sdk/token باستخدام Public Key.
  4. استخدم رمز الجلسة الناتج لاستدعاء /api/v1/sdk/orders.
  5. حوّل المستخدم إلى payment_url أو استعلم عن حالة الطلب.

الوضع الحالي لا يتطلب توقيع المعلمات في الواجهة الأمامية. يوصى باستخدام JavaScript SDK أو استدعاء واجهات token و orders يدويًا.

الحصول على Public Key

  1. سجّل الدخول إلى لوحة PonponPay.
  2. افتح صفحة "Frontend Integration".
  3. فعّل تكامل الواجهة الأمامية.
  4. أنشئ وانسخ 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.