📘

O que você irá aprender com esse artigo?

• Criação de clientes
• Criação de planos
• Tokenização de cartão de crédito
• Como armazenar dados de cartão de crédito
• Criação de assinaturas

Caso de uso

“Quero poder cobrar dos meus clientes periodicamente, definindo um intervalo entre as cobranças para cada plano, isso de forma automática via cartão de crédito.”

Esse processo consiste em criar planos, nos quais são definidos os detalhes dessa cobrança, como periodicidade e produtos ou serviços atrelados a ele, e depois em criação de assinatura, em que você cria uma cobrança para os clientes, seguindo as especificações do plano.

Vamos entender melhor como funciona a estrutura dessas opções através da API?

Diagrama de sequência

🚧

Atenção!

A recorrência pode ser configurada para qualquer método de pagamento (PIX, boleto e cartão de crédito). Esse artigo irá mostrar como funciona para cartão de crédito, mas sua configuração pode ser replicada para os outros métodos.

Cadastrar cliente

Antes de qualquer coisa, você precisa que os seus clientes estejam cadastrados na plataforma. Apenas assim que você poderá criar uma assinatura. Para fazer esse cadastro, basta realizar uma chamada POST Criar cliente na API.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/customers' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=df598e45cd90947e522e12ec895a84f7059cacbc-1627922464' \
--data-raw '{
     "email": "[email protected]",
     "name": " iugu de sousa beserra",
     "phone_prefix":11,
     "phone": 951701035,
     "zip_code": "39560000",
     "number": "10",
     "street": "Salinas ",
     "city": "Minas gerais",
     "state": "Mg",
     "district": "Salinas "
}'

Modelo de response

Criar Plano

Imagine que você está criando uma assinatura num serviço de streaming. Lá você, antes de mais nada, tem que escolher seu plano, certo? Para criar uma cobrança recorrente, o plano também vem primeiro.

Na criação do plano você define a periodicidade da cobrança, ou seja, se ela será mensal, trimestral, anual, de x em x dias... Na iugu, você tem a liberdade para definir de acordo com as necessidades do seu negócio.

Além disso, você também consegue definir uma duração para o plano. Para isso, basta configurar o limite de ciclos. Por exemplo, o plano se encerra após 12 ciclos de cobranças mensais, fazendo com que o plano dure por um ano.

É possível definir os produtos e preços que vão ser usados para cobrança, ou manter o valor do plano é igual a zero.

Caso você tenha poucos planos definidos como padrão para todos os clientes, sem necessidade de alteração constante, recomendamos que defina os valores específicos de cada um no momento de criação do plano. Porém, se o seu modelo de recorrência tem variação de produtos e valores, mantendo o intervalo de cobrança, sugerimos que o preço do plano seja zero. Dessa maneira, você define o valor quando for criar a assinatura, sem a necessidade de criar diversos planos.

Para criar um plano, basta realizar um POST na api Criar Plano.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/plans' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=7a4a918b584a49f8bdedd9a35cf25d480cabefbc-1628521134' \ 
--data-raw '{ 
     "name": "testeIugu", 
     "identifier": "mensal_iugu", 
     "interval": 1, 
     "interval_type": "months", 
     "value_cents": 0, 
     "max_cycles": 0, 
     "billing_days": 1
     }'

Modelo de response

Tokenização do cartão de crédito

Toda vez que tiver de criar uma cobrança via cartão de crédito, esse tem de ser validado através do processo de tokenização, que basicamente garante segurança ao criptonizar os dados. Esse processo pode ser realizado de duas maneiras:

1. Iugu JS
   Para empresas que não são PCI Dss (Padrão de Segurança de Dados da Indústria de Pagamento com Cartão), o indicado e que o processo de tokenização utilize o método iugu.js. Com esse código de javascript inserido na sua webpage, você garante que os dados de cartão inseridos pelo cliente serão coletados apenas pelo front-end da sua aplicação. O método iugu.js irá retornar o token desse cartão que você poderá usar para realizar a cobrança direta ou criar a forma de pagamento.

2. Direto via Api
   Agora, se sua empresa tenha a certificação PCI Dss, você pode realizar esse processo de tokenização diretamente na API com uma chamada POST na API Criar Token, onde será gerado um token id e retornado no response.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/payment_token' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \ 
