moneywave
1.0.0
用於使用moneywave API 服務的 PHP 函式庫。
您可以查看文件以查看所有可用內容：https://moneywave-doc.herokuapp.com/
首先，您只需透過composer安裝它：
$ composer require emmanix2002/ moneywave
這會將其新增至您的composer.json並將其安裝為專案依賴項。
moneywave服務上可用的所有功能和資源均作為服務公開。因此，要使用任何服務，首先需要創建它。
moneywave API 上的所有功能和資源都作為該庫中的服務公開。
該庫的入口點是moneywave類別。
$ moneywave = new moneywave ();
我們稍後將對此進行更多討論。
要使用該庫，您需要從moneywave帳戶取得憑證。他們為您提供了兩把鑰匙：
您的帳戶可以處於兩種狀態之一： Test或Production 。對於每個狀態，您將使用不同的鍵。
moneywave類別需要這些金鑰（並且必須受到保護－它們用於驗證商家帳戶）；要將它們與此庫一起使用，您可以使用兩種可能的方法之一。
使用此方法將密鑰儲存在伺服器上的特定檔案中，這意味著這些值不會硬編碼到您的程式碼中。該庫期望找到一個名為.env文件，該文件與您的Composer vendor目錄處於同一層級。
.env
vendor/
composer.json
composer.lock
正如您在上面看到的，設定檔案應該處於所描述的層級。該文件的內容應該與您在.env.example中找到的內容相同，如下所示：
# 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客戶端的第二種方法是將所有設定傳遞到建構函式中。
與方法一不同，您需要將金鑰儲存在某處，並在實例化它時將它們提供給客戶端。
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
當客戶端實例化時（請參閱設定），它會自動啟動VerifyMerchant服務。該服務從moneywave服務取得access token ，該令牌將用於授權您針對 API 發出的每個其他請求。
每個access token有效期為2 hours 。在您的應用程式中，您有以下兩個選項之一：
Session中，以便在多個請求中使用它對於第一個選項，請查看examples目錄中的範例檔案。你會看到這樣的東西：
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()方法。每個功能和資源都對應到一個服務；可以從類別名稱輕鬆推斷出映射。
下表描述了所有服務：
| 班級名稱 | 服務電話 |
|---|---|
| 帳號驗證 | 建立帳號驗證服務 |
| 帳戶到帳戶 | 建立帳戶到帳戶服務 |
| 帳戶到錢包 | 建立帳戶到錢包服務 |
| 帳戶轉帳 | 建立帳戶轉帳服務 |
| 銀行 | 創建銀行服務 |
| 卡到銀行帳戶 | 建立卡片到銀行帳戶服務 |
| 卡代幣化 | 創建卡片令牌化服務 |
| 卡到錢包 | 創建卡片到錢包服務 |
| 卡轉帳 | 建立卡片傳輸服務 |
| 支付 | 創建支付服務 |
| 散裝支付 | 建立DisburseBulkService |
| 網路銀行到錢包 | 創建網路銀行到錢包服務 |
| 查詢卡到帳戶轉賬 | 建立查詢卡到帳戶轉賬 |
| 查詢支出 | 建立查詢支付服務 |
| 重試失敗傳輸 | 建立重試失敗傳輸服務 |
| 儲值卡總計 | 建立TotalChargeToCardService |
| 驗證卡傳輸 | 建立驗證卡傳輸服務 |
| 驗證傳輸 | 建立驗證傳輸服務 |
| 驗證商戶 | 建立驗證商戶服務 |
| 錢包餘額 | 創建錢包餘額服務 |
每個服務都有一個屬性列表，必須先對其進行設置，然後才能將其發送到 API；如果未設定這些屬性中的一個或多個，則呼叫send()會引發ValidationException 。
我們以Account Number validation API資源為例：
根據文檔，需要以下屬性：
| 欄位名稱 | 描述 |
|---|---|
| 帳號 | 寄件者的帳號 |
| 銀行代碼 | 要解析的帳戶的銀行代碼 |
要使用該庫，我們將執行以下操作：
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
如果未在服務對像上設定這些欄位之一，則會引發ValidationException異常。
moneywave文件（針對服務）中定義的每個欄位都可以設定為建立的服務對象的屬性。
有些欄位比較特殊，不需要您設定（儘管您可以選擇設定它們）；圖書館將自動為它們提供所需的值。找到下面列出的它們：
| 場地 | 描述 |
|---|---|
| API金鑰 | 這將被設定為用於實例化moneywave物件的 API 金鑰 |
| 秘密 | 這將設定為用於moneywave物件的金鑰 |
| 費用 | 預設為0 |
| 接受者 | 對於createCardToWalletService ，預設為wallet |
| 貨幣 | 自動設定為奈拉Currency::NAIRA |
正如有特殊欄位一樣，也有一些特殊的服務對象，它們比常規的send()方法提供更多功能。
createCardToBankAccountService() 、 createCardToWalletService() ）這些接送服務很特別，因為大多數時候它們都是兩條腿的。它們涉及以下步驟：
1 傳輸支路 2 驗證支路
這些步驟依序進行；並且必須完成這兩個步驟才能完成轉移。
有 2 個服務負責validation階段；他們是：
createValidateCardTransferService() ：允許您驗證使用Verve金融卡進行的卡片到錢包或卡片到帳戶的轉賬createValidateTransferService() ：允許您驗證使用帳戶進行的卡片到錢包或卡片到帳戶的轉帳。也就是說， charge_with字段設定為ChargeMethod::ACCOUNT 。因此，當您在第一站之後收到來自 API 的成功回應時；您開始驗證腿。
注意：對於 Mastercard 和 Visa 卡轉賬，您將在成功的 API 回應中收到authurl密鑰；您將重定向到此 URL，以便付款人驗證轉帳。成功或失敗後，付款人將被重定向迴轉帳請求的redirecturl欄位中設定的URL。
該服務用於將現金從您的moneywave錢包支付到多個銀行帳戶。它有一個特殊的方法來添加個人beneficiary帳戶。
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
此方法可讓您依序新增每個受益人帳戶：
$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物件上定義的方法：
| 方法 | 返回類型 | 描述 |
|---|---|---|
| 取得原始回應() | 細繩 | 來自 API 的 JSON 回應 |
| 成功() | 布林值 | 檢查status鍵是否=== "success" |
| 取得代碼() | 細繩 | 回傳code密鑰 |
| 獲取訊息() | 細繩 | 傳回message屬性 |
| 取得數據() | 大批 | 返回data鍵 |
注意：對於data是字串的回應；它傳回這個陣列[data: string]
