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アカウントから資格情報を取得する必要があります。次の 2 つのキーが提供されます。
アカウントは、 TestまたはProduction 2 つの状態のいずれかになります。これらの状態ごとに、異なるキーを使用します。
これらのキーは、 moneywaveクラスに必要です (そして保護する必要があります。販売アカウントの認証に使用されます)。このライブラリでそれらを使用するには、2 つの可能な方法のいずれかを使用できます。
この方法を使用すると、サーバー上の特定のファイルにキーが保存されます。つまり、値はコードにハードコーディングされません。ライブラリは、 composer vendorディレクトリと同じレベルで.envというファイルを見つけることを期待します。
.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クライアントを構成する 2 番目の方法は、すべての設定をコンストラクターに渡すことです。
方法 1とは異なり、キーをどこかに保存し、インスタンス化するときにクライアントに提供する必要があります。
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
クライアントがインスタンス化されると (構成を参照)、 VerifyMerchantサービスが自動的に起動します。このサービスは、API に対して行う他のすべてのリクエストを承認するために使用されるaccess token moneywaveサービスから取得します。
すべてのaccess tokenの有効期間は2 hoursです。アプリケーションには、次の 2 つのオプションのいずれかがあります。
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()メソッドの 1 つを呼び出して、そこから必要なサービスのインスタンスを作成します。send()メソッドを呼び出します。各機能とリソースはサービスにマップされます。マッピングはクラス名から簡単に推測できます。
以下の表にすべてのサービスを示します。
| クラス名 | サービスコール |
|---|---|
| アカウント番号検証 | createAccountNumberValidationService |
| アカウントからアカウントへ | createAccountToAccountService |
| アカウントからウォレットへ | createAccountToWalletService |
| 口座振替 | createAccountTransferService |
| 銀行 | createBanksService |
| カードから銀行口座へ | createCardToBankAccountService |
| カードトークン化 | createCardTokenizationService |
| カードからウォレットへ | createCardToWalletService |
| カード転送 | createCardTransferService |
| 支払い | createDisburseService |
| バルクの支払い | createDisburseBulkService |
| インターネットバンキングからウォレットへ | createInternetBankingToWalletService |
| QueryCardToAccountTransfer | createQueryCardToAccountTransfer |
| 支払いの問い合わせ | createQueryDisbursementService |
| 再試行失敗転送 | createRetryFailedTransferService |
| カードへの合計チャージ | createTotalChargeToCardService |
| カード転送の検証 | createValidateCardTransferService |
| 転送の検証 | createValidateTransferService |
| 販売者の確認 | createVerifyMerchantService |
| ウォレット残高 | createWalletBalanceService |
各サービスには、API に送信する前に設定する必要があるプロパティのリストがあります。これらのプロパティの 1 つ以上が設定されていない場合、 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() )これらの送迎サービスは、ほとんどの場合2 本足で行われるため、特別です。それには次の手順が含まれます。
1 転送区間 2 検証区間
これらの手順は次々に実行されます。転送を完了するには両方の手順を完了する必要があります。
validation作業を行うサービスが 2 つあります。彼らです：
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オブジェクトで定義されているメソッドを説明しています。
| 方法 | 戻り値の型 | 説明 |
|---|---|---|
| getRawResponse() | 弦 | APIからのJSONレスポンス |
| isSuccessful() | ブール | statusキー=== "success"かどうかを確認します |
| getコード() | 弦 | codeキーを返します |
| getMessage() | 弦 | message属性を返します |
| getData() | 配列 | dataキーを返します |
注: dataが文字列である応答の場合。この配列[data: string]を返します
