توثيق المطورين — واجهة برمجة تكامل التجار من India Payme

نظرة عامة

تقدّم India Payme للتجار قدرتين أساسيتين في المعاملات: التحصيل (Payin) — تحصيل المبالغ من المستخدم النهائي نيابة عن التاجر؛ والدفع (Payout) — تحويل الأموال إلى حساب محدد نيابة عن التاجر. جميع الواجهات الخارجية تُستدعى عبر POST بصيغة JSON، ويجب أن تتضمن توقيعًا للواجهة البرمجية (API). بعد معالجة الطلب، تُرسل المنصة إشعارًا غير متزامن إلى التاجر، كما تتيح إمكانية الاستعلام اليدوي عن حالة الطلب.

الوظيفة	الطريقة	المسار
إنشاء طلب تحصيل	POST	`/transaction/payin/v1/apply`
الاستعلام عن طلب تحصيل	POST	`/transaction/payin/v1/query`
إنشاء طلب دفع	POST	`/transaction/payout/v1/apply`
الاستعلام عن طلب دفع	POST	`/transaction/payout/v1/query`
الاستعلام عن الرصيد	POST	`/transaction/payout/v1/balance`

العنوان الأساسي (يُرجى الاعتماد على نطاق بوابة الإنتاج الذي تقدّمه المنصة بعد فتح الحساب):

https://{نطاق البوابة}

التحضير للتكامل

سجّل الدخول إلى لوحة تحكم التاجر ← مفاتيح التطبيق، حيث يمتلك كل تطبيق زوجًا من بيانات الاعتماد: appKey وappSecret. علمًا بأن appKey هو نفسه ترويسة الطلب appId؛ أما appSecret فهو مفتاح التوقيع، ويُستخدم فقط لحساب التوقيع محليًا، ولا يُرسل ضمن الطلب.

يجب أن تحتوي جميع الطلبات على ترويسات HTTP التالية، مع تعيين Content-Type إلى application/json:

Header	إلزامي	الوصف
`appId`	نعم	معرّف تطبيق التاجر (وهو appKey)
`timestamp`	نعم	طابع زمني Unix بالمللي ثانية
`nonce`	نعم	سلسلة عشوائية، لا تقل عن 10 خانات، تُستخدم مرة واحدة فقط ولا يمكن إعادة استخدامها
`sign`	نعم	التوقيع المحسوب وفق القواعد الموضحة في القسم التالي

قواعد التوقيع

خوارزمية التوقيع هي SHA-256 مباشرةً (بصيغة سداسية عشرية بأحرف صغيرة)، وليست HMAC. يُضاف appSecret مباشرة في نهاية السلسلة المراد توقيعها، ثم تُحسب قيمة SHA-256 للسلسلة الناتجة. الخطوات:

اجمع «الحقول العلوية من جسم الطلب (غير الفارغة فقط)» مع «ترويسات التوقيع appId وtimestamp وnonce» في خريطة (Map) واحدة (لا يشارك sign نفسه في هذه العملية)؛
رتّب أسماء المعاملات تصاعديًا وفق ترميز ASCII، وادمجها بصيغة key1=value1&key2=value2…؛
أضف appSecret مباشرة في النهاية (دون أي فاصل)، ثم احسب SHA-256 بصيغة سداسية عشرية بأحرف صغيرة للسلسلة الكاملة للحصول على sign.

# السلسلة المراد توقيعها
signString = "key1=value1&key2=value2…&keyN=valueN" + appSecret
sign = SHA256_HEX(signString)   // سداسي عشري بأحرف صغيرة

مدة الصلاحية ومنع إعادة التشغيل:

