moneywave

moneywave

مكتبة PHP لاستهلاك خدمات moneywave API.
يمكنك الاطلاع على الوثائق لمعرفة كل ما هو متاح: https://moneywave-doc.herokuapp.com/

• بداية سريعة
• مقدمة
• إعدادات
• الاستخدام
• خدمات
• التعامل مع الردود

بداية سريعة

للبدء، كل ما عليك فعله هو تثبيته عبر composer :

moneywave">

 $ composer require emmanix2002/ moneywave

سيؤدي ذلك إلى إضافته إلى composer.json الخاص بك وتثبيته باعتباره تابعًا للمشروع.

مقدمة

يتم عرض جميع الميزات والموارد المتوفرة في خدمة moneywave كخدمات . ومن ثم، لاستخدام أي من الخدمات، يجب أولاً إنشاؤها.

يتم عرض جميع الميزات والموارد الموجودة في واجهة برمجة تطبيقات moneywave كخدمات في هذه المكتبة.

نقطة الدخول إلى هذه المكتبة هي فئة moneywave .

moneywave = new moneywave ();">

 $ moneywave = new moneywave ();

سنناقش المزيد حول هذا الأمر لاحقًا.

إعدادات

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

• مفتاح واجهة برمجة التطبيقات
• المفتاح السري

يمكن أن يكون حسابك في إحدى الحالتين: Test أو Production . لكل حالة من هذه الحالات ، ستستخدم مفاتيح مختلفة.
هذه المفاتيح مطلوبة من قبل فئة moneywave (ويجب حمايتها - فهي تُستخدم لمصادقة حساب التاجر)؛ لاستخدامها مع هذه المكتبة، يمكنك استخدام إحدى الطريقتين الممكنتين.

متغيرات البيئة

يؤدي استخدام هذه الطريقة إلى تخزين المفتاح في ملف محدد على الخادم الخاص بك، مما يعني أن القيم لا يتم ترميزها ضمن التعليمات البرمجية الخاصة بك. تتوقع المكتبة العثور على ملف يسمى .env على نفس مستوى دليل vendor الملحن الخاص بك.

 .env
vendor/
composer.json
composer.lock

كما ترون أعلاه، يجب أن يكون ملف الإعداد على المستوى الموضح. يجب أن يكون محتوى الملف هو نفسه الذي يمكنك العثور عليه في .env.example كما يلي:

moneywave API key moneywave _API_KEY="your API key goes here" # your account moneywave Secret key moneywave _SECRET_KEY="your secret key goes here" # the environment - staging | production moneywave _ENV="staging"">

 # your account moneywave API key
moneywave _API_KEY="your API key goes here"
# your account moneywave Secret key
moneywave _SECRET_KEY="your secret key goes here"
# the environment - staging | production
moneywave _ENV="staging"

يجب تعيين هذه القيم لاستخدام المكتبة؛ مع القيام بذلك، يمكنك ببساطة الاتصال:

moneywave = new moneywave ();">

 $ moneywave = new moneywave ();

انتقل إلى المنشئ

الطريقة الثانية لتكوين عميل moneywave هي تمرير كافة الإعدادات إلى المُنشئ.
على عكس الطريقة الأولى ، ستحتاج إلى تخزين المفاتيح في مكان ما وتقديمها للعميل عند إنشاء مثيل لها.

moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment $ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);">

 $ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);

الاستخدام

عندما يتم إنشاء مثيل للعميل ( راجع التكوين)، فإنه يبدأ تشغيل خدمة VerifyMerchant تلقائيًا. تحصل هذه الخدمة على access token من خدمة moneywave الذي سيتم استخدامه لترخيص كل طلب آخر تقوم به مقابل واجهة برمجة التطبيقات (API).
عمر كل access token هو 2 hours . في طلبك، لديك أحد الخيارين:

• احفظ الرمز المميز المسترد في Session لاستخدامه عبر طلبات متعددة
• اسمح للمكتبة بطلب واحد لكل مكالمة يتم إجراؤها إلى واجهة برمجة التطبيقات (API).

بالنسبة للخيار الأول، قم بإلقاء نظرة على نماذج الملفات الموجودة في دليل examples . سترى شيئا مثل هذا:

moneywaveExceptionValidationException; use Emmanix2002 moneywave moneywave ; require(dirname(__DIR__).'/vendor/autoload.php'); session_start(); try { $accessToken = !empty($_SESSION['accessToken']) ? $_SESSION['accessToken'] : null; $mw = new moneywave ($accessToken); $_SESSION['accessToken'] = $mw->getAccessToken(); $query = $mw->createWalletBalanceService(); $response = $query->send(); var_dump($response->getData()); var_dump($response->getMessage()); } catch (ValidationException $e) { var_dump($e->getMessage()); }">

 use Emmanix2002 moneywave ExceptionValidationException;
use Emmanix2002 moneywave  moneywave ;

