دليل المطورين لنظام الدفع Smart EPay 🚀

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

إنشاء حساب إنشاء مفتاح API

بعد إنشاء ApiKey، سيكون بإمكانك استخدام هذا المفتاح لإرسال طلبات إلى API الخاص بنا.

خاصية	الوصف
CurrencyCode	رمز العملة للمعاملة. يمكن أن يكون: 'USD' دولار الأمريكي 'SYP' ليرة السورية 'EUR' يورو هذا مطلوب لتحديد نوع العملة المستخدمة في المعاملة.
Amount	مقدار المبلغ المراد تحويله. يجب أن يكون هذا رقماً موجباً يعبر عن قيمة المعاملة بالعملة المحددة.
Desc	وصف المعاملة. هذا يوفر تفاصيل حول الغرض من المعاملة أو المنتجات المدفوعة.
RedirectUrl	الرابط الذي سيتم إعادة توجيه المستخدم إليه بعد إتمام الدفع. يستخدم هذا لإعادة المستخدم إلى صفحة محددة، مثل صفحة الشكر أو تأكيد الطلب.

كيفية استخدام الAPI لإنشاء معاملات الدفع

لإنشاء معاملة دفع باستخدام نظامنا، يجب أن ترسل طلب من النوع POST مع بيانات المطلوبة بصيغة JSON الى العنوان التالي:

POST /api/payments/transactions

إليك مثال بمختلف لغات البرمجة

import java.net.HttpURLConnection
import java.net.URL

fun main() {
  val apiUrl = "https://smart-epay.com/api/payments/transactions"
  val apiKey = "Your-API-Key-Here"
  val jsonData = "{\"CurrencyCode\": \"SYP\", \"Amount\": 200, \"Desc\": \"Description of the transaction\", \"RedirectUrl\": \"https://example.com/redirect-after-payment\"}"

  val url = URL(apiUrl)
  (url.openConnection() as HttpURLConnection).apply {
    requestMethod = "POST"
    setRequestProperty("Content-Type", "application/json")
    setRequestProperty("Authorization", "Bearer $apiKey")
    doOutput = true
    outputStream.use { it.write(jsonData.toByteArray()) }
    println("Response Code: $responseCode")
    if (responseCode == HttpURLConnection.HTTP_OK) {
      println("Response: " + inputStream.bufferedReader().use { it.readText() })
    } else {
      println("Error in connection")
    }
  }
}

$apiUrl = '<%=Domain/api/payments/transactions';
$apiKey = 'Your-API-Key-Here';
$data = array('CurrencyCode' => 'SYP', 'Amount' => 200, 'Desc' => 'Description of the transaction', 'RedirectUrl' => 'https://example.com/redirect-after-payment');
$jsonData = json_encode($data);
$options = array('http' => array(
    'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiKey",
    'method' => 'POST',
    'content' => $jsonData
));
$context = stream_context_create($options);
$response = file_get_contents($apiUrl, false, $context);
if ($response === false) {
    echo 'Error in request';
} else {
    echo 'Success: ' . $response;
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiUrl = "<%=Domain/api/payments/transactions";
        String apiKey = "Your-API-Key-Here";
        String json = "{\"CurrencyCode\":\"SYP\",\"Amount\":200,\"Desc\":\"Description of the transaction\",\"RedirectUrl\":\"https://example.com/redirect-after-payment\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(apiUrl))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(BodyPublishers.ofString(json))
            .build();

        HttpResponse response = client.send(request, BodyHandlers.ofString());
        System.out.println(response.statusCode() == 200 ? response.body() : "Error: " + response.statusCode());
    }
}

import requests
headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {'Your-API-Key-Here'}'
}
data = {
    "CurrencyCode": "SYP",
    "Amount": 200,
    "Desc": "Description of the transaction",
    "RedirectUrl": "https://example.com/redirect-after-payment"
}

response = requests.post('https://smart-epay.com/api/payments/transactions', headers=headers, json=data)
if response.status_code == 200:
    data_received = response.json()
    print('Success:', data_received)
else:
    print('Error:', response.status_code)

const apiUrl = 'https://smart-epay.com/api/payments/transactions';
const apiKey = 'Your-API-Key-Here';
const data = {
    CurrencyCode: 'USD',
    Amount: 100,
    Desc: 'Description of the transaction',
    RedirectUrl: 'https://example.com/redirect-after-payment'
};