صلاحية الطابع الزمني 30 ثانية: |وقت الخادم − timestamp| ≤ 30s، وفي حال التجاوز يُعاد timestamp has expired. يُرجى التأكد من مزامنة الساعة (NTP) بين العميل والبوابة.
منع إعادة التشغيل عبر nonce: لا يمكن استخدام نفس الـ nonce إلا مرة واحدة، وتكراره يؤدي إلى الخطأ nonce has been used (رمز الخطأ 900).
الحقول ذات القيمة الفارغة لا تشارك في التوقيع — يجب أن تتطابق «مجموعة الحقول المشمولة بالتوقيع» تمامًا مع «حقول JSON المُرسلة فعليًا».

مثال على التوقيع بلغة Node.js:

const crypto = require('crypto');

function buildSign(appId, appSecret, timestamp, nonce, body) {
  const params = { ...body, appId, timestamp, nonce };
  const signString = Object.keys(params)
    .filter(k => params[k] !== null && params[k] !== undefined)
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&') + appSecret;
  return crypto.createHash('sha256').update(signString, 'utf8').digest('hex');
}

إنشاء طلب تحصيل POST

POST /transaction/payin/v1/apply — ينشئ طلب تحصيل ويعيد رابط صفحة الدفع payUrl لتوجيه المستخدم لإتمام عملية الدفع.

الحقل	النوع	إلزامي	الوصف
`merchantOrderNo`	string	نعم	رقم طلب التاجر، ويجب ألا يتكرر
`amount`	number	نعم	مبلغ الطلب، رقم عشري (مثل `100.02`)
`name`	string	نعم	اسم المستخدم. بأحرف إنجليزية فقط، لا يقل عن 3 أحرف، يمكن أن يحتوي على مسافات، دون رموز أو أرقام
`phone`	string	نعم	رقم الجوال
`email`	string	نعم	البريد الإلكتروني
`currency`	string	نعم	العملة: `INR` / `PKR` / `USDT` / `BDT`
`product`	string	نعم	رمز منتج الدفع، تُصدره المنصة وفق اتفاقية التعاقد
`notifyUrl`	string	لا	عنوان الإشعار غير المتزامن؛ في حال عدم إرساله تُستخدم عنوان الإشعار الافتراضي للتاجر
`returnUrl`	string	لا	صفحة إعادة التوجيه بعد نجاح الدفع
`payType`	string	لا	طريقة الدفع المباشر عبر المحفظة: `JAZZCASH` / `EASYPAISA` / `BKASH` / `NAGAD`

POST /transaction/payin/v1/apply
{
  "merchantOrderNo": "ORD1751731200123",
  "amount": "600.00",
  "currency": "INR",
  "product": "{رمز المنتج}",
  "name": "John Doe",
  "phone": "9910099100",
  "email": "john@example.com",
  "notifyUrl": "https://shop.example/pay/notify"
}

// الاستجابة
{
  "code": 0,
  "msg": "Success",
  "data": {
    "orderNo": "P1751731200999",
    "merchantOrderNo": "ORD1751731200123",
    "amount": 600,
    "currency": "INR",
    "payUrl": "https://{نطاق صفحة الدفع}/cashier/xxxx",
    "payStatus": 0
  }
}

بعد الحصول على payUrl، وجّه المستخدم للانتقال إليه لإتمام الدفع، وتُعتمد الإشعارات غير المتزامنة كمرجع نهائي للنتيجة.

إنشاء طلب دفع POST

POST /transaction/payout/v1/apply — يبدأ عملية دفع إلى حساب محدد. معالجة غير متزامنة: تقوم الواجهة أولًا بالتحقق من الحساب وتجميد المبلغ، ثم تُطابق القناة المناسبة للدفع بشكل غير متزامن، وعادة ما تكون الاستجابة الأولية payStatus=0 (تم القبول)، وتُعتمد نتيجة الاستعلام أو الإشعار كحالة نهائية.

