README

目录
简介
免责声明
安装
- 要求
- Composer
入门
参考

简介

Midtrans Iris PHP 库是一个 API 客户端库，用于与 Midtrans Iris API 通信，主要用于发放和支付。

免责声明

注意：虽然 API 几乎完整，但此库仅与“聚合器”方案进行了测试。还有一个“促进者”方案，但需要拥有针对该方案的特定账户才能使用 API 密钥进行测试。有关方案的信息，请访问 https://iris-docs.midtrans.com/#business-flow。

安装

要求

PHP 7.2.34 及以上版本。

Composer

您可以通过 Composer 安装绑定。运行以下命令

composer require timedoor/tmd-midtrans-iris

要使用此库，请使用 Composer 的自动加载

require_once('vendor/autoload.php');

入门

基本用法如下

$iris = new \Timedoor\TmdMidtransIris\Iris([
    'approver_api_key'  => 'your_api_key',
    'creator_api_key'   => 'your_api_key',
    'merchant_key'      => 'your_merchant_key'
]);

$beneficiaries = $iris->beneficiaries()->all();
var_dump($beneficiaries);

参考

对于您使用的每个服务，它们可能会抛出一些异常，如 UnauthorizedRequestException、BadRequestException 或 GeneralException，因此请确保您处理可能发生的异常。

所有示例都将假设您已经设置了 iris 并有一个名为 $iris 的 iris 实例对象。

每个 models 和 dtos 都从 \Timedoor\TmdMidtransIris\Utils\DataMapper 继承，这将允许您从数组中构建您的 models 和 dtos，而不仅仅是使用 setter 方法。

受益人

对于每个受益人，将使用 alias_name 作为唯一标识符。因此，请确保为 alias_name 使用唯一值。

1.0 获取受益人列表

示例

$beneficiaries = $iris->beneficiary()->all();

1.1 创建受益人

示例

$request = \Timedoor\TmdMidtransIris\Models\Beneficiary::fromArray([
    'name'          => 'John Doe',
    'bank'          => 'bca',
    'account'       => '141414141414',
    'alias_name'    => 'johndoe1',
    'email'         => 'john@example.com'
]);

您还可以使用 setters 来构建您的请求模型，如下所示

$request = (new \Timedoor\TmdMidtransIris\Models\Beneficiary)
            ->setName('John Doe')
            ->setBank('bca');

创建受益人

$result = $iris->beneficiary()->create($request);
var_dump($result) // ['status' => 'created']

1.2 更新受益人

与创建受益人类似，但此操作需要另一个属性，即 alias_name。假设您想要更新的受益人将具有 alias_name 为 johndoe1

$request = \Timedoor\TmdMidtransIris\Models\Beneficiary::fromArray([
    'name'          => 'Jane Doe',
    'bank'          => 'mandiri',
    'account'       => '1515151515',
    'alias_name'    => 'janedoe',
    'email'         => 'jane.doe@example.com'
]);

$result = $iris->beneficiary()->update('johndoe1', $request);
var_dump($result) // ['status' => 'updated']

银行账户

在此场景中，对于银行账户，将使用一些术语，即 facilitator 和 aggregator。您可以在 https://iris-docs.midtrans.com/#business-flow 上了解更多信息。

警告：仅 聚合器 方案与 Iris API 的集成测试进行了测试。

银行账户服务将分为 3 个服务

基本银行账户服务
聚合器 特定银行账户服务
促进者 特定银行账户服务

2.0 获取银行账户余额

基本

$balance = $iris->bankAccount()->balance();
var_dump($balance); // int(10000) default is 0

聚合器

与基本银行账户服务获取账户余额类似，只需添加一个 AccountType 参数即可，例如

$balance = $iris->bankAccount(\Timedoor\TmdMidtransIris\AccountType::AGGREGATOR)->balance();

促进者

只需将参数更改为 \Timedoor\TmdMidtransIris\AccountType::FACILITATOR

$balance = $iris->bankAccount(\Timedoor\TmdMidtransIris\AccountType::FACILITATOR)->balance();

2.1 获取银行账户列表（促进者）

此功能仅适用于促进者模型。您可以通过以下辅助方法简单地获取您拥有的银行账户列表

$balance = $iris->bankAccount(\Timedoor\TmdMidtransIris\AccountType::FACILITATOR)->all();

此方法将返回一个\Timedoor\TmdMidtransIris\Models\BankAccount数组。

2.2 验证银行账户

您可以使用银行账户服务上的validate方法来确保您的用户银行账户的有效性，如下所示

$result = $iris->bankAccount()->validate('bca', '12345678');

此方法接受两个参数，分别是

银行代码
账户号码

如果成功调用，它将返回一个\Timedoor\TmdMidtransIris\Models\BankAccountValidated，如果验证的账户无效，则会抛出异常。如果您想查找受支持的银行，请参阅此链接：https://iris-docs.midtrans.com/#supported-banks，或者您可以集成内置方法2.3 受支持的银行。

2.3 支持的银行

