README

Vandar Cashier是一个Laravel包，提供了与Vandar服务的无缝集成。查看Vandar文档以获取我们提供的服务的更多信息。

设置

要使用Vandar Cashier，您需要首先通过Composer安装它

composer require vandarpay/cashier

然后，您需要发布包的资产并将您项目的数据库迁移以添加Vandar Cashier的表

php artisan vendor:publish --provider="Vandar\\Cashier\\VandarCashierServiceProvider"
php artisan migrate

之后，打开您的用户模型（位于大多数项目的app/User.php或app/Models/User.php），并添加Billable特性

use Vandar\Cashier\Traits\Billable;
// ...
class User extends Authenticatable
{
    use Billable;
// ...

您需要在您的.env文件中添加必要的配置

VANDAR_MOBILE=
VANDAR_PASSWORD=
VANDAR_BUSINESS_SLUG=
VANDAR_API_KEY=

VANDAR_MOBILE和VANDAR_PASSWORD是您登录Vander仪表板的凭证，VANDAR_BUSINESS_SLUG是在您在Vander中添加业务时设置的，而VANDAR_API_KEY是通过您的业务仪表板获得的。

用法

目前，Vandar Cashier支持Vandar服务的三项：IPG、直接借记和结算。IPG是更常用的方法，它为您提供一个链接，用户可以使用它来支付服务。直接借记服务通过请求访问用户的银行账户并在不涉及用户交互的情况下定期从他们的账户中提取资金来实现。

IPG

独立

如果您正在创建捐赠表单，或者您不需要登录用户进行支付，您需要两个路径。第一个路径是启动支付并将它发送到支付网关。第二个路径（也称为回调URL）将在您的用户返回后验证交易。

use Vandar\Cashier\Models\Payment;
Route::get('/initiate-payment', function(Request $request) {
    // Amounts are in IRR
    // For more values, see Payment or https://vandarpay.github.io/docs/ipg/#step-1
    $payment = Payment::create(['amount' => 10000]);
    return redirect($payment->url);
});

用户相关

在一个用户相关的场景中，我们假设任何进行支付的人已经登录到您的系统，因此，您可以为他们创建一个支付链接，通过他们的用户模型进行重定向

Route::get('/initiate-payment', function(Request $request){
    $user = auth()->user(); // Added as a separate variable for clarity
    // Amounts are in IRR
    // For more values, see Payment or https://vandarpay.github.io/docs/ipg/#step-1
    $payment = $user->payments()->create(['amount' => 10000]);
    return redirect($payment->url); // See documentation for info on payload and callback
});

回调URL

一旦交易完成（成功或不成功），他们将被重定向回您定义的回调路径，您可以定义一个控制器或路由，使用Payment::verify($request)方法验证支付

use Vandar\Cashier\Models\Payment;
Route::get('/callback', function(Request $request){
    if(Payment::verifyFromRequest($request)){
        return 'Success!';
    } 
    else {
        return 'Failed!';
    }
});

verify方法会自动更新数据库中的交易状态。

此外，对于IPG，您需要为用户从Vandar返回到您的应用程序时定义一个回调URL，您可以选择设置VANDAR_CALLBACK_URL环境变量或修改config/vandar.php。您还需要在Vandar的业务仪表板中添加回调URL，否则将导致错误。

直接借记

设置直接借记时，您需要执行两个主要步骤。

1. 让用户允许访问他们的账户（也称为授权）
2. 从用户的账户中请求提取

授权

授权基本上是客户授予我们访问他们账户的权限。在Vandar中，客户由他们的电话号码定义，这被认为是客户的唯一键。如果您计划在项目中使用订阅服务，您需要在用户表中添加一个mobile_number列。此代码可以用作迁移，将添加此类列

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class AddMobileNumbersColumnToUsersTable extends Migration
{
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('mobile_number')->nullable();
        });
    }
    
    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
           $table->dropColumn('mobile_number');
        });
    }
}

您还可以在传递给authorizeMandate的数组中传递mobile_number键。

然后您可以创建一个授权令牌，并将用户重定向到银行进行授权令牌的授权。

Route::get('/initiate-mandate', function(){
    $user = auth()->user();
    if(! $user->hasValidMandate()){ // You may use the hasValidMandate method if your design requires each user to have only one active mandate
    return redirect($user->authorizeMandate(['bank_code' => '062', 'count' => 3, 'limit' => '10000', 'expiration_date' => '2021-01-01']));
    }
})

您还需要为用户在完成授权令牌流程后返回的回调URL，这个路径应通过 VANDAR_MANDATE_CALLBACK_URL 设置为绝对URL，或者编辑配置文件。

