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]
