Skip to main content
POST
No 3DS gerenciado, a cobrança de cartão é criada com threeDSMode managed e, quando o banco pede verificação ou desafio, fica no status authentication_required até o comprador se autenticar. Esta rota é a continuação: ela recebe o resultado da autenticação, processa a cobrança e dispara os webhooks e o postback. A resposta tem o mesmo formato da resposta de criação de cobrança. Quem chama esta rota é a página de autenticação aberta pela authenticationUrl, depois que o comprador conclui a verificação. No fluxo gerenciado, a sua integração não precisa chamá-la: ela cria a cobrança, abre a authenticationUrl e acompanha o resultado por webhook ou por GET /v1/charges/{id}. Veja o guia do 3DS gerenciado.

Quando usar

Para o negócio: no 3DS gerenciado, a cobrança existe desde o início, mas só é processada quando esta rota é chamada com o resultado da autenticação. Enquanto ela estiver em authentication_required, o pedido não está pago.

Antes de chamar

  • A cobrança precisa ter sido criada em POST /v1/charges com paymentMethod.threeDSMode managed e o objeto browser, e estar com status authentication_required.
  • Os dados do cartão da cobrança ficam guardados por 15 minutos. Depois disso, a retomada falha com 422.
  • O resultado da autenticação 3DS vem de POST /v1/three-ds/challenge-result.
  • Use a chave pública (pk_, ou pk_test_ no sandbox) como usuário do Basic, com senha vazia.

Parâmetros de caminho

string
required
ID da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.

Corpo da requisição

object
required
Dados da autenticação 3D Secure (schema CreditCardThreeDS). O objeto é obrigatório: threeDS: null responde 400. Nos campos opcionais, omita o campo quando não tiver valor. Não envie null: um null sobrescreve o valor que já estava guardado na cobrança.
O schema CreditCardThreeDS também lista mode, deviceData e challenge. Não envie esses campos: mode é de uso interno e deviceData e challenge não são lidos no 3DS da Finvia.

Respostas

A resposta 200 tem o formato da cobrança criada (schema CreatedCharge).
string
required
Identificador único da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
string
required
Status da cobrança depois do processamento: paid, pending, refused ou failed. Ex.: paid.
object | null
required
Detalhes do cartão usado.
string | null
required
Motivo do status, principalmente em cobranças recusadas. Quando a autenticação não passou, vem no formato 3ds_<estado>: Authentication did not succeed.
Os erros vêm no formato { statusCode, message, error }. Trate o erro pelo código HTTP, não pelo texto: as mensagens misturam português e inglês e são exibidas aqui exatamente como a API devolve.
Depois de um 422, a cobrança não é processada e não pode mais ser retomada. Crie uma nova cobrança. Não trate a cobrança antiga como paga.
O código 200 confirma que a cobrança foi processada. Para saber se ela foi paga, leia o status: paid libera o pedido; refused e failed encerram a tentativa, com o motivo em reason.

Erros comuns

Veja também

3DS gerenciado

Guia do fluxo gerenciado pela Finvia.

Criar uma cobrança

Campos threeDSMode, browser e authenticationUrl.

Obter resultado do 3DS

Origem do objeto threeDS.

Webhooks de cobrança

Eventos disparados após a retomada.