moneywave

moneywave

ไลบรารี PHP สำหรับการใช้บริการ moneywave API
คุณสามารถตรวจสอบเอกสารเพื่อดูทั้งหมดที่มีอยู่: https://moneywave-doc.herokuapp.com/

• เริ่มต้นอย่างรวดเร็ว
• การแนะนำ
• การกำหนดค่า
• การใช้งาน
• บริการ
• การจัดการกับคำตอบ

เริ่มต้นอย่างรวดเร็ว

ในการเริ่มต้น คุณเพียงแค่ต้องติดตั้งผ่าน composer :

 $ composer require emmanix2002/ moneywave

สิ่งนี้จะเพิ่มลงใน composer.json ของคุณและติดตั้งเป็นการพึ่งพาโปรเจ็กต์

การแนะนำ

คุณสมบัติ และ ทรัพยากร ทั้งหมดที่มีอยู่ในบริการ moneywave จะถูกเปิดเผยเป็น บริการ ดังนั้นหากต้องการใช้บริการใดๆ จะต้องสร้างขึ้นก่อน

คุณลักษณะและทรัพยากรทั้งหมดบน moneywave API ได้รับการเปิดเผยเป็นบริการในไลบรารีนี้

จุดเริ่มต้นของไลบรารีนี้คือคลาส moneywave

moneywave ();">

 $ moneywave = new moneywave ();

เราจะหารือเพิ่มเติมเกี่ยวกับเรื่องนี้ในภายหลัง

การกำหนดค่า

หากต้องการใช้ห้องสมุด คุณต้องได้รับข้อมูลรับรองจากบัญชี moneywave ของคุณ พวกเขาให้กุญแจสองดอกแก่คุณ:

• คีย์ API
• รหัสลับ

บัญชีของคุณสามารถอยู่ในสถานะใดสถานะหนึ่งจากสองสถานะ: 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 ();">

 $ moneywave = new moneywave ();

ผ่านเข้าไปในตัวสร้าง

วิธีที่สองในการกำหนดค่าไคลเอนต์ moneywave คือการส่งการตั้งค่าทั้งหมดไปยังตัวสร้าง
ต่างจาก วิธีที่ 1 คุณจะต้องเก็บคีย์ไว้ที่ไหนสักแห่งและมอบให้แก่ลูกค้าเมื่อคุณสร้างอินสแตนซ์

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 ในใบสมัครของคุณ คุณมีหนึ่งใน 2 ตัวเลือก:

• บันทึกโทเค็นที่ดึงข้อมูลไปยัง 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
บัญชีไปยังบัญชี	createAccountToAccountService
บัญชีToWallet	createAccountToWalletService
การโอนบัญชี	createAccountTransferService
ธนาคาร	createBanksService
บัญชีบัตรไปยังธนาคาร	createCardToBankAccountService
การทำโทเค็นบัตร	createCardTokenizationService
CardToWallet	createCardToWalletService
การโอนบัตร	createCardTransferService
เบิกจ่าย	createDisburseService
เบิกจ่ายจำนวนมาก	createDisburseBulkService
อินเทอร์เน็ต BankingToWallet	createInternetBankingToWalletService
QueryCardToAccountโอน	createQueryCardToAccountTransfer
สอบถามการเบิกจ่าย	createQueryDisbursementService
ลองอีกครั้งล้มเหลวในการโอน	createRetryFailedTransferService.retry
TotalChargeToCard	createTotalChargeToCardService
ตรวจสอบการโอนบัตร	createValidateCardTransferService
ตรวจสอบการโอน	createValidateTransferService
ตรวจสอบMerchant	createVerifyMerchantService
WalletBalance	createWalletBalanceService

แต่ละบริการมีรายการคุณสมบัติที่ต้องตั้งค่าก่อนจึงจะสามารถส่งไปยัง API ได้ หากไม่ได้ตั้งค่าคุณสมบัติเหล่านี้ตั้งแต่หนึ่งรายการขึ้นไป การเรียก send() จะส่ง ValidationException
ลองใช้ ทรัพยากร Account Number validation API เป็นตัวอย่าง:
จากเอกสารประกอบ จำเป็นต้องมีคุณสมบัติต่อไปนี้:

ชื่อฟิลด์	คำอธิบาย
บัญชี_หมายเลข	หมายเลขบัญชีของผู้ส่ง
bank_code	รหัสธนาคารของบัญชีที่จะแก้ไข

หากต้องการใช้ไลบรารี เราจะดำเนินการดังนี้:

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 (สำหรับบริการ) สามารถตั้งค่าเป็นคุณสมบัติบนออบเจ็กต์บริการที่สร้างขึ้นได้

สนามพิเศษ

มีบางช่องที่พิเศษและคุณไม่จำเป็นต้องตั้งค่าเอง (แต่คุณสามารถเลือกตั้งค่าได้) พวกเขาจะได้รับค่าที่ต้องการจากห้องสมุดโดยอัตโนมัติ ค้นหาได้ตามรายการด้านล่าง:

สนาม	คำอธิบาย
apiKey	สิ่งนี้จะถูกตั้งค่าเป็นคีย์ API ที่ใช้ในการสร้างอินสแตนซ์ของวัตถุ moneywave
ความลับ	สิ่งนี้จะถูกตั้งค่าเป็นรหัสลับที่ใช้สำหรับวัตถุ moneywave
ค่าธรรมเนียม	ตั้ง ค่าเริ่มต้น เป็น 0
ผู้รับ	สำหรับ createCardToWalletService จะถูกตั้งค่าเป็น wallet ตามค่าเริ่มต้น
สกุลเงิน	ตั้งค่าเป็น Naira Currency::NAIRA โดยอัตโนมัติ

บริการพิเศษ

เช่นเดียวกับที่มีช่องพิเศษ นอกจากนี้ยังมีออบเจ็กต์บริการพิเศษบางอย่างที่นำเสนอมากกว่าเมธอด send() ปกติ

การโอนเงิน ( createCardToBankAccountService() , createCardToWalletService() )

บริการรับส่งเหล่านี้มีความพิเศษเพราะโดยส่วนใหญ่แล้วจะเป็น แบบ 2 ขา พวกเขาเกี่ยวข้องกับขั้นตอนต่อไปนี้:

1 ขาโอน 2 ขาตรวจสอบ

ขั้นตอนเหล่านี้ทำงานทีละขั้นตอน และต้องดำเนินการให้เสร็จสิ้นทั้งสองขั้นตอนจึงจะ เสร็จสิ้น การโอน
มีบริการ 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]