require(dirname(__DIR__).'/vendor/autoload.php');
session_start();

try {
    $accessToken = !empty($_SESSION['accessToken']) ? $_SESSION['accessToken'] : null;
    $mw = new moneywave ($accessToken);
    $_SESSION['accessToken'] = $mw->getAccessToken();
    $query = $mw->createWalletBalanceService();
    $response = $query->send();
    var_dump($response->getData());
    var_dump($response->getMessage());
} catch (ValidationException $e) {
    var_dump($e->getMessage());
}

وهذا يجعل من الممكن استخدام نفس access token لطلب آخر من نفس الجهاز.

خدمات

بعد إنشاء مثيل لكائن moneywave ، اتبع الخطوات التالية لاستخدام الخدمة:

• قم بإنشاء مثيل للخدمة المطلوبة منه عن طريق استدعاء إحدى طرق create*Service()
• قم بتعيين الخصائص على كائن الخدمة
• استدعاء طريقة send() على كائن الخدمة الذي تم إنشاؤه.

يتم تعيين كل ميزة ومورد لخدمة ما؛ يمكن استنتاج التعيينات بسهولة من اسم الفئة .
ويوضح الجدول أدناه كافة الخدمات:

اسم الفئة	مكالمة الخدمة
التحقق من صحة رقم الحساب	createAccountNumberValidationService
AccountToAccount	createAccountToAccountService
AccountToWallet	createAccountToWalletService
نقل الحساب	createAccountTransferService
البنوك	createBanksService
حساب CardToBank	createCardToBankAccountService
ترميز البطاقة	createCardTokenizationService
CardToWallet	createCardToWalletService
نقل البطاقة	createCardTransferService
صرف	createDisburseService
DisburseBulk	createDisburseBulkService
InternetBankingToWallet	createInternetBankingToWalletService
QueryCardToAccountTransfer	createQueryCardToAccountTransfer
الاستعلام عن الصرف	createQueryDisbursementService
إعادة محاولة النقل الفاشلة	createRetryFailedTransferService
TotalChargeToCard	createTotalChargeToCardService
التحقق من صحة بطاقة النقل	createValidateCardTransferService
التحقق من صحة النقل	createValidateTransferService
VerifyMerchant	createVerifyMerchantService
WalletBalance	createWalletBalanceService

تحتوي كل خدمة على قائمة بالخصائص التي يجب تعيينها عليها قبل إرسالها إلى واجهة برمجة التطبيقات (API)؛ إذا لم يتم تعيين واحدة أو أكثر من هذه الخصائص، فسيؤدي استدعاء send() إلى طرح ValidationException .
لنستخدم مورد Account Number validation API كمثال:
من الوثائق، الخصائص التالية مطلوبة:

اسم الحقل	وصف
account_number	رقم حساب المرسل
Bank_code	رمز البنك للحساب لحلها

لاستخدام المكتبة، سنفعل شيئًا مثل هذا:

moneywave = new moneywave (); $accountValidation = $ moneywave ->createAccountNumberValidationService(); $accountValidation->account_number = '0690000004'; $accountValidation->bank_code = Banks::ACCESS_BANK; $response = $accountValidation->send();">

 $ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();

إذا لم يتم تعيين أحد هذه الحقول على كائن الخدمة ، فسيتم طرح استثناء ValidationException .

يمكن تعيين كل حقل محدد ضمن وثائق moneywave (لخدمة ما) كخاصية على كائن الخدمة الذي تم إنشاؤه.

الحقول الخاصة

هناك حقول معينة خاصة، ولا تحتاج إلى تعيينها بواسطتك (على الرغم من أنه يمكنك اختيار تعيينها)؛ سيتم منحهم القيمة المطلوبة تلقائيًا بواسطة المكتبة. تجدها مدرجة أدناه:

مجال	وصف
com.apiKey	سيتم تعيين هذا على مفتاح API المستخدم لإنشاء كائن moneywave
سر	سيتم تعيين هذا على المفتاح السري المستخدم لكائن moneywave
مصاريف	تم ضبطه افتراضيًا على 0
متلقي	بالنسبة إلى createCardToWalletService ، يتم تعيين هذا على wallet افتراضيًا
عملة	يتم ضبطها تلقائيًا على Currency::NAIRA

خدمات خاصة

مثلما توجد حقول خاصة، هناك أيضًا بعض كائنات الخدمة الخاصة، التي تقدم أكثر من الطريقة العادية: send() .

التحويلات ( createCardToBankAccountService() ، createCardToWalletService() )

تعتبر خدمات النقل هذه مميزة لأنها في معظم الأحيان تكون ثنائية . وهي تنطوي على الخطوات التالية:

1 مرحلة النقل 2 مرحلة التحقق

تعمل هذه الخطوات واحدة تلو الأخرى؛ ويجب إكمال كلا الخطوتين لإتمام عملية النقل.
هناك خدمتان تهتمان بجزء validation ؛ هم:

