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?api_token={{api_token}}' \ 

--header 'Content-Type: application/json' \ 

--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?api_token={{api_token}}' \ 

--header 'Content-Type: application/json' \ 

--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?api_token={{api_token}}' \ 

--header 'Content-Type: application/json' \ 

--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/892CFB1F859940669B62BA0A433B5F10/capture?api_token={{api_token}}' \ 

--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/309DAD1735A2446D9B05B98BE7DB4DBB/cancel?api_token=1A128BCC7CFCEAAE09625AFB122FD47547F7108FB2B1C0EF1ACC817DCA08760D' \ 

--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


Did this page help you?