GuPayment

<p align="center"><img src="https://user-images.githubusercontent.com/3699061/82709406-ea491500-9c56-11ea-94e0-08fbc73c4dc9.png"></p> <p align="center"> <a href='https://travis-ci.org/Potelo/GuPayment'><img alt="Build status" src="https://travis-ci.org/Potelo/GuPayment.svg?branch=master"></a> <a href='https://coveralls.io/github/Potelo/GuPayment?branch=master'><img src='https://coveralls.io/repos/github/Potelo/GuPayment/badge.svg?branch=master' alt='Coverage Status' /></a> <a href='https://packagist.org/packages/potelo/gu-payment'><img alt="Packagist Downloads" src="https://img.shields.io/packagist/dt/potelo/gu-payment?color=%230b7cbd"></a> <a href='https://packagist.org/packages/potelo/gu-payment'><img alt="Packagist Version" src="https://img.shields.io/packagist/v/potelo/gu-payment?color=%2333a2d8"></a> </p>

Introdução

GuPayment é baseado no Laravel Cashier e fornece uma interface para controlar assinaturas do iugu.com.

Compatível com Laravel 5.5+, 6.x e 7.x.

Instalação

Instale esse pacote pelo composer:

composer require potelo/gu-payment

Se você não utiliza o auto-discovery, Adicione o GuPaymentServiceProvider em config/app.php

Potelo\GuPayment\GuPaymentServiceProvider::class,

Agora, configure as variáveis utilizadas pelo GuPayment no seu .env:

IUGU_APIKEY=SUA_CHAVE
IUGU_ID=SEU_ID_IUGU
GUPAYMENT_SIGNATURE_TABLE=subscriptions
IUGU_MODEL=User
IUGU_MODEL_FOREIGN_KEY=user_id
IUGU_USER_MODEL_COLUMN=iugu_id
IUGU_SUBSCRIPTION_MODEL_ID_COLUMN=iugu_id
IUGU_SUBSCRIPTION_MODEL_PLAN_COLUMN=iugu_plan

Antes de usar o GuPayment você precisa preparar o banco de dados. Primeiro você tem que publicar o migration.

php artisan vendor:publish --tag=migrations

Caso precise modificar ou acrescentar colunas na tabela de assinatura, basta editar os migrations publicados. Depois, basta rodar o comando php artisan migrate.

Vamos agora adicionar o Trait ao seu modelo do usuário.

use Potelo\GuPayment\GuPaymentTrait;

class User extends Authenticatable
{
    use GuPaymentTrait;
}

Agora vamos adicionar em config/services.php duas configurações. A classe do usuário, sua chave de api que o Iugu fornece e o nome da tabela utilizada para gerenciar as assinaturas, a mesma escolhida na criação do migration.

'iugu' => [
    'model'  => App\User::class,
    'key' => env('IUGU_APIKEY'),
    'signature_table' => env('GUPAYMENT_SIGNATURE_TABLE'),
    'model_foreign_key' => env('IUGU_MODEL_FOREIGN_KEY'),
]

Assinaturas

Criando assinaturas

Para criar uma assinatura, primeiro você precisa ter uma instância de um usuário que extende o GuPaymentTrait. Você então deve usar o método newSubscription para criar uma assinatura:

$user = User::find(1);

$user->newSubscription('main', 'gold')->create($creditCardToken);

O primeiro argumento deve ser o nome da assinatura. Esse nome não será utilizado no Iugu.com, apenas na sua aplicação. Se sua aplicação tiver apenas um tipo de assinatura, você pode chamá-la de principal ou primária. O segundo argumento é o identificador do plano no Iugu.com.

O método create automaticamente criará uma assinatura no Iugu.com e atualizará o seu banco de dados com o ID do cliente referente ao Iugu e outras informações relevantes. Você pode chamar o create sem passar nenhum parâmetro ou informar o token do cartão de crédito para que o usuário tenha uma forma de pagamento padrão. Veja como gerar o token em iugu.js

Caso queira que a assinatura seja criada apenas após a comprovação do pagamento, basta chamar o método chargeOnSuccess após newSubscription. IMPORTANTE: Esse modo de criar uma assinatura só funciona para o cliente que tenha um método de pagamento padrão, não funciona com boleto.

$user = User::find(1);

$user->newSubscription('main', 'gold')
->chargeOnSuccess()
->create($creditCardToken);

Assinatura com subitens

Para adicionar itens de cobrança a mais na assinatura do cliente, utilize o método subItems.

$subItems = [
    [
        'description' => 'Desconto recorrente',
        'price_cents' => -900,
        'quantity' => 1,
        'recurrent' => true,
    ],
    [
        'description' => 'Adicional não recorrente',
        'price_cents' => 250,
        'quantity' => 1,
        'recurrent' => false,
    ]
];

// Create Subscription
$user->newSubscription('main', 'gold')
    ->subItems($subItems)
    ->create($creditCardToken);

Também é possível adicionar um item por vez, utilizando o método addSubItem.

