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
A integração 3DS é um fluxo de trabalho de pagamento. Crie o pagamento normalmente, responda quando a DEUNA retornar pending_3ds, apresente a próxima ação retornada e aguarde o status final de pagamento autorizado.
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 capaz de desafiar segue este formato:
{
"order": {
"order_id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"status": "pending",
"payment": {
"data": {
"id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"method_type": "credit_card",
"status": "pending_3ds",
"next_action": {
"action": "authorization_3ds",
"authorization_3ds": {
"version": "2.2.0",
"url_challenge": "https://api.deuna.io/transactions/next-action/...",
"three_ds_flow_id": "0f5a8f52-7f95-4a1f-9ee8-e92946547ea9"
}
}
}
}
}
}Use estes campos como fonte da verdade:
| Campo | Significado | Ação |
|---|---|---|
order.payment.data.status | pending_3ds significa que a autenticação não foi concluída. | Mantenha o pagamento sem solução e apresente a próxima ação. |
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 DEUNA de curta duração para a experiência de autenticação. | Abra-o apenas no modo de apresentação compatível com a conexão. |
order.payment.data.next_action.authorization_3ds.three_ds_flow_id | Correlaciona o fluxo de autenticação. | Retenha para solução de problemas; não o utilize como comprovante de pagamento. |
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.
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.
4. Aguarde o status final do pagamento#
Enquanto a autenticação estiver ativa, o pagamento permanece pending_3ds. A autenticação bem-sucedida apenas permite a autorização de prosseguir; não significa que o dinheiro foi transferido.
Utilize ambos:
- Webhooks DEUNA para alterações de status assíncronas; 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 | A autenticação ainda não foi concluída. | Aguarde; não processe ou reinicie automaticamente. |
processing ou authorizing | O pagamento ainda está em andamento. | Continue a reconciliação. |
denied, cancelled, ou expired | O pagamento não foi concluído. | Exiba um resultado recuperável e inicie uma nova tentativa somente quando apropriado. |
Consulte Fluxo de Pagamento & Statuses para cada estado e transição de pagamento pública.
5. Implemente a autenticação sem atrito#
A autenticação sem atrito pode não retornar pending_3ds porque o emissor pode autenticar e permitir que a autorização continue na mesma solicitação. Seu código deve, portanto, suportar ambos os 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.
6. Tempos limite e novas tentativas#
As janelas de desafio do emissor variam. DEUNA pode manter um pagamento em pending_3ds até a janela de autenticação configurada; a proteção de serviço atual não excede 10 minutos. Após a expiração, o pagamento passa para um estado de falha relatado e o comprador deve iniciar uma nova tentativa de pagamento.
- 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.
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.