Download the PHP package potelo/gu-payment without Composer

On this page you can find all versions of the php package potelo/gu-payment. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package gu-payment

Build status Coverage Status Packagist Downloads Packagist Version

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.


All versions of gu-payment with dependencies

PHP Build Version
Package Version
Requires php Version >=7.4
iugu/iugu Version dev-master
dompdf/dompdf Version ^0.8.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package potelo/gu-payment contains the following files

Loading the files please wait ....