Cobranças recorrentes por API
A recorrência é uma excelente estratégia para fidelizar clientes e garantir uma maior previsibilidade de caixa. Configurar esse tipo de cobrança de acordo com as necessidades do seu negócio é fácil e direto via API.
O que você irá aprender com esse artigo?
- Os principais endpoints de Assinatura
- Sequência de Chamadas
- Como criar Plano
- Como criar Cliente
- Como criar Assinatura
- Como criar e Listar Forma de Pagamento
Caso de uso
“Quero poder cobrar meus clientes periodicamente, definindo intervalos específicos entre as cobranças para cada plano, tudo de forma automática via cartão de crédito.”
Recorrência na iugu
O processo de cobranças recorrentes envolve dois passos principais:
- Criar Plano —
v1/plans
: são definidos os detalhes da cobrança, como periodicidade e produtos ou serviços associados. - Criar Assinatura —
v1/subscriptions
: que gera cobranças automáticas para os clientes conforme as especificações do plano.
Métodos de Pagamentos Compatíveis
Todos os métodos de pagamento são compatíveis, porém, com comportamentos diferentes.
Método | Pagamento automático | Renovação após |
---|---|---|
Cartão de Crédito | ✅ | transação aprovada |
Boleto Bancário | ❌ | 2 dias úteis (compensação) |
Pix | ❌ | transação bem sucedida |
Cartão de Crédito
Se o seu Plano/Assinatura aceitam Cartão de Crédito (credit_card
) como forma de pagamento, então não há a necessidade do cliente fazer o pagamento manual da fatura.
Boleto Bancário
Já para Boleto Bancário (bank_slip
), o cliente precisará acessá-lo e pagá-lo manualmente.
Pix
O Pix (pix
) conta com a mesma dinâmica do boleto, porém, será via pix.
Importante
Antes de criar o Plano e/ou Assinatura, certifique-se de que o método escolhido esteja habilitado em sua conta iugu.
Sequência de Chamadas
O passo a passo a seguir simula:
- A contratação de uma assinatura mensal (a cada 1 mês)
- Dados de contato como nome (
name
) e e-mail (email
), foram coletados previamente - Os dados do cartão de crédito já foram coletados e tokenizados. Saiba mais
1. Criar Plano
Já tem um plano criado? Pule para a etapa 2. Se não, utilize o endpoint Criar Plano — v1/plans
. Atente-se aos parâmetros:
identifier
— Identificador do Plano. Utilize-o como uma tag que identifica o planointerval_type
— Meses (months
) ou Semanas (weeks
)interval
— Quantidade de intervalos de Meses ou Semanas
"E como fica uma assinatura anual?"
Simples! O
interval_type
será do tipomonths
(meses) e o interval será12
.
Request exemplo
curl --request POST \
--url 'https://api.iugu.com/v1/plans?api_token=<seu-api_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"name": "Nome do Plano",
"identifier": "dev_basic",
"interval": 1,
"interval_type": "months",
"value_cents": 1000,
"payable_with": [
"credit_card"
],
"features": [
{
"name": "Nome da funcionalidade",
"identifier": "id_function",
"value": 1
}
]
}
'
2. Criar um Cliente
Já tem um cliente criado? Pule para a etapa 3. Se não, utilize o Criar Cliente — v1/cutomers
. Preencha os parâmetros obrigatórios:
email
— E-mail do clientename
— Nome do cliente
Request exemplo
curl --request POST \
--url 'https://api.iugu.com/v1/customers?api_token=<seu-api_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"email": "[email protected]",
"name": "Nome do Cliente"
}
'
3. Criar Forma de Pagamento
Se a forma de pagamento já existe: Utilize o Listar Formas de Pagamento — GET
v1/customers/{customer_id}/payment_methods
para obter seu id
e pule para a etapa 4.
Se não: Utilize o Criar Forma de Pagamento — POST
v1/customers/{customer_id}/payment_methods
.
Preencha os parâmetros obrigatórios:
customer_id
— ID do Cliente (etapa 2)description
— Descrição do cartão. Também usado como "apelido" ou "nome do cartão"token
— Dados do cartão tokenizados (saiba mais)
E escolha se este cartão será a forma de pagamento padrão (favorito) deste cliente ou não:
set_as_default
—true
oufalse
Request exemplo
curl --request POST \
--url 'https://api.iugu.com/v1/customers/7112C74C949A4195805265251C76ACF6/payment_methods?api_token=<seu-api_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"description": "Nome ou Descrição deste Cartão",
"token": "53dd7091-05c7-4782-9eac-Censurado",
"set_as_default": true
}
'
4. Criar Assinatura
Utilize o endpoint Criar Assinatura — v1/subscriptions
. Atente-se aos parâmetros:
O que a Assinatura herda do Plano?
Os parâmetros abaixo, quando não preenchidos nesta chamada, herdam os valores do Plano — POST
v1/plans
(etapa 1):
payable_with
— do parâmetropayable_with
price_cents
— do parâmetrovalue
do objetofeatures
(ou a soma deles)
only_on_charge_success
Incentivamos a utilização do parâmetro
only_charge_on_success
comotrue
. Desse modo, a Assinatura será criada apenas se a cobrança inicial for bem-sucedida.
Quando é a primeira cobrança de uma Assinatura
Quando é a primeira vez que esta Assinatura está sendo criada, no retorno deste endpoint será exibido o invoice_id
parâmetro recent_invoices
.
Quando é a cobrança de uma Assinatura já criada
Já nas próximas cobranças dessa Assinatura, aciona o gatilho Fatura Criada — invoice.created
, Mudança de Status da Fatura — invoice.status_changed
e Fatura Liberada — invoice.released
.
Request exemplo
curl --request POST \
--url 'https://api.iugu.com/v1/subscriptions?api_token=<seu-api_token>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"customer_id": "7112C74C949A4195805265251C76ACF6",
"plan_identifier": "dev_basic"
}
'
Passo a passo em diagrama
O passo a passo acima pode ser ilustrado com o seguinte diagrama de sequência.
![](https://files.readme.io/3603bac-Group_12.png)
Features complementares
Há outros endpoints que permitem disponibilizar outros recursos aos assinantes. Por exemplo:
Suspender e Reativar Assinatura
Os endpoints abaixo permitem Suspender e/ou Ativar uma Assinatura:
- Ativar Assinatura —
v1/subscriptions/{id}/activate
- Suspender Assinatura —
v1/subscriptions/{id}/suspend
Upgrade/downgrade de Plano
O endpoint Alterar Plano da Assinatura — v1/subscriptions/{id}/change_plan/{plan_identifier}
permite alterar o Plano da Assinatura do assinante.
Gestão de Forma de Pagamento
Os endpoints abaixo permitem a gestão das formas de pagamento:
- Criar Forma de Pagamento —
POST
v1/customers/{customer_id}/payment_methods
- Remover Forma de Pagamento —
DELETE
v1/customers/{id}
- Listar Forma de Pagamento —
GET
v1/customers/{customer_id}/payment_methods
- Editar Cliente —
PUT
v1/customers/{id}
(parâmetrodefault_payment_method_id
)
Updated 4 months ago