المصادقة
أرسل بيانات WHGPG الخاصة بك مع كل طلب API باستخدام الترويسات التالية.
X-WHGPG-Unique-ID: WHGPG-U-...
X-WHGPG-API-Hash: whgpg_hash_...
لا تعرض API Hash داخل JavaScript في المتصفح أو في كود عام.
تتضمن كل استجابة API ترويسة X-WHGPG-Request-ID لتتبع الطلب عند الدعم أو داخل سجل التاجر.
X-WHGPG-Request-ID: 550e8400-e29b-41d4-a716-446655440000
إنشاء عملية دفع
POST https://www.whgpg.odwyah.com/api/v1/payments
curl -X POST https://www.whgpg.odwyah.com/api/v1/payments \
-H "Accept: application/json" \
-H "X-WHGPG-Unique-ID: WHGPG-U-2608-XXXXXXXXXX" \
-H "X-WHGPG-API-Hash: whgpg_hash_YOUR_SECRET" \
-H "Idempotency-Key: ORDER-1001" \
-d "amount=1.000" \
-d "reference=ORDER-1001" \
-d "return_url=https://merchant.example/payment/return"
حقول اختيارية
| الحقل | الوصف |
|---|
description | وصف يظهر مع عملية الدفع. |
webhook_url | رابط HTTPS خاص بهذه العملية. إذا ترك فارغاً يستخدم رابط Webhook المسجل للتاجر. |
payment_method | benefitpay, benefit, card, apple_pay |
customer[name] | بيانات العميل اختيارية، كما يدعم email وmobile وcountry وcity وaddress. |
الاستجابة
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"id": "PAY-20260830-XXXXXXX",
"status": "pending",
"amount": "1.000",
"currency": "BHD",
"payment_url": "https://whgpg.odwyah.com/sandbox/payment/SBX-...",
"idempotent_replay": false
}
وجّه العميل إلى payment_url ولا تعتبر الطلب مدفوعاً اعتماداً على رجوع المتصفح وحده.
Idempotency
أرسل Idempotency-Key فريداً لكل طلب لدى التاجر. إعادة نفس الطلب بنفس المفتاح تعيد نفس عملية WHGPG ولا تنشئ خصماً جديداً.
Idempotency-Key: ORDER-1001
إعادة المحاولة الآمنة ترجع idempotent_replay=true مع نفس رقم ورابط الدفع.
{
"success": true,
"id": "PAY-20260830-XXXXXXX",
"status": "pending",
"idempotent_replay": true
}
إذا استُخدم نفس المفتاح مع بيانات دفع مختلفة يرفض WHGPG الطلب برمز HTTP 409.
الاستعلام عن حالة الدفع
GET https://www.whgpg.odwyah.com/api/v1/payments/PAY-20260830-XXXXXXX
curl https://www.whgpg.odwyah.com/api/v1/payments/PAY-20260830-XXXXXXX \
-H "Accept: application/json" \
-H "X-WHGPG-Unique-ID: YOUR_UNIQUE_ID" \
-H "X-WHGPG-API-Hash: YOUR_API_HASH"
الاستجابة
{
"success": true,
"id": "PAY-20260830-XXXXXXX",
"status": "completed",
"amount": "1.000",
"currency": "BHD",
"processor": "sandbox",
"processor_environment": "test",
"settlement_status": "settled",
"refunded_amount": "0.000"
}
Webhooks
يرسل WHGPG طلب JSON موقعاً بعد وصول دفعة API إلى حالة نهائية.
{
"event": "payment.completed",
"merchant_id": "WHGPG-M-2608-XXXXXX",
"payment_id": "PAY-20260830-XXXXXXX",
"reference": "ORDER-1001",
"status": "completed",
"amount": "1.000",
"currency": "BHD",
"payment_method": "benefitpay",
"transaction_id": "SBX-TXN-...",
"invoice_id": "SBX-INV-...",
"processor": "sandbox",
"settlement_status": "settled",
"refunded_amount": "0.000",
"paid_at": "2026-08-30T15:54:54+03:00"
}
ترويسات Webhook
X-WHGPG-Event: payment.completed
X-WHGPG-Delivery-ID: 550e8400-e29b-41d4-a716-446655440000
X-WHGPG-Timestamp: 1788094494
X-WHGPG-Signature: sha256=...
تحقق من توقيع HMAC-SHA256 على timestamp ثم نقطة ثم نص الطلب الخام كما استلمته تماماً.
$signed = $timestamp . '.' . $rawRequestBody;
$expected = 'sha256=' . hash_hmac('sha256', $signed, $webhookSecret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_WHGPG_SIGNATURE'] ?? '');
لمنع إعادة الإرسال، ارفض التوقيتات القديمة واحفظ Delivery ID للطلبات التي تمت معالجتها.
أمثلة الربط
نزّل نموذج PHP مستقل لموقع التاجر أو استخدم أمثلة الربط من الخادم أدناه.
تنزيل نموذج تاجر PHP
Laravel / PHP
$response = Http::withHeaders([
'X-WHGPG-Unique-ID' => env('WHGPG_UNIQUE_ID'),
'X-WHGPG-API-Hash' => env('WHGPG_API_HASH'),
'Idempotency-Key' => 'ORDER-1001',
])->post('https://www.whgpg.odwyah.com/api/v1/payments', [
'amount' => '10.000',
'reference' => 'ORDER-1001',
'return_url' => 'https://merchant.example/payment/return',
]);
return redirect()->away($response['payment_url']);
JavaScript
احتفظ بـ Unique ID وAPI Hash في خادمك فقط ولا تعرضهما في JavaScript داخل المتصفح.
// Run this on your server, not in browser JavaScript.
const response = await fetch('https://www.whgpg.odwyah.com/api/v1/payments', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
'X-WHGPG-Unique-ID': process.env.WHGPG_UNIQUE_ID,
'X-WHGPG-API-Hash': process.env.WHGPG_API_HASH,
'Idempotency-Key': 'ORDER-1001'
},
body: JSON.stringify({amount:'10.000',reference:'ORDER-1001',return_url:'https://merchant.example/payment/return'})
});
Sandbox
يستخدم Sandbox نفس API ومسار الدفع بدون نقل أموال حقيقية.
BenefitPayBenefit debitVisa / MastercardApple Pay
طرق الدفع في Sandbox محاكاة فقط ولا يتم الاتصال ببنك أو شبكة بطاقات حقيقية.
استخدم Sandbox لاختبار الحالات النهائية وسلوك الربط قبل توصيل التحصيل الفعلي.
CompletedFailedCancelledWebhook retryIdempotency replay
حدود الاستخدام
يطبق WHGPG حدوداً منفصلة لكل تاجر في الدقيقة واليوم، وتوضح ترويسات الاستجابة المتبقي في حد الدقيقة.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Retry-After: 42
يمكن للإدارة تحديد الحدود لكل تاجر، ويحتوي HTTP 429 على Retry-After.
رموز حالة HTTP
{
"success": false,
"code": "INVALID_API_CREDENTIALS",
"message": "Invalid WHGPG API credentials.",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
| HTTP | Code | المعنى |
|---|
| 201 | - | تم إنشاء عملية الدفع بنجاح. |
| 401 | INVALID_API_CREDENTIALS | بيانات WHGPG مفقودة أو غير صحيحة. |
| 403 | MERCHANT_API_INACTIVE | API التاجر أو بوابة الدفع غير مفعلة. |
| 404 | PAYMENT_NOT_FOUND | عملية الدفع المطلوبة غير موجودة لهذا التاجر. |
| 409 | IDEMPOTENCY_KEY_REUSED | تم استخدام Idempotency-Key نفسه مع بيانات دفع مختلفة. |
| 422 | VALIDATION_ERROR | خطأ في البيانات أو وسيلة الدفع المطلوبة غير متاحة. |
| 429 | RATE_LIMIT_EXCEEDED | تم تجاوز حد استخدام API الخاص بالتاجر. |
| 502 | PROCESSOR_ERROR | تعذر على WHGPG إنشاء أو التحقق من الدفعة عبر المعالج المهيأ. |