$subItem = [
   'description' => 'Desconto recorrente',
   'price_cents' => -900,
   'quantity' => 1,
   'recurrent' => true,
];

// Create Subscription
$user->newSubscription('main', 'gold')
    ->addSubItem($subItem)
    ->create($creditCardToken);

Dados adicionais

Se você desejar adicionar informações extras à assinatura, basta passar um array como terceiro parâmetro no método newSubscription, que é repassado à API do Iugu no parâmetro custom_variables:

$user = User::find(1);

$user->newSubscription('main', 'gold', [
    'adicional_assinatura' => 'boa assinatura'
])->create(NULL);

Outros parâmetros

Para customizar os parâmetros enviados à API, passe um array no quarto parâmetro do método newSubscription para a criação da assinatura, e/ou no segundo parâmetro do método create para a criação do cliente:

$user = User::find(1);

'$user->newSubscription('main', 'gold', [], ['ignore_due_email' => true])
    ->create(NULL, [
        'name' => $user->nome,
        'notes' => 'Anotações gerais'
    ]);

Para mais informações dos parâmetros que são suportados pela API do Iugu, confira a Documentação oficial

Tratamento de erros

Caso algum erro seja gerado no Iugu, é possível identificar esses erros pelo método getLastError do SubscriptionBuilder:

$user = User::find(1);

$subscriptionBuilder = $user->newSubscription('main', 'gold');

$subscription = $subscriptionBuilder->trialDays(20)->create($creditCardToken);

if ($subscription) {
    // TUDO ok
} else {
    $erros = $subscriptionBuilder->getLastError();
    
    if (is_array($erros)) {
        // array
    } else {
        // string
    }
}

O erro retornado pelo iugu, pode ser um array ou uma string.

Checando status da assinatura

Uma vez que o usuário assine um plano na sua aplicação, você pode verificar o status dessa assinatura através de alguns métodos. O método subscribed retorna true se o usuário possui uma assinatura ativa, mesmo se estiver no período trial:

if ($user->subscribed('main')) {
    //
}

O método subscribedpode ser utilizado em um route middleware, permitindo que você filtre o acesso de rotas baseado no status da assinatura do usuário:

public function handle($request, Closure $next)
{
    if ($request->user() && ! $request->user()->subscribed('main')) {
        // This user is not a paying customer...
        return redirect('billing');
    }

    return $next($request);
}

Se você precisa saber se um a assinatura de um usuário está no período trial, você pode usar o método onTrial. Esse método pode ser útil para informar ao usuário que ele está no período de testes, por exemplo:

if ($user->subscription('main')->onTrial()) {
    //
}

O método onPlan pode ser usado para saber se o usuário está assinando um determinado plano. Por exemplo, para verificar se o usuário assina o plano gold:

if ($user->onPlan('gold')) {
    //
}

Para saber se uma assinatura foi cancelada, basta usar o método cancelled na assinatura:

if ($user->subscription('main')->cancelled()) {
    //
}

Você também pode checar se uma assinatura foi cancelada mas o usuário ainda se encontra no "período de carência". Por exemplo, se um usuário cancelar a assinatura no dia 5 de Março mas a data de vencimento é apenas no dia 10, ele está nesse período de carência até o dia 10. Para saber basta utilizar o método onGracePeriod:

if ($user->subscription('main')->onGracePeriod()) {
    //
}

Para utilizar o objeto do Iugu a partir da assinatura, utilize o método asIuguSubscription:

$user->subscription('main')->asIuguSubscription();

Mudando o plano da assinatura

Se um usuário já possui uma assinatura, ele pode querer mudar para algum outro plano. Por exemplo, um usuário do plano gold pode querer economizar e mudar para o plano silver. Para mudar o plano de um usuário em uma assinatura, basta usar o método swap da seguinte forma:

$user = App\User::find(1);

$user->subscription('main')->swap('silver');

Ao utilizar o método swap, uma Fatura cobrando a mudança de plano poderá ser gerada para o cliente. Para simular os custos da alteração de plano, basta utilizar o método swapPlanSimulation:

$simulation = $user->subscription('main')->swapPlanSimulation('silver');

$cost = $simulation->cost;
$discount = $simulation->discount;
$cycles = $simulation->cycles;
$oldPlan = $simulation->old_plan;
$newPlan = $simulation->new_plan;
$expiresAt = $simulation->expires_at;

Para mudar de plano sem cobrança proporcional, basta passar o segundo parâmetro como true:

$user = App\User::find(1);

$skipCharge = true;
$user->subscription('main')->swap('silver', $skipCharge);

Caso queira alterar a data de vencimento (Que é quando a próxima fatura será gerada/cobrada), basta passar um terceiro parâmetro com a data no objeto Carbon:

$user = App\User::find(1);

$skipCharge = true;
$nextDue = Carbon::now()->addDays(10);
$user->subscription('main')->swap('silver', $skipCharge, $nextDue);

Cancelando assinaturas

Para cancelar uma assinat