您可以使用 Mandate::verifyFromRequest 方法验证授权令牌是否成功创建，并根据需要更新授权令牌。

use Vandar\Cashier\Models\Mandate;
Route::get('/mandate-callback', function(Request $request){
    if(Mandate::verifyFromRequest($request)){
        return 'Success!';
    } else {
        return 'Failed!';
    }
})

您还可以通过授权令牌模型的撤销函数撤销任何授权令牌。

use Vandar\Cashier\Models\Mandate

$mandate = Mandate::find(1);
$mandate->revoke(); // true if mandate was revoked successfully

由于用户取消授权令牌的唯一方式是通过您的平台，因此提供一种方便的方式供用户取消是标准的。

提款

成功创建授权令牌后，您可以通过授权令牌创建提款。

$user->mandates()->active()->first()->createWithdrawal(['amount' => 10000, 'is_instant' => true, 'description' => 'Subscription renewal', 'max_retry_count' => 16]);

请注意，您可以使用任何您喜欢的方发找到您当前的授权令牌，例如，如果您为每个用户有多个授权令牌，您可以使用不同的查询找到特定的授权令牌。

在创建新的提款时，传递 authorization_id 和 notify_url 不是必需的，因为 Cashier 自动设置这些值。

注意：如果没有提供，Vandar Cashier 将自动将 withdrawal_date 设置为现在。（date('Y-m-d')）

如果您不是创建即时提款（is_instant = false），您还可以在运行之前取消提款。

$status = $withdrawal->cancel(); // Returns 'CANCELED' on success, any other status (DONE, PENDING, INIT, FAILED) on failure.

结算

Vandar Cashier 提供了发起结算请求的能力。

$settlement = Settlement::create(['amount' => 5000, 'iban' => 'IR000000000000000000000000']) // amount is in Toman

成功创建结算后，Vandar 将将结算排队并发送给银行。当结算最终确定后，将向 vandar 配置中指定的 settlement_notify_url 发送通知。

Vandar Cashier 提供了一个自动处理结算更新并相应更新您的数据库的路由，因此除非您需要实现自己的解决方案，否则您不需要更新 settlement_notify_url。

您还可以在结算完成之前通过取消方法取消结算。如果成功，将返回 CANCELED。如果取消尝试失败，将返回数据库中最后已知的状态。

$settlement->cancel(); // Returns `CANCELED` on success.

工具

您可以使用 Vandar::getBanksHealth() 方法获取一个包含所有银行及其是否健康的数组的数组。

错误处理

在接触Vandar API时，由于API中处理您的请求时发生错误，可能会引发一系列异常。所有这些错误都可以通过 Vandar\Exceptions\ResponseException 异常捕获和处理。这意味着Cashier引发的所有异常都有以下方法

try {
    ...
} catch (\Vandar\Cashier\Exceptions\ResponseException $exception) {
    dump($exception->context()) // Dumps all the information passed into Guzzle, including headers and configuration
    dump($exception->getUrl()) // Dumps the url the request was sent to
    dump($exception->getPayload()) // Dumps the payload that was sent to Vandar APIs
    dump($exception->getResponse()) // Dumps the response object returned by Guzzle
    dump($exception->getResponse()->json()) // Returns an associative array of json response.
    dump($exception->errors()) // Useful especially in InvalidPayloadException, returns the "errors" key in the json response
}

您还可以尝试根据引发的异常区分错误

• ExternalAPIException 在发生任何5xx错误时引发
• AuthenticationException 在发生HTTP 401错误时引发，这可能仅发生在您忘记设置您的环境或您的信息无效的情况下，如果这种情况发生在任何其他情况下，请让我们知道！
• DeprecatedAPIException 在发生HTTP 404、405或410错误时引发，这通常意味着您使用的Vandar Cashier（及其背后的API）版本不再由Vandar支持，运行 composer update！
• InvalidPayloadException 在尝试的操作在Vandar方面以任何方式无效并引发HTTP 422时引发。（例如，您被授权提取1000托曼，但您尝试提取更多），我们打算将其分解为更具体的异常。
• TooManyRequestsException 在您尝试在短时间内向Vandar发送大量请求时引发，导致HTTP 429错误。
• UnexpectedAPIErrorException 当返回任何不在Vandar收银员范围内的4xx系列错误时引发。如果发生这种情况，请考虑更新收银员或提交包含您获得的异常完整上下文的bug。

许可证

本项目中所有材料（除非另有说明）均可在MIT许可证下使用。有关更多信息，请参阅LICENSE文件。