fluxo de compra 3DS
Gerenciar a autenticação pendente, apresentar a próxima ação e confirmar o status final do pagamento.
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.
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:
- Crie um pedido com Criar pedido, então pague com Criar pagamento.
- 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:
{
"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:
| Campo | Significado | Ação |
|---|---|---|
order.payment.data.status | pending_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.action | Identifica 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_challenge | URL 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:
- Utilize a URL retornada
url_challenge; não construa uma URL 3DS. - 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.
- Mantenha as URLs de sucesso, falha e retorno.
- 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:
- os webhooks de status de pagamento configurados e verificados para atualizações no backend; e
- Obtenha o pedido quando o cliente retorna ou quando seu sistema precisa reconciliar um resultado incerto.
| Resultado | Significado | Ação de conclusão |
|---|---|---|
processed | Compra concluída. | Conclua após a validação das suas regras de negócio. |
authorized | Os fundos foram autorizados, mas não capturados. | Siga sua estratégia de captura; não trate como capturado. |
pending_3ds | O 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 authorizing | O pagamento ainda está em andamento. | Continue a reconciliação; não envie outra compra para concluir o 3DS. |
denied, cancelled, ou expired | O 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_3dsmais umaauthorization_3dsaçã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.