fetch(apiUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify(data)
})
.then(response => {
    return response.json(); // or response.text() if the server responds with plain text
})
.then(data => {
    console.log('Success:', data);  
    // Action to take upon successful response
    // For example, redirecting the user to the payment page
    location.assign(data.paymentUrl);
})
.catch(error => {
    console.error('Error:', error.message);
});

شرح الكود:

استبدال القيم: استبدل apiUrl بالرابط الفعلي لل-API، و apiKey بالمفتاح الخاص بك الذي قمت بإنشائه.
إرسال الطلب: قم بتحديد طريقة الإرسال باستخدام method: 'POST'. في الـheaders، أرسل المفتاح الخاص بك وتأكد من إرسال البيانات كـ JSON.
البيانات المطلوبة: في الـbody, يتم تحديد البيانات التي ترغب بإرسالها كالتالي:
```
{
  CurrencyCode: 'USD',
  Amount: 100,
  Desc: 'Description of the transaction',
  RedirectUrl: 'https://example.com/redirect-after-payment'
}
```
قم باستبدال البيانات بما يناسب طلبك، مثل العملة، المبلغ، الوصف، ورابط التحويل بعد الدفع.
معالجة الاستجابة: عند تلقي الرد بنجاح، يمكنك تحديد ما ترغب به، مثل تحويل المستخدم إلى صفحة الدفع باستخدام location.assign(data.paymentUrl)، وذلك استنادًا إلى البيانات التي تلقيتها من ال-API.

بعد إرسال الطلب بنجاح، سيقوم النظام بإعادة رد محتوي رابط الدفع إذا تمت العملية كما هو متوقع. على سبيل المثال:

{
  "success": true,
  "paymentUrl": "https://smart-epay.com/api/payments/Transaction Id/pay"
}

إذا واجهت أي مشاكل، سيقدم النظام رسالة خطأ توضح السبب. مثلاً، إذا كان المفتاح غير صالح أو لم يتم إرساله بشكل صحيح، قد يكون الرد كالتالي:

{
    "success": false,
    "errorMessage": "Invalid ApiKey"
}

تأكد من استبدال الـ URL والبيرر توكن بالقيم الفعلية المستخدمة في نظامك قبل البدء بإرسال الطلبات.

للحصول على قائمة المعاملات، يجب أن ترسل طلب من النوع POST مع المفتاح الخاص بال API في الرأس إلى العنوان التالي:

POST /api/payments/transactions/list

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiUrl = "<%=Domain/api/payments/transactions/list";
        String apiKey = "Your-API-Key";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(apiUrl))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(BodyPublishers.noBody())
            .build();

        HttpResponse response = client.send(request, BodyHandlers.ofString());
        System.out.println(response.statusCode() == 200 ? "Success: " + response.body() : "Error: " + response.statusCode());
    }
}

import requests

api_url = "https://smart-epay.com/api/payments/transactions/list"
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer Your-API-Key'
}

response = requests.post(api_url, headers=headers)
if response.status_code == 200:
    print('Success:', response.json())
else:
    print('Error:', response.status_code)

$apiUrl = '<%=Domain/api/payments/transactions/list';
$headers = array(
    'Content-Type: application/json',
    'Authorization: Bearer Your-API-Key'
);

$options = array('http' => array(
    'method' => 'POST',
    'header' => implode("\r\n", $headers)
));

$context = stream_context_create($options);
$response = file_get_contents($apiUrl, false, $context);
if ($response !== false) {
    echo 'Success: ' . $response;
} else {
    echo 'Error in request';
}

مثال على الطلب باستخدام JavaScript:

const apiUrl = 'https://smart-epay.com/api/payments/transactions/list';
const apiKey = 'Your-API-Key';

fetch(apiUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    }
})
.then(response => response.json())
.then(data => {
    console.log('Success:', data);
})
.catch(error => {
    console.error('Error:', error.message);
});

### أمثلة باللغات المختلفة لاستخدام الAPI لاستعلام قائمة المعاملات عبر POST

شرح الكود:

استبدال القيم: استبدل apiUrl وYour-Api-Key-Id بالرابط الفعلي لل-API والمفتاح الخاص بك.
إرسال الطلب: تأكد من أن طريقة الإرسال هي POST وأنك ترسل المفتاح الخاص بك في الرأس.
معالجة الاستجابة: عند تلقي الرد، يمكنك معالجة البيانات المسترجعة أو إدارة الأخطاء إذا واجهت أيًا منها.

