📘

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