如果您需要知道使用哪个银行代码，或者只是为了满足您应用程序的UI设计，您可以在以下示例中获取所有受支持的银行账户。以下是如何使用它的示例

$result = $iris->bankAccount()->bankList();

此方法返回一个\Timedoor\TmdMidtransIris\Models\Bank数组。

支付

本节将描述您如何使用此库来管理您的付款。Iris的API使我们能够创建、批准、拒绝、获取账户的付款详情和历史记录。有关Iris提供的Open API的更多信息，请参阅此链接：https://iris-docs.midtrans.com。在本节中，您将遇到一些与API交互的角色，即creator和approver，每个角色都有其特定的任务，将在特定部分中描述。

2.0 创建支付

此API仅适用于creator角色，并允许您一次创建单个或多笔付款。以下是如何使用它的示例

$payouts = [
    (new \Timedoor\TmdMidtransIris\Dto\PayoutRequest)
        ->setBeneficiaryName('Example')
        ->setBeneficiaryAccount('1212121212')
        ->setBeneficiaryBank('bca')
        ->setAmount(10000)
        ->setNotes('just an example payout'),
    (new \Timedoor\TmdMidtransIris\Dto\PayoutRequest)
        ->setBeneficiaryName('Example 2')
        ->setBeneficiaryAccount('1313131313')
        ->setBeneficiaryBank('bni')
        ->setAmount(20000)
        ->setNotes('just an example payout')
];

$result = $iris->payout()->create($payouts);

在付款服务上的create方法仅接受一个\Timedoor\TmdMidtransIris\Dto\PayoutRequest数组。您可以使用setter方法构建请求，或者您也可以使用fromArray方法，因为\Timedoor\TmdMidtransIris\Dto\PayoutRequest扩展自Timedoor\TmdMidtransIris\Utils\DataMapper。

在成功请求的情况下，此方法将返回一个\Timedoor\TmdMidtransIris\Models\Payout[]数组，无论是您传递单个还是多笔付款，或者在失败的情况下抛出异常。

2.1 批准支付

创建付款后的下一步是批准它。这项工作需要approver角色。付款批准请求非常简单，如下例所示

$result = $iris->payout()->approve(['ref001', 'ref002'], '333333');

approve方法接受两个参数：一个ref_nos数组或付款ID以及一个otp。如果成功，它将返回一个数组["status" => "ok"]，如果失败，则会抛出异常。更多信息请参阅此链接 https://iris-docs.midtrans.com/#approve-payouts。

2.2 拒绝支付

您可以拒绝任何已创建且状态为queued的付款。例如

$response = $iris->payout()->reject(['ref001'], 'the reason why you reject it');

当您拒绝付款时，您需要传递拒绝原因，但与批准不同，不需要输入otp。如果失败，此方法将抛出异常，如果成功，则返回一个数组。更多信息请参阅https://iris-docs.midtrans.com/#reject-payouts。

2.3 获取支付详情

要获取有关付款的更详细的信息，您可以使用此方法。例如

$payout = $iris->payout()->get('ref001');

如果成功，此方法将返回一个\Timedoor\TmdMidtransIris\Models\Payout，或者在失败的情况下抛出异常。

交易历史

您可以获取已保存到您的账户中的交易记录的历史，例如payouts或topups。要获取交易记录列表，只需在交易服务上调用history方法，如下所示

$transactions = $iris->transaction()->history();

此方法实际上接受两个参数，即\DateTime对象，但它是可选的。它将返回一个\Timedoor\TmdMidtransIris\Models\Transaction数组。

通过调整参数中的$from和$to来过滤历史数据有一些规则和限制，更多内容请在此处查看：https://iris-docs.midtrans.com/#transaction-history。

充值渠道信息

在您能够批准任何付款之前，对于aggregator模型，您需要在账户中拥有一定余额。要为账户充值，您需要用一定金额的现金进行充值。此API将为您提供需要将这笔特定金额转到何处以充值账户余额的信息。例如

$channels = $iris->topUp()->channels();

此方法将返回一个包含\Timedoor\TmdMidtransIris\Models\TopUpChannel的数组。

Laravel 支持

此软件包完全支持Laravel。安装此软件包后，如果您使用Laravel自动发现，所有服务都将对您可用。安装软件包后，您应根据您的凭据配置库

MIDTRANS_IRIS_ENV=
MIDTRANS_IRIS_MERCHANT_KEY=
MIDTRANS_IRIS_CREATOR_KEY=
MIDTRANS_IRIS_APPROVER_KEY=

用作依赖注入

public function index(Beneficiary $beneficiary)
{
    return $beneficiary->all();
}

您还可以使用外观

use Timedoor\TmdMidtransIris\Facade as Iris;

然后使用您需要的服务

$payout = Iris::payout()->get('abc');

// or

$beneficiaries = Iris::beneficiary()->all();

不使用Laravel自动发现

如果您使用的是不带自动发现的Laravel版本，您必须在您的config/app.php文件中指定服务提供程序

\Timedoor\TmdMidtransIris\IrisServiceProvider::class

timedoor / tmd-midtrans-iris

维护者

详细信息