الحقل	النوع	إلزامي	الوصف
`merchantOrderNo`	string	نعم	رقم طلب التاجر
`amount`	number	نعم	مبلغ الدفع، الحد الأدنى 100.00
`accountName`	string	نعم	اسم المستفيد. بأحرف إنجليزية فقط، لا يقل عن 3 أحرف، يمكن أن يحتوي على مسافات
`account`	string	نعم	رقم حساب المستفيد
`phone`	string	نعم	رقم الجوال
`email`	string	نعم	البريد الإلكتروني
`currency`	string	نعم	العملة: `INR` / `PKR` / `USDT` / `BDT`
`bizCode`	string	نعم	نوع عملية الدفع: `IMPS` / `UPI` / `BANK` / `JAZZCASH` / `EASYPAISA` / `BKASH` / `NAGAD` / `ECARD`
`payCode`	string	نعم	طريقة الدفع: `CARD` / `WALLET` / `NBK` / `ITT` / `VC`
`branchCode`	string	نعم	رمز التسوية: بالنسبة للهند أدخل IFSC؛ ولباكستان أدخل bankcode؛ ولبنغلاديش يُحدَّد وفق bizCode
`product`	string	نعم	رمز منتج الدفع، تُصدره المنصة
`bankName`	string	لا	اسم البنك
`swiftCode`	string	لا	رمز SWIFT (يُستخدم مع التحويل البرقي الدولي ITT)

POST /transaction/payout/v1/apply
{
  "merchantOrderNo": "PO1751731200123",
  "amount": "1500.00",
  "currency": "INR",
  "product": "{رمز المنتج}",
  "accountName": "John Doe",
  "account": "1234567890",
  "bizCode": "IMPS",
  "payCode": "NBK",
  "branchCode": "HDFC0000001",
  "bankName": "HDFC",
  "phone": "9910099100",
  "email": "john@example.com"
}

الاستعلام عن الطلبات POST

للتحصيل POST /transaction/payin/v1/query، وللدفع POST /transaction/payout/v1/query. مرِّر merchantOrderNo أو orderNo لتحديد الطلب. الحد الأقصى 5 طلبات/ثانية.

POST /transaction/payin/v1/query
{ "merchantOrderNo": "ORD1751731200123" }

// بيانات الاستجابة (data)
{
  "orderNo": "P1751731200999",
  "merchantOrderNo": "ORD1751731200123",
  "amount": 600,
  "realAmount": 600,
  "currency": "INR",
  "payStatus": 1        // 0 قيد المعالجة / 1 تم التحصيل / -1 ملغى
}

الاستعلام عن الرصيد POST

POST /transaction/payout/v1/balance — للاستعلام عن رصيد حساب التاجر. الحد الأقصى 5 طلبات/ثانية.

POST /transaction/payout/v1/balance
{ "currency": "INR" }

// بيانات الاستجابة (data)
{
  "accountNo": "ACC0001",
  "currency": "INR",
  "balance": 100000.00,       // الرصيد الإجمالي
  "balanceActive": 98500.00,  // الرصيد المتاح
  "balanceFreeze": 1500.00    // الرصيد المجمَّد
}

الإشعارات غير المتزامنة

عند وصول الطلب إلى حالته النهائية، تُرسل المنصة إشعارًا عبر POST (بصيغة JSON) إلى notifyUrl الخاص بالتاجر (وفي حال عدم إرساله يُستخدم العنوان الافتراضي للتاجر)، مصحوبًا بنفس ترويسات التوقيع (appId/timestamp/nonce/sign). ويجب على التاجر إعادة حساب التوقيع بنفس القواعد باستخدام appSecret الخاص به ومطابقته للتحقق من صحة الإشعار.

رسالة إشعار التحصيل تتضمن: merchantOrderNo، orderNo، currency، product، amount، realAmount، status (القيمة "1" تعني نجاح التحصيل). أما إشعار الدفع فيتضمن إضافة إلى ذلك utr (الرقم المرجعي المصرفي) وstatusDes (وصف الحالة)، حيث تكون status إما "1" للنجاح أو "2" للفشل.

// مثال على جسم إشعار التحصيل
{
  "merchantOrderNo": "ORD1751731200123",
  "orderNo": "P1751731200999",
  "currency": "INR",
  "product": "{رمز المنتج}",
  "amount": "600.00",
  "realAmount": "600.00",
  "status": "1"
}

