Download the PHP package potelo/gu-payment without Composer

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:

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

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

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

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.

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.

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:

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.

Assinatura com subitens

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

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

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:

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:

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:

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:

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:

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:

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:

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

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:

Para utilizar o objeto do Iugu a partir da assinatura, utilize o método 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:

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:

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

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:

Cancelando assinaturas

Para cancelar uma assinatura, basta chamar o método cancel na assinatura do usuário:

Ao cancelar uma assinatura, ela continua ativa até o dia do vencimento. Para cancelar uma assinatura imediatamente utilize o método cancelNow:

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:

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:

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:

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:

Tratando os gatilhos (ou Webhooks)

Gatilhos (ou Webhooks) 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:

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 para essa rota. Você pode colocar a URL em except no middleware VerifyCsrfToken:

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.

Caso queira testar os webhooks em ambiente local, você pode utilizar o ngrok.

Faturas

Você pode facilmente pegar as faturas de um usuário através do método invoices:

Esse método irá trazer apenas as faturas que já foram pagas, caso queira incluir as faturas pendentes, basta passar o primeiro parâmetro como true:

Você pode listar as faturas de um usuário e disponibilizar pdfs de cada uma delas. Por exemplo:

Para gerar o pdf basta utilizar o método downloadInvoice:

Faturas avulsas

Se você precisar criar faturas avulsas, que não estejam relacionadas a assinatura, basta usar o método createInvoice:

Caso você precise gerar uma fatura com vários itens, utilize os métodos newInvoice, addItem e create:

Reembolsar Fatura

Para reembolsar uma fatura utilize o método refund:

Gerar Segunda Via de Fatura (Apenas BOLETO)

Para gerar uma segunda via de boleto de uma fatura utilize o método duplicate

Clientes e métodos de Pagamento (Cartões)

Para gerenciar os métodos de pagamento, o cliente precisa existir no Iugu. Quando você utiliza o método newSubscription o cliente é criado automaticamente. Porém para criar um cliente manualmente, você pode utilizar o método createAsIuguCustomer.

Para acessar o cliente do Iugu a partir do usuário, utilize o método asIuguCustomer:

Após ter um cliente cadastrado no Iugu, você pode gerenciar seus métodos de pagamento. Para criar um cartão utilize o método createCard:

O método aceita um array como segundo argumento com as opções disponíveis para criação de um método de pagamento. O cartão é criado sendo definido como default nos cartões do cliente. Se quiser alterar esse comportamento passe a chave set_as_default com o valor false nas opções do segundo parâmetro do método:

Para obter os cartões de um cliente você pederá utilizar os métodos cards (Retorna uma Illuminate\Support\Collection de cartões), findCard (Retorna uma instância de Potelo\GuPayment\Card ou null se o cartão não for encontrado) ou findCardOrFail (Retorna uma instância de Potelo\GuPayment\Card ou lança uma exceção caso o cartão não seja encontrado):

Para deletar um cartão apenas obtenha uma instância de Potelo\GuPayment\Card e use o metodo deleteCard:

Para deletar todos os cartões use deleteCards:

Cobrança simples

Se você quiser fazer uma cobrança simples com o cartão de crédito, você pode usar o método de charge em uma instância de um usuário que use o Trait GuPaymentTrait. Para utilizar a cobrança simples nesse pacote, é necessário que o cliente já esteja cadastrado no Iugu.

O método charge aceita um array como segundo parâmetro, permitindo que você passe algumas opções desejadas para criação de uma cobrança no Iugu. Consulte a documentação do Iugu para saber as opções disponíveis ao criar uma cobrança:

Por padrão um item será criado com as seguintes definições:

Sinta-se livre para adicionar seus próprios items como preferir no segundo parâmetro:

OBS: Se um array de items for passado no segundo argumento o item padrão não será adicionado.