README

本包提供了HelloCash API的接口。它处理发票、支付以及Webhooks。

有关更多信息，请查看文档：https://api-et.hellocash.net/docs/

注意：此项目不是官方包，我与HelloCash没有任何关联。

设置

安装

通过Composer安装此包。

此包需要Laravel 5.0或更高版本，并使用Guzzle进行API调用。根据您的依赖关系使用适当的版本。

composer require drsdre/laravel-hellocash

服务提供者

此包支持Laravel 5.5的自动发现。

如果您使用的是旧版本，请在您的 config/app.php 中添加以下服务提供者。

'providers' => [
    drsdre\HelloCash\HelloCashServiceProvider::class,
]

配置

在 config/hellocash.php 中管理连接参数。建议使用基于'token'的身份验证，而不是'credentials'。

return [
    'principal' => env('HELLOCASH_PRINCIPAL'),
    'credentials' => env('HELLOCASH_CREDENTIALS'),
    'token' => env('HELLOCASH_TOKEN'),
    'system' => env('HELLOCASH_SYSTEM'),
    'webhook_secret' => env('HELLOCASH_WEBHOOK_SECRET'),
];

从HelloCash获取的 principal 和 system 数据。在HelloCash门户中生成的'token'，或者通过'connection' API端点生成。

有关API身份验证的更多信息，请参阅文档：https://api-et.hellocash.net/docs/#/Authenticate

处理Webhooks

HelloCash支持Webhooks，此包提供了一个可扩展以处理传入通知事件的控制器。请确保设置'HELLOCASH_WEBHOOK_SECRET'环境参数。这可以在HelloCash门户的连接设置中生成或通过'connection' API端点生成。

有关Webhooks的更多信息，请参阅wiki：https://api-et.hellocash.net/docs/#/Connection

扩展控制器

您可以创建一个控制器来处理所有事件，也可以为每个事件创建一个控制器。无论哪种方式，您的控制器都必须扩展 drsdre\HelloCash\WebhookController。Webhook验证将自动处理。

HelloCash通过Webhooks发送转账和发票的更新。要处理这些事件，您的控制器必须扩展 handleEventNotification 方法。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use drsdre\HelloCash\WebhookController as BaseController;

class WebhookController extends BaseController
{
    /**
     * Handle payment notifications.
     *
     * @param  Request $request
     */
    protected function handleEventNotification(Request $request)
    {
        $event = $request->EventData;
    }
}

定义路由

在您的 routes/web.php 中定义以下路由，替换URI和控制器。

Route::match(['post', 'get'], 'hellocash/webhooks', 'WebhookController@handle');

排除CSRF保护

不要忘记将您的webhook URI添加到 VerifyCsrfToken 中间件的 $except 数组中。

<?php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    /**
     * The URIs that should be excluded from CSRF verification.
     *
     * @var array
     */
    protected $except = [
        'hellocash/webhooks',
    ];
}

API方法

Postman Collection

可用的Postman集合用于测试调用。请确保设置以下密钥的环境：

端点: https://api-et.hellocash.net
主体: 如你所提供
凭证: 如你所提供
系统: 如你所提供

发票

创建或验证发票

查看: https://api-et.hellocash.net/docs/#/Invoice

$HC_invoice = app(drsdre\HelloCash\Requests\Invoice::class);

$invoice = $HC_invoice->create(
    ...
);

获取发票状态

查看: https://api-et.hellocash.net/docs/#!/Invoice/invoice_findByIdWrap

$HC_invoice = app(drsdre\HelloCash\Requests\Invoice::class);

$invoice = $HC_invoice->get('175936509216');

搜索发票

查看: https://api-et.hellocash.net/docs/#!/Invoice/invoice_findWrap

$HC_invoice = app(drsdre\HelloCash\Requests\Invoice::class);

$invoices = $HC_invoice->search(['status' => 'PENDING']);

删除发票

查看: https://api-et.hellocash.net/docs/#!/Invoice/invoice_deleteById

$HC_invoice = app(drsdre\HelloCash\Requests\Invoice::class);

$response = $HC_invoice->remove('175936509216');

转账

创建或验证新的转账

查看: https://api-et.hellocash.net/docs/#!/Transfer/transfer_create

$HC_transfer = app(drsdre\HelloCash\Transfer::class);

$transfer = $HC_transfer->create(
    ...
);

搜索转账

查看: https://api-et.hellocash.net/docs/#!/Transfer/transfer_find

$HC_transfer = app(drsdre\HelloCash\Transfer::class);

$transfers = $HC_transfer->search(['status' => 'PENDING']);

通过ID获取转账

查看: https://api-et.hellocash.net/docs/#!/Transfer/transfer_findByIdWrap

$HC_transfer = app(drsdre\HelloCash\Transfer::class);

$transfer = $HC_transfer->get('LUC00000248255ETH');

取消转账

查看: https://api-et.hellocash.net/docs/#!/Transfer/transfer_cancel

$HC_transfer = app(drsdre\HelloCash\Transfer::class);

$response = $HC_transfer->cancel(['LUC00000248255ETH']);

授权一组转账

查看: https://api-et.hellocash.net/docs/#!/Transfer/transfer_authorize

$HC_transfer = app(drsdre\HelloCash\Transfer::class);

$response = $HC_transfer->authorize(['LUC00000248255ETH']);

Webhooks

设置与你的webhook URL的连接

查看: https://api-et.hellocash.net/docs/#!/Connection/connection_create

$webhook = app(drsdre\HelloCash\Webhook::class);

$key = $webhook->verify();

异常

当HelloCash API返回错误时，会抛出drsdre\HelloCash\HelloCashException。

对于任何其他HTTP错误，会抛出GuzzleHttp\Exception\ClientException。

测试

运行phpunit --group unit来触发单元测试。

要运行功能测试，你需要在根目录中包含一个.env文件，其中包含凭证（HELLOCASH_PRINCIPAL、HELLOCASH_CREDENTIALS、HELLOCASH_SYSTEM），以便调用HelloCash的测试API。然后运行phpunit --group functional来触发测试。

drsdre / laravel-hellocash

维护者

详细信息