وثائق ربط TruePaySys

مرحباً بك في وثائق المطورين. تتيح لك واجهة برمجة التطبيقات (API) الخاصة بنا دمج بوابة الدفع TruePaySys في موقعك أو تطبيقك بسهولة تامة. نحن نستخدم معايير RESTful ونعيد البيانات بصيغة JSON.

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

https://truepaysys.com/api/v1

المصادقة (Authentication)

تتطلب جميع الطلبات وجود X-Api-Key في ترويسة الطلب (Headers). يمكنك الحصول على مفتاحك من لوحة تحكم التاجر.

headers example

X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

بدء عملية دفع (Initiate Payment)

لبدء عملية دفع جديدة، قم بإرسال طلب POST إلى المسار أدناه. سيقوم النظام بإنشاء معاملة وإعادة رابط توجيه (Redirect URL) ليدفع من خلاله العميل.

POST https://truepaysys.com/api/v1/initiate

المتغيرات (JSON Body)

amount REQUIRED

مبلغ العملية (مثال: 150.00)

order_id REQUIRED

رقم الطلب الفريد في نظامك (ID)

method OPTIONAL

طريقة الدفع: instapay, wallet

customer_name OPTIONAL

الاسم بالكامل للعميل (لتفادي طلب البيانات)

customer_email OPTIONAL

البريد الإلكتروني للعميل (لتفادي طلب البيانات)

customer_phone OPTIONAL

رقم هاتف العميل (لتفادي طلب البيانات)

💡 ملحوظة ديناميكية: إذا لم يتم إرسال بيانات العميل (الاسم، البريد، الهاتف) عند بدء الدفع، سيقوم النظام تلقائياً بتوجيه العميل إلى صفحة إدخال البيانات لإدخالها بنفسه قبل إتمام عملية الدفع.

Request Example

curl -X POST https://truepaysys.com/api/v1/initiate \
  -H "X-Api-Key: pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "order_id": "ORD-12345",
    "method": "instapay",
    "customer_name": "Ahmed Mohamed",
    "customer_email": "customer@example.com",
    "customer_phone": "01122334455"
  }'

هيكل الاستجابة (Response)

Successful Response (200 OK)

{
  "transaction_id": 105,
  "redirect_url": "https://truepaysys.com/pay/105"
}

إشعارات الدفع (Webhooks)

بمجرد اكتمال عملية الدفع (بعد المراجعة من الإدارة)، سنقوم بإرسال طلب POST إلى رابط الـ Callback الذي قمت بتحديده في إعدادات حسابك.

التحقق من التوقيع (Signature Verification)

يتم إرسال توقيع رقمي في الـ Header باسم X-Signature. هو عبارة عن HMAC-SHA256 لجسم الطلب (Request Body) باستخدام الـ Secret Key الخاص بك.

أمثلة التحقق (Verification Examples)

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$secret = 'YOUR_SECRET_KEY';

$hash = hash_hmac('sha256', $payload, $secret);

if (hash_equals($hash, $signature)) {
    // Signature is valid
    $data = json_decode($payload, true);
    // Process order...
}

const crypto = require('crypto');
// Assuming you have the raw body
const signature = req.headers['x-signature'];
const secret = 'YOUR_SECRET_KEY';

const hash = crypto
  .createHmac('sha256', secret)
  .update(req.rawBody) // Use raw request body
  .digest('hex');

if (hash === signature) {
    // Signature is valid
}

import hmac
import hashlib

payload = request.data # Raw bytes
signature = request.headers.get('X-Signature')
secret = b'YOUR_SECRET_KEY'

hash = hmac.new(secret, payload, hashlib.sha256).hexdigest()

if hmac.compare_digest(hash, signature):
    # Signature is valid

Webhook JSON Payload

{
  "id": 105,
  "status": "approved",
  "amount": 150.00,
  "foreign_id": "ORD-12345",
  "method": "instapay",
  "created_at": "2023-10-25 14:30:00"
}

بيانات الاختبار والسيناريوهات

بما أن النظام يعتمد على مراجعة الإيصالات يدوياً من قبل الإدارة، يمكنك في بيئة الاختبار رفع أي صورة توضيحية كإيصال. لتجربة السيناريوهات المختلفة:

محاكاة النجاح

قم برفع إيصال واضح وانتظر موافقة لوحة تحكم الأدمن (أو وافق عليها بنفسك إذا كنت تملك صلاحية الوصول للأدمن).

محاكاة الرفض

من لوحة تحكم الأدمن، اختر "رفض" للمعاملة المعلقة لتصلك إشارة بالفشل إلى الـ Webhook.

أكواد الخطأ (Error Codes)

نستخدم أكواد HTTP القياسية للإشارة إلى نجاح أو فشل الطلبات، بالإضافة إلى رسائل خطأ توضيحية في جسم الرد (JSON).

HTTP Code	Error Type	الوصف
200 OK	Success	الطلب تم بنجاح.
400 Bad Request	Validation Error	بيانات غير مكتملة أو غير صالحة (مثال: مبلغ سالب، رقم طلب مفقود).
401 Unauthorized	Authentication Error	مفتاح الـ API غير صالح أو مفقود.
403 Forbidden	Permission Error	حسابك محظور أو غير مفعل.
404 Not Found	Resource Warning	الرابط أو المورد غير موجود.
405 Method Not Allowed	Method Error	استخدام GET بدلاً من POST (أو العكس).
500 Server Error	System Error	خطأ داخلي في الخادم. يرجى التواصل مع الدعم الفني.

تكامل كامل باستخدام PHP (cURL)

$data = [
    'amount' => 500.00,
    'order_id' => 'MY_ORDER_123',
    'method' => 'instapay',
    'customer_name' => 'Ahmed Mohamed',
    'customer_email' => 'customer@example.com',
    'customer_phone' => '01122334455'
];

$ch = curl_init("https://truepaysys.com/api/v1/initiate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: YOUR_PUBLIC_KEY'
]);

$response = curl_exec($ch);
$json = json_decode($response, true);

if (isset($json['redirect_url'])) {
    header("Location: " . $json['redirect_url']);
} else {
    echo "Error: " . ($json['error'] ?? 'Unknown');
}

Node.js (Using Axios)

const axios = require('axios');

const data = {
    amount: 500.00,
    order_id: 'MY_ORDER_123',
    method: 'instapay',
    customer_name: 'Ahmed Mohamed',
    customer_email: 'customer@example.com',
    customer_phone: '01122334455'
};

try {
    const response = await axios.post('https://truepaysys.com/api/v1/initiate', data, {
        headers: {
            'Content-Type': 'application/json',
            'X-Api-Key': 'YOUR_PUBLIC_KEY'
        }
    });

    if (response.data.redirect_url) {
        console.log('Payment URL:', response.data.redirect_url);
        // Redirect user...
    }
} catch (error) {
    console.error('Error:', error.response.data);
}

Python (Using Requests)

import requests

url = "https://truepaysys.com/api/v1/initiate"

payload = {
    "amount": 500.00,
    "order_id": "MY_ORDER_123",
    "method": "instapay",
    "customer_name": "Ahmed Mohamed",
    "customer_email": "customer@example.com",
    "customer_phone": "01122334455"
}

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_PUBLIC_KEY"
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    data = response.json()
    print("Payment URL:", data["redirect_url"])
else:
    print("Error:", response.text)