Pular para o conteúdo principal
Nesta página

Envie o pagamento com cartão uma única vez, apresente qualquer próxima ação 3DS retornada e verifique o resultado do pagamento no backend. A experiência de autenticação pode coletar sinais do navegador, terminar sem desafio ou solicitar que o cliente se autentique com seu banco.

Diagrama de fluxo
processedauthorizedAinda pendente ou emprocessamentoSem sucesso1Envie o pagamentouma única vez2Trate next_actionquando retornadoVerificações donavegador e desafioopcional3A DEUNA conclui ouconfirma oprocessamento dopagamento4Verifique o pedidooriginal no backend5Status atual dopagamento6Aplique a políticade entrega7Siga a política decaptura acordada8Mantenha pendente ereconcilie depois9Mostre o resultado eavalie se é possíveltentar novamente
DEUNAResultadoRevisão ou pendente

A autenticação pode falhar ou ser interrompida em qualquer etapa. O diagrama mostra o percurso normal; o status atual do pagamento determina se você deve aguardar, concluir a entrega ou oferecer recuperação.

Responsabilidades da sua integração#

Seu backend cria o pagamento e verifica o resultado. Seu checkout apresenta a ação retornada e mantém o contexto do pedido original. A DEUNA coordena verificações do navegador, autenticação e qualquer autorização restante com o provedor conectado; o emissor controla o desafio e a decisão de autenticação.

Não crie sua própria sequência de chamadas de autenticação ao provedor nem presuma que cada etapa do diagrama exige uma solicitação de API separada do comerciante. Use a ação retornada por meio da integração compatível com sua conexão.

1. Criar o pagamento#

Use um dos padrões de pagamento com cartão suportados:

  1. Crie um pedido com Criar pedido, então pague com Criar pagamento.
  2. Use a solicitação única Criar pagamento fluir quando for adequado à sua integração.

Envie informações completas do comprador, faturamento, pedido e dispositivo. Esses sinais ajudam o emissor a decidir se a autenticação pode ser simples.

2. Inspecione a resposta de pagamento#

Uma resposta 3DS pendente pode incluir os campos a seguir. Este exemplo mostra apenas os campos necessários para continuar o fluxo:

JSON
{
  "order": {
    "payment": {
      "data": {
        "status": "pending_3ds",
        "next_action": {
          "action": "authorization_3ds",
          "authorization_3ds": {
            "url_challenge": "https://api.deuna.io/transactions/next-action/NEXT_ACTION_ID"
          }
        }
      }
    }
  }
}

Use estes campos como fonte da verdade:

CampoSignificadoAção
order.payment.data.statuspending_3ds significa que o fluxo de pagamento 3DS está sem resolução.Mantenha a entrega bloqueada e trate a ação retornada.
order.payment.data.next_action.actionIdentifica a ação necessária do cliente.Alça authorization_3ds com o SDK DEUNA suportado ou dados de desafio retornados.
order.payment.data.next_action.authorization_3ds.url_challengeURL da DEUNA para a próxima etapa de autenticação, que pode incluir verificações do navegador antes de um desafio.Use exatamente a URL retornada no modo de apresentação compatível com a conexão.

Para compatibilidade, algumas integrações também podem receber um nível superior authorization_3ds objeto. Novas implementações devem preferir next_action.

3. Apresente a próxima ação#

SDK Web

Uso initNextAction(...) quando você deseja que o DEUNA gerencie o comportamento modal, iframe ou redirecionamento suportado. Veja o Referência do SDK da Web.

Se um Payment Widget da DEUNA já gerencia a jornada de pagamento, deixe que ele trate a ação retornada. Não abra uma segunda instância de Next Action para a mesma tentativa. Para um formulário de pagamento próprio do comerciante, consulte o Widget Next Action.

Integração direta com o navegador

Se você gerencia a próxima etapa:

  1. Utilize a URL retornada url_challenge; não construa uma URL 3DS.
  2. Siga o modo de apresentação configurado. Não force a exibição de uma página do emissor em um iframe quando um redirecionamento de nível superior for necessário.
  3. Mantenha as URLs de sucesso, falha e retorno.
  4. Trate uma janela fechada, callback ou redirecionamento como um sinal para recuperar o estado – e não como um sinal de sucesso do pagamento.

Aplicativos nativos

