Cobrança em duas etapas
O que você irá aprender com esse artigo?
- O que é cobrança em duas etapas
- Como habilitar cobrança em duas etapas na iugu
- Como realizar a captura ou cancelamento da fatura via AP
Caso de uso
“Vendedor possui um sistema de serviços, onde o cliente acessa o aplicativo e solicita um montador de móveis. O vendedor precisa garantir que o cliente terá saldo para pagar o serviço antes de deslocar o profissional que fará a montagem, mas ele deseja capturar o valor a ser pago apenas após a prestação do serviço, como garantia de que o trabalho foi feito.”
Diagrama de sequência
O que é uma cobrança em duas etapas
A cobrança em duas etapas é uma pré-autorização do valor de uma transação no cartão de crédito do comprador. Ou seja, basicamente é uma reserva desse valor no cartão que pode ser capturada ou cancelada após algumas horas ou após dias.
A cobrança em duas etapas, como o próprio nome diz, ocorre em duas sequencias de passos: a autorização e a captura.
A autorização ocorre quando as adquirentes vinculadas à iugu validam o cartão e verificam se há algum problema de limite, data de validade, dígitos do cartão, entre outros. Se estiver tudo certo a autorização é realizada com sucesso e nesse momento o valor é reservado no cartão do comprador. Nesse cenário, a fatura fica com status “Em análise".
A segunda etapa é a captura, onde o valor será capturado de fato, dessa forma, ele é debitado do cartão do cliente final. É possível também, ao invés de escolher a captura do valor, escolher o cancelamento da reserva.
Em todo caso, se em 7 dias corridos nenhuma das duas ações forem tomadas, o cancelamento será feito de forma automática pela iugu.
Como habilitar cobrança em duas etapas na iugu
Para habilitar este recurso é necessário acessar o painel da conta iugu e clicar em: Configurações > Cartão de Crédito > Fluxo de Pagamento em duas etapas.
Como realizar a captura ou cancelamento da autorização via API
Com o passo anterior, as faturas já estarão habilitadas para a cobrança em duas etapas. Então depois de ter a fatura criada e autorizada, o passo seguinte é a captura ou cancelamento dessa autorização.
Para melhor controle das faturas que precisam ser capturadas ou canceladas é recomendado o uso de gatilhos para verificar o status da transação. Nesse caso, crie um gatilho para o evento de invoice.status_changed.
Os gatilhos podem ser configurados pelo painel da conta, veja como fazer aqui. Para realizar a configuração via API é necessário realizar um POST na API de Criar Gatilho.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/web_hooks' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c225e22a406e3690b6b1b472c244bd81423884f6-1633892271' \
--data-raw '{
"event": "invoice.status_changed",
"url": "https://webhook.site/3e9fb0cc-523a-49f8-8acc-c2485d0954ac",
"authorization": "my_key"
}'
Modelo de response:
O primeiro passo é criar o comprador com seus respectivos dados, conforme a API de Criar cliente. Depois é necessário tokenizar o cartão, se tiver PCI é só criar o token na API de Criar Token e se não tiver é necessário utilizar o iugu.js. Para mais detalhes do iugu.js veja esse artigo. Caso seja necessário armazenar os dados do cartão para compras futuras, utilize a API de Criar Forma de Pagamento.
Com os dados do cliente é possível criar uma fatura que terá seu valor reservado.
Para isso é necessário realizar um POST na API de Criar Fatura.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/invoices' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c225e22a406e3690b6b1b472c244bd81423884f6-1633892271' \
--data-raw '{
"email": "[email protected]",
"due_date": "2021-10-10",
"ensure_workday_due_date": false,
"items": [
{
"description": "Item teste",
"quantity": 1,
"price_cents": 1000
}
],
"fines": false,
"late_payment_fine": 2,
"per_day_interest": false,
"per_day_interest_value": 5,
"payable_with": [
"all"
],
"customer_id": "844E3AB785AD4A78877CB2639DE4BAA3",
"order_id": "1633897104"
}'
Modelo de response
Autorizar a fatura
No retorno da criação da fatura pegue o id que foi retornado, que identifica essa fatura, para criar a autorização. Para autorizar a fatura, ou criar a reserva, faça um POST na API de Cobrança Direta.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/charge' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c225e22a406e3690b6b1b472c244bd81423884f6-1633892271' \
--data-raw '{
"customer_payment_method_id": "FDEB80CC57EA4BA1ADE6C7119CB702CD",
"invoice_id": "892CFB1F859940669B62BA0A433B5F10"
}'
Modelo de response
No momento da autorização da fatura será disparado um gatilho do invoice.status_changed informando o status da fatura como "in_analysis”. Essa notificação mostrará que a fatura se encontra em análise, ou seja, a reserva foi criada e ainda falta capturar o pagamento.
Modelo de gatilho
Até esse ponto há um valor reservado no cartão do cliente, ou seja, ele não pode usar o limite desse valor que foi gerado para outros pagamentos, pois ele está bloqueado. Mas esse valor ainda não foi debitado da conta dele, então o vendedor ainda não recebeu esse pagamento. Para isso, é necessário que seja feita uma captura dessa autorização ou que a reserva seja cancelada, se for o caso.
Capturar autorização
Depois de reservar aquele valor o passo seguinte é capturar a autorização. Nesse caso, envie o id da fatura que foi obtido através do gatilho ou que foi retornado na criação da fatura e faça um POST na API de Capturar fatura.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/invoices/{{invoice_id}}/capture' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c225e22a406e3690b6b1b472c244bd81423884f6-1633892271'
Modelo de response
Assim que a fatura for capturada, uma nova notificação será disparada avisando que a fatura teve seu status alterado para pago.
Cancelar autorização
Para cancelar a reserva basta informar o id da fatura que foi obtido através do gatilho ou que foi retornado na criação da fatura. Nesse caso é feito um PUT na API de Cancelar Fatura.
Modelo de request
curl --location --request PUT 'https://api.iugu.com/v1/invoices/{{invoice_id}}/cancel' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c225e22a406e3690b6b1b472c244bd81423884f6-1633892271'
Modelo de response
Assim que a fatura for cancelada, uma nova notificação será disparada avisando que a fatura teve seu status alterado para cancelado.
Modelo de gatilho
Updated over 2 years ago