README

用于消费 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。
让我们以 账户号码验证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 验证端

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

• createValidateCardTransferService()：允许您验证使用 威士卡 借记卡进行的 卡到钱包 或 卡到账户 转账
• 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]