README

Caixeiro 是为巴西社区开发的周期性支付（订阅）解决方案，适用于具有特殊支付规则和极端不同的支付网关。

该项目的想法是提供一个简化的 API，使您能够轻松地使用首选的网关实现周期性支付。

网关支持计划

安装

安装 Caixeiro 很简单，只需使用 composer 将 Caixeiro 添加到您的 Laravel 项目中。

composer require artesaos/caixeiro

还需要添加您的支付网关的依赖。

MoIP

composer require artesaos/moip-subscriptions

配置

每个驱动器都有自己的字段，因为有些不需要某些数据，但这些字段都是可选的，我们将分别介绍每个驱动器，以便更好地利用它们。

MoIP

迁移

通常，代表您系统中订阅者的模型将是 User 模型，但某些应用程序可能基于 Tenant 或 Empresa 进行订阅，请将以下字段添加到创建表示订阅者的实体的表的迁移中

遗憾的是，MoIP 需要许多信息作为必填项，并且由于账户数据可能与卡片数据不同，我们将创建单独的字段来存储这些信息。

// Os seguintes campos são de uso do Caixeiro
$table->string('customer_id')->nullable();
$table->string('subscription_id')->nullable();
$table->string('card_brand')->nullable();
$table->string('card_last_four')->nullable();
$table->string('plan_code')->nullable();
$table->string('plan_name')->nullable();
$table->integer('amount')->nullable();
$table->string('status')->nullable();
$table->date('expires_at')->nullable();
$table->date('trial_expires_at')->nullable();
$table->text('subscription_metadata')->nullable();

环境

为了正确启动 MoIP 客户端并识别适当的模型，您必须在您的 config/services.php 文件中添加以下配置。

'caixeiro' => [
    'model' => env('CAIXEIRO_MODEL', App\User::class),
    'driver' => env('CAIXEIRO_DRIVER', 'moip'),
],
    
'moip'  =>  [
    'token' =>  env('MOIP_API_TOKEN', null),
    'key' =>  env('MOIP_API_KEY', null),
    'production' => env('MOIP_PRODUCTION', false),
],

请注意，示例中的信息是从您的应用程序的 .env 文件中检索的，可以按以下方式执行

CAIXEIRO_MODEL=App\User
CAIXEIRO_DRIVER=moip
MOIP_API_TOKEN=ABCDEFGHIJKLMNOPQRSTUVYXWZ
MOIP_API_KEY=ABCDEFGHIJKLMNOPQRSTUVYXWZ0123456789
MOIP_PRODUCTION=false

服务提供者

显然，像 Laravel 的其他包一样，您需要注册 Caixeiro 的服务提供者

Artesaos\Caixeiro\CaixeiroServiceProvider::class,

配置模型

设置键和其他信息后，您应在代表订阅者（通常是 User）的模型中使用 trait Artesaos\Caixeiro\Billable

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Artesaos\Caixeiro\Billable;

class User extends Authenticatable
{
   use Billable;
}

使用

警告

用户数据的处理，如地址、CPF、电话和出生日期，由您的应用程序负责，并非所有驱动器都需要这些信息，但您负责更新这些信息。

计划和优惠券

为了简化，我们没有创建管理和计划或优惠券的接口，因为这此类信息可以在您的网关面板中轻松配置。

Caixeiro API 将提供使用这些选项的选项，而不是管理选项。

客户

创建或修改客户

在创建订阅之前，我们需要在与网关一起创建客户，传递信用卡不是必须的，如果您想稍后通过银行汇票创建订阅。

/**
 * A variável $user simboliza o cenário comum onde
 * a assinatura é ligada a um usuáro.
 * Qualquer model que use a Trait Billable
 * pode ser usada.
 */

$user->customerData()
	// Nome Completo
    ->withName($user->name)
	// Email
    ->withEmail($user->email)
	// Nascimento
    ->withBirthday('1990-02-11')
	// Rua, Numero, Complemento
	// Bairro, Cidade, Estado
	// Pais, CEP
    ->withAddress(
        'Rua Linux Torvals', '42', 'A',
        'LinuxLandia', 'São Paulo', 'São Paulo',
        'BRA', '12345-000')
    // CPF
    ->withDocument('12345678909')
	// Telefone
    ->withPhoneNumber('11', '988887777')
	// Caso a API Use Dados do Cartão de Crédito Diretamente
    ->withCreditCard(
        'Linus Torvalds',
        '4111111111111111',
        '12', '17', '789'
    )
    // Caso a deseje passar um TOKEN gerado via
    // JS ao inves dos dados do cartão
    // nesse caso o método acima não deve ser usado.
    ->withCreditCardToken('7bcbb4ae59be06caf9966470c68f250e')
    // Finalmente cria o assinante
    ->save();

对于修改，API 与创建相同，所有在创建过程中可用的方法也可用于修改（每个网关都有自己的更新规则，将很快创建更详细的用户手册）但是必须在设置数据后调用 update() 方法。

$user->customerData()
	// Alterando o Telefone
    ->withPhoneNumber('33', '544443333')
	// Trocando o cartão de crédito
    ->withCreditCard(
        'Linus Torvalds',
        '4222222222222222',
        '02', '22', '743'
    )
    // e finalmente o update
    ->update();

订阅

创建订阅很简单，请记住，在创建订阅的前一阶段准备客户是强制性的。

创建订阅

// Criando uma assinatura no plano 'plano-basico'
// e setando o método de pagamento como boleto bancário
$user->newSubscription('plano-basico')
	->withBankSlip()
	->create();

// Caso queira sobrescrever o valor da assinatura para 120 reais
$user->newSubscription('plano-basico')
	->withCustomAmount(12000)
	->create();
	
// Caso o cliente tenha informado um cupon de desconto
$user->newSubscription('plano-basico')
	->withCoupon('LARAVEL50')
	->create();
	
// As opções também podem ser combinadas:
$user->newSubscription('plano-basico')
	->withCustomAmount(12000)
	->withCoupon('LARAVEL50')
	->withBankSlip()
	->create();

挂起、激活和取消订阅

// Suspender
$user->suspendSubscription();

// (Re)ativar 
$user->activateSubscription();

// Cancelar
$user->cancelSubscription();