--data-raw '{ 
    "data": { 
        "number": "4532 1887 3049 3626", 
        "verification_value": "141", 
        "first_name": "teste ", 
        "last_name": "s beserra", 
        "month": "06", 
        "year": "2022" 
    }, 
    "account_id": "E6495D15290D47D3950C2A723D07A24E", 
    "method": "credit_card"//, 
    //"test": true - essa propriedade se igual true não deixa cadastrar cartão de teste. 
}'

Modelo de response

Armazenar os dados do cartão de crédito

Uma experiência de compra rápida e com poucos passos ajuda muito a evitar o abandono de carrinho. Uma maneira de garantir isso, é armazenar os dados de cartão para que o cliente não precise preencher novamente toda vez que realizar uma nova compra. Se o seu modelo de negócio tem essa necessidade, você precisa criar uma forma de pagamento com o cartão tokenizado na chamada Tokenizar Cartão.

Além disso, você precisa armazenar, ao lado de sua aplicação, o id do cliente (customer) e utilizá-lo na url da requisição. Dessa maneira, o cartão de crédito tokenizado será atribuído a um determinado cliente. Com isso, basta realizar uma chamada POST na API Criar Forma de Pagamento.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/customers/{customer_id}/payment_methods' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \ 
--data-raw '{ 
     "token": "{id to token}", 
     "description": "Teste iugu", 
     "set_as_default": true 
}'

Modelo de response

Criar assinatura

Com os planos criados, e as informações de cobrança do cliente cadastradas, você já pode criar as assinaturas. Para isso, basta ter o id do cliente (customer) e o identifier usado para criar o plano. Essas informações são necessárias para criar a requisição.

Também nessa chamada, você consegue definir quando a assinatura acaba com a propriedade expires_at, quais métodos de pagamentos o cliente pode usar para pagar a fatura através da payble_with. Você consegue ainda incluir itens, configurando assim o valor da assinatura na propriedade subitems. E caso a fatura não seja paga, você pode padronizar o cancelamento automático.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/subscriptions' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic {{api_token}}' \
--header 'Cookie: __cfruid=7a4a918b584a49f8bdedd9a35cf25d480cabefbc-1628521134' \ 
--data-raw '{ 
     "payable_with": [ 
          "credit_card" 
     ], 
     "subitems": [ 
          { 
               "description": "nome do item", 
               "price_cents": 1000, 
               "quantity": 1, 
               "recurrent": true 
          } 
     ], 
     "two_step": true, 
     "suspend_on_invoice_expired": true, 
     "only_charge_on_due_date": false, 
     "plan_identifier": "mensal_iugu", 
     "customer_id": "AF9598E489F0461FA32716335BD19144", 
     "expires_at": "09-08-2021", 
     "only_on_charge_success": true, 
     "ignore_due_email": false 
}'

Modelo de response

🚧

Parâmetro only_on_charge_success

Para ter mais agilidade na assinatura, é interessante que, para pagamentos no cartão de crédito, seja enviado o parâmetro only_on_charge_success true na API de Criar Assinatura. Isso faz com que a assinatura seja criada somente caso o pagamento no momento de assinatura retorne sucesso.

Melhorias

Tela de upgrade/downgrade de plano

Para alguns casos, é importante permitir que seu cliente altere seu plano ele mesmo pelo site. Para isso, deve ser criada uma tela de alteração de planos. A API utilizada é Alterar Plano da Assinatura.

Tela de gestão das formas de pagamento

Muitas vezes o cliente decide alterar seu cartão pois tem um novo, ou o antigo foi roubado, ou expirou. Para isso, é importante criar uma tela para a gestão dos mesmos. Idealmente a tela deve ter uma lista dos cartões cadastrados, uma possibilidade de escolher o padrão (será o cartão cobrado em cada ciclo da recorrência), remoção de cartões e adição de novos.
Veja as seguintes chamadas:

• Criar Forma de Pagamento
• Remover Forma de Pagamento
• Listar Formas de Pagamento
• Alterar Cliente: essa é utilizada para alterar a forma de pagamento padrão.

Tela de cancelamento e reativação

Infelizmente algum cliente pode eventualmente querer cancelar a recorrência. Para isso, o ideal é ter um botão onde o cliente desativa e reativa sua assinatura. Para isso, utilize a API de Suspender Assinatura e a de Ativar Assinatura.