README

Moneywave

一个用于消费Moneywave API服务的PHP库。
您可以通过查看文档来查看所有可用的信息：https://moneywave-doc.herokuapp.com/

• 快速入门
• 介绍
• 配置
• 使用
• 服务
• 处理响应

快速入门

要开始，您只需通过composer安装它

$ composer require emmanix2002/moneywave

这将将其添加到您的composer.json文件中，并将其作为项目依赖项安装。

介绍

Moneywave服务上可用的所有功能和资源都作为服务公开。因此，要使用任何服务，首先需要创建它。

Moneywave API上的所有功能和资源都作为此库中的服务公开。

此库的入口点是Moneywave类。

$moneywave = new Moneywave();

我们稍后会进一步讨论这个问题。

配置

要使用此库，您需要从您的Moneywave账户获取凭据。它们提供您两个密钥

• API密钥
• 密钥

您的账户可以处于两种状态之一：测试或生产。对于这些状态中的每一个，您将使用不同的密钥。
这些密钥是Moneywave类（必须受到保护——它们用于验证商户账户）所必需的；要使用它们与此库一起使用，您可以使用两种可能的方法之一。

环境变量

使用此方法将密钥存储在您的服务器上的特定文件中，这意味着值不会被硬编码到您的代码中。库期望在您的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客户端的第二种方式是将所有设置传递给构造函数。
与方法一不同，您需要将密钥存储在某个位置，并在实例化时将其提供给客户端。

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

使用

客户端实例化时（请参阅 配置），它将自动启动VerifyMerchant服务。此服务从Moneywave服务获取访问令牌，该令牌将用于授权您对API发起的每个其他请求。
每个访问令牌的有效期为2小时。在您的应用程序中，您有两个选项之一

• 将检索到的令牌保存到您的会话中，以便在多个请求中使用
• 允许库为每次对API的调用请求一个令牌

对于第一个选项，请查看examples目录中的示例文件。您会看到如下内容

use Emmanix2002\Moneywave\Exception\ValidationException;
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());
}

这使得使用相同的访问令牌在相同机器上的另一个请求中成为可能。

服务

在实例化Moneywave对象后，您需要按照以下步骤使用服务

• 通过调用其中一个 create*Service() 方法，从它创建所需服务的实例。
• 在 服务对象 上设置属性。
• 在创建的 服务对象 上调用 send() 方法。

每个特性和资源都映射到一个服务；映射可以通过 类名 容易地推断出来。
下表描述了所有服务

每个服务都有一个属性列表，必须在将其发送到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 文档（对于服务）中定义的每个字段都可以设置为创建的服务对象的属性。

特殊字段

有一些字段是特殊的，不需要您设置（尽管您可以选择设置它们）；它们将由库自动赋予所需的值。以下列出它们：

特殊服务

就像有特殊字段一样，还有一些特殊的服务对象，它们提供了比常规更多的 send() 方法。

转账（createCardToBankAccountService()，createCardToWalletService()）

这些转账服务是特殊的，因为它们通常涉及两个步骤：1 转账步骤 2 验证步骤

1 转账步骤 2 验证步骤

这些步骤依次进行；并且必须完成这两个步骤才能完成转账。
有两个服务负责验证步骤；它们是：

• createValidateCardTransferService()：允许您验证使用 Verve 借记卡进行的 卡到钱包 或 卡到账户 转账
• createValidateTransferService()：允许您验证使用账户进行的卡到钱包或卡到账户转账。也就是说，charge_with字段设置为ChargeMethod::ACCOUNT。

因此，在收到API在第一阶段成功响应后；您开始验证阶段。

注意：对于万事达卡和维萨卡转账，您将在成功的API响应中收到一个authurl密钥；您需要将付款人重定向到这个URL以验证转账。成功或失败后，付款人将被重定向回转账请求中redirecturl字段设置的URL。

createDisburseBulkService()

此服务用于将您的Moneywave钱包中的现金分发给多个银行账户。它具有一个用于添加单个收款人账户的特殊方法。

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 = 'MoneywaveSDK';
$bulkDisbursement->addRecipient(Banks::ACCESS_BANK, '0690000004', 1)
                 ->addRecipient(Banks::ACCESS_BANK, '0690000005', 2);

请查看examples/disburse_bulk.php文件以获取完整示例。

处理响应

如果服务对象（参见服务）上的所有必需字段都已设置，则调用send()将返回一个响应对象，它是MoneywaveResponse类的实例。
继续上面的账户验证示例

$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
}

下表描述了在MoneywaveResponse对象上定义的方法

注意：对于data是字符串的响应，它返回此数组[data: string]