يجب أن يُعيد التاجر نصًا صرفًا يحتوي على OK أو success (دون تمييز حالة الأحرف). وإلا تدخل المنصة في طابور إعادة المحاولة: بحد أقصى 5 مرات، بفواصل زمنية متزايدة بالدقائق (1 / 2 / 5 / 10 / 30 / 60 / 120). لذلك يجب أن تضمن واجهة التاجر خاصية الاتساق عند التكرار (idempotency) (قد يُرسل نفس orderNo أكثر من مرة).

حالات الطلب

يعتمد تكامل التاجر على الحالات الخارجية التالية (بينما آلة الحالة الداخلية أكثر تفصيلًا ولا تُعرض مباشرة):

السيناريو	الحقل	القيم الممكنة
استجابة قبول الطلب	`payStatus`	`0` تم الإنشاء / `1` ناجح / `2` فاشل / `3` ملغى
الاستعلام عن طلب تحصيل	`payStatus`	`0` قيد المعالجة / `1` تم التحصيل / `-1` ملغى
الاستعلام عن طلب دفع	`payStatus`	`0` بانتظار الدفع / `1` تم الدفع / `-1` ملغى
الإشعار غير المتزامن	`status`	نجاح التحصيل `"1"`؛ الدفع: `"1"` نجاح / `"2"` فشل

رموز الأخطاء

عندما يكون code != 0 في نص الاستجابة فهذا يعني الفشل، وتوضّح msg رسالة الخطأ. أشيع رموز الأخطاء التجارية:

code	الوصف
`0`	نجاح
`400`	خطأ في المعاملات / فشل التحقق من التوقيع (Sign invalid)
`900`	طلب مكرر / إعادة استخدام nonce
`10000` / `10001`	التطبيق غير موجود / التطبيق غير متاح
`10002`	العملة غير مدعومة
`10003` / `10007`	التاجر غير متاح / حساب التاجر غير متاح
`10004`	المنتج غير مفعّل أو انتهت صلاحية الاتفاقية
`10005` / `10009`	لا توجد قناة متاحة حاليًا / القناة غير متاحة مؤقتًا
`10008`	رصيد الحساب غير كافٍ
`10010`	عنوان IP غير مدرج في القائمة البيضاء
`10011` / `10012`	المنتج غير صالح / طريقة الدفع غير صالحة
`10020`	رقم طلب التاجر مكرر
`30001` / `30002`	رقم الطلب غير صحيح / العملة غير صحيحة أو الحساب غير مفعّل

مثال كامل لسير التكامل

على سبيل المثال، عملية التحصيل:

جهّز جسم الطلب التجاري (راجع حقول «إنشاء طلب تحصيل»).
أنشئ timestamp (بالمللي ثانية) وnonce (سلسلة عشوائية لا تقل عن 10 خانات).
احسب sign وفق «قواعد التوقيع».
أرسل طلب POST /transaction/payin/v1/apply مع ترويسات التوقيع الأربع + جسم JSON.
إذا كانت code==0 فاستخدم data.payUrl لتوجيه المستخدم لإتمام الدفع.
استمع للإشعارات غير المتزامنة؛ ويمكن أيضًا الاستعلام يدويًا للتحقق من الحالة النهائية.
عند استلام الإشعار، تحقق من التوقيع، ونفّذ المعالجة التجارية، ثم أعد نصًا صرفًا بقيمة OK.

ملاحظة: تتطابق مسارات الواجهات والحقول ورموز الحالة في هذا الدليل مع التطبيق الفعلي في الإنتاج؛ أما نطاق بوابة الإنتاج ورموز product المتاحة وسياسة القائمة البيضاء لعناوين IP وغيرها، فتُعتمد وفق ما تقدّمه المنصة بعد فتح الحساب.

واجهة برمجية للتحصيل والدفع، تكامل في خطوات قليلة