• createValidateCardTransferService() : يسمح لك بالتحقق من صحة البطاقة إلى المحفظة أو تحويل البطاقة إلى الحساب الذي تم إجراؤه باستخدام بطاقة الخصم Verve
• createValidateTransferService() : يسمح لك بالتحقق من صحة البطاقة إلى المحفظة أو تحويل البطاقة إلى الحساب الذي تم إجراؤه باستخدام الحساب. وهذا يعني أنه تم تعيين الحقل Charge_with على ChargeMethod::ACCOUNT .

لذا، عندما تتلقى استجابة ناجحة من واجهة برمجة التطبيقات (API) بعد المرحلة الأولى ؛ تبدأ ساق التحقق.

ملاحظة : بالنسبة لعمليات نقل بطاقات Mastercard وVisa، ستتلقى مفتاح authurl في استجابة API الناجحة؛ يجب عليك إعادة التوجيه إلى عنوان URL هذا حتى يتمكن الدافع من التحقق من صحة التحويل. بعد النجاح أو الفشل، ستتم إعادة توجيه الدافع مرة أخرى إلى عنوان URL المحدد في حقل redirecturl لطلب النقل.

createDisburseBulkService()

هذه الخدمة مخصصة لصرف النقود من محفظة moneywave الخاصة بك إلى حسابات بنكية متعددة. لديها طريقة خاصة لإضافة حسابات beneficiary الفردية.

 addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);

تسمح لك هذه الطريقة بإضافة كل حساب مستفيد على حدة:

moneywave->createDisburseBulkService(); $bulkDisbursement->lock = 'wallet password'; $bulkDisbursement->ref = 'unique reference'; # suggestion: you could use a UUID; check out ramsey/uuid package $bulkDisbursement->senderName = ' moneywave SDK'; $bulkDisbursement->addRecipient(Banks::ACCESS_BANK, '0690000004', 1) ->addRecipient(Banks::ACCESS_BANK, '0690000005', 2);">

 $bulkDisbursement = $ moneywave ->createDisburseBulkService();
$bulkDisbursement->lock = 'wallet password';
$bulkDisbursement->ref = 'unique reference';    # suggestion: you could use a UUID; check out ramsey/uuid package
$bulkDisbursement->senderName = ' moneywave SDK';
$bulkDisbursement->addRecipient(Banks::ACCESS_BANK, '0690000004', 1)
                 ->addRecipient(Banks::ACCESS_BANK, '0690000005', 2);

انظر إلى ملف examples/disburse_bulk.php للحصول على المثال الكامل.

التعامل مع الردود

إذا تم تعيين جميع الحقول المطلوبة في كائن الخدمة (انظر الخدمات)، فسيؤدي استدعاء send() إلى إرجاع كائن استجابة وهو مثيل لفئة moneywave Response .
الاستمرار في مثال التحقق من صحة الحساب أعلاه:

 $response = $accountValidation->send();

ستكون استجابة JSON الناجحة بهذا النموذج:

 {
    status: "success",
    data: {
        name: "MICHAEL JACKSON"
    }
}

بينما ستكون استجابة الفشل JSON بالشكل:

 {
    status: "error",
    message: "error message description",
    code: "error code string; e.g. INVALID_ID",
    data: "data string -- this is absent most of the time"
}

يقدم متغير $response بعض الوظائف التي يمكن استخدامها للتعامل مع هذه البيانات:

 # was a request successful?
if ($response->isSuccessful()) {
    # do something with the returned data
    $name = $response->getData()['name'];
} else {
    # this was a failure
    $message = $response->getMessage();
    $code = $response->getCode();
    $data = $response->getData();
}

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

 if ($response->isSuccessful()) {
    $name = $response->getData()['name'];
} else {
    $message = $response->message;
    $code = $response->code;
}

وكمثال آخر، تبدو الاستجابة من خدمة VerifyMerchant كما يلي:

 {
    status: "success",
    token: "" // a valid merchant token
}

باستخدام الرد، سيتعين عليك القيام بذلك:

 $response = $verifyService->send();
if ($response->isSuccessful()) {
    $token = $response->token;
} else {
    # process the error response as you normally would
}

يصف الجدول أدناه الطرق المحددة في كائن moneywave Response :

طريقة	نوع الإرجاع	وصف
getRawResponse()	خيط	استجابة JSON من API
ناجح ()	منطقي	يتحقق مما إذا كان مفتاح status === "success"
الحصول على كود ()	خيط	إرجاع مفتاح code
الحصول على رسالة ()	خيط	إرجاع سمة message
الحصول على البيانات ()	صفيف	إرجاع مفتاح data

ملاحظة : بالنسبة للاستجابات التي تكون فيها data عبارة عن سلسلة؛ تقوم بإرجاع هذه المصفوفة [data: string]