PHPackages flatbox-giganti/gu-payment - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. flatbox-giganti/gu-payment ActiveLibrary[Payment Processing](/categories/payments) flatbox-giganti/gu-payment ========================== GuPayment fornece uma interface para controlar assinaturas do iugu.com 2.15.1.0(5y ago)0331MITPHPPHP >=5.6 Since Mar 9Pushed 5y agoCompare [ Source](https://github.com/flatbox-giganti/GuPayment)[ Packagist](https://packagist.org/packages/flatbox-giganti/gu-payment)[ RSS](/packages/flatbox-giganti-gu-payment/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (3)Dependencies (6)Versions (35)Used By (0) [![](https://user-images.githubusercontent.com/3699061/82709406-ea491500-9c56-11ea-94e0-08fbc73c4dc9.png)](https://user-images.githubusercontent.com/3699061/82709406-ea491500-9c56-11ea-94e0-08fbc73c4dc9.png) [![Build status](https://camo.githubusercontent.com/a0f90defa51a60b0979cb967d44c5979127622d20cfe29dd192ec07137988ce5/68747470733a2f2f7472617669732d63692e6f72672f506f74656c6f2f47755061796d656e742e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/Potelo/GuPayment) [![Coverage Status](https://camo.githubusercontent.com/34aba3ceee5221a3602a8b22ded980422cb537eebd2414d7f2b2ddf5c90094f6/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f506f74656c6f2f47755061796d656e742f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/Potelo/GuPayment?branch=master)[![Packagist Downloads](https://camo.githubusercontent.com/b39396b7535b404973563ee48d669bd01ccb108b361b363be88007e58cae9977/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706f74656c6f2f67752d7061796d656e743f636f6c6f723d253233306237636264)](https://packagist.org/packages/potelo/gu-payment)[![Packagist Version](https://camo.githubusercontent.com/ee3ee7f8e449e95ea7de150670da795a7fbf321c81a45c6dbf1a73a00e04aa03/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706f74656c6f2f67752d7061796d656e743f636f6c6f723d253233333361326438)](https://packagist.org/packages/potelo/gu-payment) Introdução ---------- [](#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 ---------- [](#instalação) Instale esse pacote pelo composer: ``` composer require potelo/gu-payment ``` Se você não utiliza o [auto-discovery](https://medium.com/@taylorotwell/package-auto-discovery-in-laravel-5-5-ea9e3ab20518), 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 ----------- [](#assinaturas) ### Criando 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](https://iugu.com/referencias/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 [](#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 [](#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 [](#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](https://dev.iugu.com/reference#criar-assinatura) ### Tratamento de erros [](#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 [](#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 `subscribed`pode 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 [](#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](https://support.iugu.com/hc/pt-br/articles/201727517-Como-funcionam-as-trocas-de-planos-durante-o-per%C3%ADodo-de-uso-) 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); ``` ### Cancelando assinaturas [](#cancelando-assinaturas) Para cancelar uma assinatura, basta chamar o método `cancel` na assinatura do usuário: ``` $user->subscription('main')->cancel(); ``` Ao cancelar uma assinatura, ela continua ativa até o dia do vencimento. Para cancelar uma assinatura imediatamente utilize o método `cancelNow`: ``` $user->subscription('main')->cancelNow(); ``` ### Reativando assinaturas [](#reativando-assinaturas) Se um usuário tem uma assinatura cancelada e gostaria de reativá-la, basta utilizar o método `resume`. Ele precisa está no "período de carência" para conseguir reativá-la: ``` $user->subscription('main')->resume(); ``` Assinatura trial ---------------- [](#assinatura-trial) Se você desejar oferecer um período trial para os usuários, você pode usar o método `trialDays` ao criar uma assinatura: ``` $user = User::find(1); $user->newSubscription('main', 'gold') ->trialDays(10) ->create($creditCardToken); ``` O usuário só será cobrado, após o período trial. Lembrando que para verificar se um usuário está com a assinatura no período trial, basta chamar o método `onTrial`: ``` if ($user->subscription('main')->onTrial()) { // } ``` O método `chargeOnSuccess` não funciona na criação de assinatura com trial. Caso queira validar o cartão de crédito do usuário, você pode utilizar o método `validateCard` na criação da assinatura. O que vai ser feito no iugu é uma cobrança de R$ 1,00 e depois o estorno dessa cobrança. Caso o pagamento seja realizado com sucesso, a assinatura é criada: ``` $user = $this->createUser(); // Create Subscription $user->newSubscription('main', 'gold')->validateCard()->create($this->getTestToken()); ``` Tratando os gatilhos (ou Webhooks) ---------------------------------- [](#tratando-os-gatilhos-ou-webhooks) [Gatilhos (ou Webhooks)](https://iugu.com/referencias/gatilhos) são endereços (URLs) para onde a Iugu dispara avisos (Via método POST) para certos eventos que ocorrem em sua conta. Por exemplo, se uma assinatura do usuário for cancelada e você precisar registrar isso em seu banco, você pode usar o gatilho. Para utilizar você precisa apontar uma rota para o método `handleWebhook`, a mesma rota que você configurou no seu painel do Iugu: ``` Route::post('webhook', '\Potelo\GuPayment\Http\Controllers\WebhookController@handleWebhook'); ``` O GuPayment tem métodos para atualizar o seu banco de dados caso uma assinatura seja suspensa ou ela expire. Apontando a rota para esse método, isso ocorrerá de forma automática. Lembrando que você precisa desativar a [proteção CRSF](https://laravel.com/docs/5.2/routing#csrf-protection) para essa rota. Você pode colocar a URL em `except` no middleware `VerifyCsrfToken`: ``` protected $except = [ 'webhook', ]; ``` ### Outros gatilhos [](#outros-gatilhos) O Iugu possui vários outros gatilhos e para você criar para outros eventos basta estender o `WebhookController`. Seus métodos devem corresponder a **handle** + o nome do evento em "camelCase". Por exemplo, ao criar uma nova fatura, o Iugu envia um gatilho com o seguinte evento: `invoice.created`, então basta você criar um método chamado `handleInvoiceCreated`. ``` Route::post('webhook', 'MeuWebhookController@handleWebhook'); ``` ```