Utilize o SDK DEUNA suportado ou um navegador/visual web seguro. Configure a URL de retorno/deep link e restaure o contexto de pagamento quando o cliente retornar ao aplicativo.

Verificações do navegador antes de um desafio

A experiência retornada pode coletar sinais do navegador e do dispositivo antes de o emissor decidir se solicita um desafio. Essa etapa não exige que o cliente digite um código ou aprove um pagamento. Mantenha a tela de carregamento e a superfície de autenticação disponíveis até que o fluxo continue.

Se a coleta de dados do navegador não terminar dentro do período de espera, o fluxo gerenciado poderá continuar com esse resultado. Isso, por si só, não significa que a autenticação falhou ou que o pagamento foi concluído. Não substitua a ação retornada por uma falha baseada em um temporizador local nem inicie outra compra.

4. Aguarde o status final do pagamento#

O término das verificações do navegador, a conclusão do desafio, uma URL de retorno e um callback do SDK são sinais para reconciliar o pedido original. Nenhum deles comprova que os fundos foram cobrados. A autenticação pode terminar junto com a autorização, ou a DEUNA ainda pode precisar concluir o pagamento depois.

Utilize ambos:

ResultadoSignificadoAção de conclusão
processedCompra concluída.Conclua após a validação das suas regras de negócio.
authorizedOs fundos foram autorizados, mas não capturados.Siga sua estratégia de captura; não trate como capturado.
pending_3dsO fluxo 3DS permanece sem resolução, com ou sem um desafio visível.Mantenha a experiência atual disponível; não conclua a entrega nem reinicie automaticamente.
pending, processing, ou authorizingO pagamento ainda está em andamento.Continue a reconciliação; não envie outra compra para concluir o 3DS.
denied, cancelled, ou expiredO pagamento não foi concluído.Exiba um resultado recuperável e inicie uma nova tentativa somente quando apropriado.

Veja Fluxo de Pagamento & Statuses para cada estado e transição de pagamento pública.

5. Implemente a autenticação sem atrito#

Frictionless significa que o cliente não realiza um desafio do emissor. Ainda assim, pode exigir a experiência de navegador retornada para coletar sinais do dispositivo e permitir a continuidade do processamento do pagamento. Seu código deve aceitar os dois resultados:

  • um status de pagamento final ou em andamento imediato; ou
  • pending_3ds mais uma authorization_3ds ação subsequente.

Não é necessário que haja uma URL de desafio para determinar se o 3DS foi avaliado.

Um pagamento bem-sucedido sem desafio não comprova, por si só, que a autenticação 3DS foi concluída com sucesso. Use os detalhes de autenticação informados quando necessário para suporte ou análise de responsabilidade.

6. Tempos limite e novas tentativas#

A coleta de dados do navegador, o carregamento da tela do desafio, a autenticação do emissor e o processamento do pagamento têm períodos de espera diferentes. Um atraso no carregamento ou um tempo limite local não determina o resultado do pagamento. Confirme a janela de autenticação aplicável à sua conexão durante a certificação; não defina uma duração universal fixa para desafios.

  • Não reutilize um URL de desafio expirado.
  • Não crie tentativas repetidas de pagamento enquanto o primeiro pagamento permanecer sem solução.
  • Use o status final e allow_retry/orientação de erro padronizada quando disponível antes de oferecer outra tentativa.
  • Se o roteamento selecionar outra conexão compatível, deixe a DEUNA decidir se um resultado de autenticação existente pode ser reutilizado.

Após o fechamento de uma tela, uma interrupção de rede ou um tempo limite, consulte o pedido original antes de oferecer outra tentativa. Se o pagamento continuar sem resolução, mostre um resultado pendente e continue a reconciliação. Se não tiver sucesso, aplique o erro e a elegibilidade de nova tentativa informados. O fechamento no cliente não garante o cancelamento do pagamento no backend.

7. Interprete os detalhes de autenticação com segurança#

O painel administrativo da DEUNA pode exibir resultados técnicos do 3DS, como a versão do protocolo, o tipo de fluxo, o ECI, o resultado da autenticação e os identificadores da transação de rede. Utilize-os para suporte, reconciliação e análise de disputas.

Não armazene ou exponha criptogramas brutos, respostas de autenticação completas ou o código HTML do desafio nos logs do comerciante. O status do pagamento – e não o ECI ou o evento de conclusão do desafio – controla a finalização.