Exiba o desafio 3DS

Quando o emissor pede que o comprador prove ser o dono do cartão (com senha do app do banco ou código por SMS), a criação da cobrança retorna status: "RequiresAction" e um nextAction com a URL do desafio. O seu checkout abre essa URL num iframe; o resto da conversa com o banco acontece lá dentro.

{
  "id": "e092c6cc-8d6f-47d3-8616-df99670286dd",
  "object": "payment_intent",
  "amount": 10000,
  "currency": "BRL",
  "status": "RequiresAction",
  "statusDetail": "PENDING_CHALLENGE",
  "nextAction": {
    "type": "IFRAME_CHALLENGE",
    "url": "URL_DE_DESAFIO_RETORNADA_PELA_API",
    "authenticationId": "6c868afc-d6bc-45c4-9886-ed97d20a2729",
    "expiresAt": "2026-09-08T15:10:00Z"
  }
}

Use nextAction.url inteira, sem montar a URL a partir do authenticationId.

1. Abra o iframeCopiar link da seção

Registre o listener de mensagens antes de carregar o iframe, para não perder uma resposta rápida.

const frame = document.createElement('iframe');
frame.title = 'Verificação do pagamento';
frame.style.width = '100%';
frame.style.maxWidth = '420px';
frame.height = '600';

const hooksOrigin = new URL(DM_HOOKS_BASE).origin;

function onChallengeMessage(event) {
  // Aceite só mensagens da Hooks, vindas deste iframe.
  if (event.origin !== hooksOrigin) return;
  if (event.source !== frame.contentWindow) return;

  let msg;
  try {
    msg = JSON.parse(event.data); // a mensagem é uma string JSON
  } catch {
    return;
  }
  if (!msg || typeof msg !== 'object') return;

  if (msg.type === 'card_3ds.processing') {
    showPending(); // não feche o iframe: o resultado final ainda pode chegar
    return;
  }

  if (msg.type === 'card_3ds.succeeded' || msg.type === 'card_3ds.failed') {
    window.removeEventListener('message', onChallengeMessage);
    frame.remove();
    refreshOrderFromYourBackend(paymentIntentId);
  }
}

window.addEventListener('message', onChallengeMessage);
frame.src = nextAction.url;
document.getElementById('challenge-container').appendChild(frame);

showPending e refreshOrderFromYourBackend são funções do seu checkout. A segunda consulta o seu backend, que por sua vez consulta o PaymentIntent na API. O navegador nunca libera o pedido sozinho.

2. Interprete as mensagensCopiar link da seção

Cada mensagem é uma string JSON com três campos: type, authentication_id e detail.

Regras de entrega:

• Cada desafio envia no máximo uma mensagem final (succeeded ou failed) e no máximo uma processing.
• processing não encerra o fluxo: uma mensagem final pode chegar depois dela.
• O authentication_id pode mudar dentro do mesmo pagamento, se o banco pedir um segundo desafio. Não use esse campo para filtrar mensagens.

3. Confirme pelo servidorCopiar link da seção

Depois de qualquer mensagem final, o seu backend consulta GET /api/v1/paymentintents/{id} e decide:

O webhook payment_intent.succeeded também confirma a aprovação. Não há webhook específico para o desafio 3DS.

Comprador que sai e voltaCopiar link da seção

Fechar o iframe ou recarregar a página não cancela a cobrança. Quando o comprador voltar ao checkout, consulte o PaymentIntent: se ele continuar RequiresAction com nextAction.expiresAt no futuro, reabra o desafio com a mesma nextAction.url. Se já tiver um desfecho, siga por ele.