بعد إرسال الطلب بنجاح، سيقوم النظام بإعادة قائمة المعاملات. على سبيل المثال:

{
  "success": true,
  "transactions": [
    {
      "TransactionId": "123",
      "Amount": 100,
      "CurrencyCode": "USD",
      "Status": "Completed"
    },
    {
      "TransactionId": "124",
      "Amount": 150,
      "CurrencyCode": "EUR",
      "Status": "Pending"
    }
  ]
}

إذا واجهت أي مشاكل، سيقدم النظام رسالة خطأ توضح السبب.

للحصول على حالة معاملة محددة، يجب أن ترسل طلب من النوع POST مع معرف المعاملة في جسم الطلب والمفتاح الخاص بال API في الرأس إلى العنوان التالي:

POST /api/payments/transactions/status

فيما يلي البيانات التي يجب أن تتضمنها في جسم الطلب:

{
  "TransactionId": "Your-Transaction-Id"
}

مثال على الطلب باستخدام JavaScript:

### أمثلة باللغات المختلفة لاستخدام الAPI لاستعلام حالة المعاملة عبر POST

const apiUrl = 'https://smart-epay.com/api/payments/transactions/status';
        const apiKey = 'Your-API-Key';
        const data = {
            TransactionId: 'Your-Transaction-Id'
        };
        
        fetch(apiUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify(data)
        })
        .then(response => response.json())
        .then(data => {
            console.log('Success:', data);
        })
        .catch(error => {
            console.error('Error:', error.message);
        });

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiUrl = "<%=Domain/api/payments/transactions/status";
        String apiKey = "Your-API-Key";
        String json = "{\"TransactionId\":\"Your-Transaction-Id\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(apiUrl))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(BodyPublishers.ofString(json))
            .build();

        HttpResponse response = client.send(request, BodyHandlers.ofString());
        System.out.println(response.statusCode() == 200 ? "Success: " + response.body() : "Error: " + response.statusCode());
    }
}

import requests

api_url = "https://smart-epay.com/api/payments/transactions/status"
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer Your-API-Key'
}
data = {
    "TransactionId": "Your-Transaction-Id"
}

response = requests.post(api_url, headers=headers, json=data)
if response.status_code == 200:
    print('Success:', response.json())
else:
    print('Error:', response.status_code)

$apiUrl = '<%=Domain/api/payments/transactions/status';
$apiKey = 'Your-API-Key';
$data = array('TransactionId' => 'Your-Transaction-Id');
$jsonData = json_encode($data);
$options = array('http' => array(
    'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiKey",
    'method' => 'POST',
    'content' => $jsonData
));
$context = stream_context_create($options);
$response = file_get_contents($apiUrl, false, $context);
if ($response !== false) {
    echo 'Success: ' . $response;
} else {
    echo 'Error in request';
}

عند إرسال طلب لاستعلام حالة المعاملة، النظام يستجيب بأحد الأشكال التالية بناءً على نتيجة الطلب:

أمثلة على الاستجابات:

إذا كانت البيانات المرسلة صحيحة وتم العثور على المعاملة:

{
  "success": true,
  "status": "Completed" // "Pending", "Completed", أو "Failed"
}

إذا كان هناك خطأ في معرف المعاملة أو لم يتم العثور على المعاملة:

{
  "success": false,
  "errorMessage": "invalid TransactionId or request"
}

إذا كانت هناك مشكلة في المفتاح الخاص بالAPI أو معرف المعاملة غير صحيح:

{
  "success": false,
  "errorMessage": "invalid api key "
}

تأكد من معالجة كل من هذه الاستجابات بشكل مناسب في تطبيقك لضمان تجربة مستخدم سلسة وفعالة.

إذا واجهت أي مشكلة، لا تتردد في التواصل معنا عبر البريد الإلكتروني: [email protected]

طريقة استخدام الAPI لإنشاء عملية دفع

كيفية استخدام الAPI لإنشاء معاملات الدفع

شرح الكود:

طريقة استخدام الAPI لاستعلام قائمة المعاملات

مثال على الطلب باستخدام JavaScript:

شرح الكود:

طريقة استخدام الAPI لاستعلام حالة المعاملة

مثال على الطلب باستخدام JavaScript:

أمثلة على الاستجابات: