Incluindo o script

Adicione o script na sua página, depois do tokenizador. Ele é um módulo ES, então a tag precisa de type="module". O SDK fica em window["AvenPayThreeDS"].

<script type="module" src="https://api.avenpayments.com/v1/scripts"></script>
<script type="module" src="https://api.avenpayments.com/v1/scripts/3ds"></script>

Exemplo completo

Chame o init e o prepare assim que a página de pagamento abrir, com o que já souber da venda, e deixe do start em diante para o clique em pagar. Em alguns cartões, o prepare começa a coletar em segundo plano os dados do aparelho do comprador para a análise de fraude, e isso leva alguns segundos. Se o start vier logo depois do prepare, a venda segue sem esses dados e tem mais chance de ser recusada.

<button id="pay" disabled>Pagar</button>

<script type="module">
  const pk = "CHAVE_DE_TOKENIZACAO";
  const tokenizer = window["AvenPay"];
  const sdk = window["AvenPayThreeDS"];
  const payButton = document.querySelector("#pay");

  // a venda é o corpo do POST /v1/payment, sem o token
  const sale = {
    amount: 10000,
    currency: "BRL",
    payer: {
      name: "Maria Souza",
      email: "maria@email.com",
      phone: "+5511999998888",
    },
    card: {
      installments: 3,
      billingAddress: {
        street: "Rua A",
        number: "100",
        city: "São Paulo",
        state: "SP",
        zipCode: "01000000",
        country: "BR",
      },
    },
  };

  // ao abrir a página: o prepare começa a coletar os dados do aparelho, o que leva alguns segundos
  try {
    await tokenizer.init(pk);
    await sdk.init(pk);
    await sdk.prepare(sale);
    payButton.disabled = false; // o botão nasce desabilitado e só liga com o prepare pronto
  } catch (error) {
    if (error.name === "PaymentError") showError(error.code, error.description);
  }

  // no clique em pagar
  payButton.addEventListener("click", async (event) => {
    event.preventDefault(); // o botão dentro do <form> faria o submit
    payButton.disabled = true; // sem isto, dois cliques fazem dois start e dois pagamentos
    const card = {
      number: "5555444433331111",
      holder: "Maria Souza",
      expMonth: "08",
      expYear: "2027",
      cvv: "789",
    };
    let payment;

    try {
      const threeDS = await sdk.start(card); // 3DS e antifraude, ou undefined
      const token = await tokenizer.encrypt(card); // só o cartão

      payment = await fetch("/meu-backend/pagar", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ token, threeDS }),
      }).then((response) => response.json());

      await sdk.finish(payment); // a resposta inteira, sem tirar campos
    } catch (error) {
      if (error.name === "PaymentError") showError(error.code, error.description);
      if (!payment) payButton.disabled = false; // com a venda criada, religar deixaria pagar de novo
    }
  });
</script>

No seu backend, o threeDS vai em card.threeDS, ao lado do token, sem mudar nada:

// seu backend recebe { token, threeDS } da página
const { token, threeDS } = request.body;
const { installments, billingAddress } = sale.card;

const response = await fetch("https://api.avenpayments.com/v1/payment", {
  method: "POST",
  headers: { Authorization: "Bearer CHAVE_DE_API", "Content-Type": "application/json" },
  body: JSON.stringify({
    ...sale, // a mesma venda do prepare, com method, description, items e metadata
    ip: "203.0.113.10", // o IP do comprador, não o do seu servidor
    card: { token, installments, billingAddress, threeDS }, // o threeDS vai como veio
  }),
});

// devolva a resposta inteira para a página

A venda no prepare

O prepare recebe a venda no mesmo formato do POST /v1/payment. Monte o objeto uma vez e use nas duas pontas.

Chame o prepare de novo sempre que o valor, a moeda, as parcelas ou o endereço mudarem, e quando passar outro objeto de venda: o start usa a venda do último prepare.

No POST /v1/payment, mande em ip o IP do comprador, que o seu backend recebe na requisição da página, e não o IP do seu servidor. Alguns bancos usam esse IP na autenticação. Sem um IP válido, a venda segue sem ele.

O threeDS no pagamento

O threeDS que o start devolve traz o resultado da autenticação e os dados de antifraude da venda. Seu backend manda esse objeto em card.threeDS no POST /v1/payment. O token do cartão leva só o cartão.

Todos os campos são opcionais. O SDK preenche só o que o cartão da sua loja usa. Quando o start devolve undefined, o campo fica de fora. Se a coleta dos dados de antifraude falhar, a venda segue sem eles.

Mande o objeto como veio, sem montar nem mudar campos. A API recusa com 400 um campo que ela não conhece. Só o `device` é diferente: fora do formato, ele é descartado e a venda segue sem ele.

Depois da venda

Em alguns cartões, a autenticação acontece depois que o pagamento é criado. Em parte deles, o finish abre a tela do banco dentro da sua página, e o comprador não sai dela. Nos outros, o finish leva o comprador até o banco, e ele volta pelo returnUrl. Nos dois casos, o resultado chega pelo webhook.

O diagrama mostra o comprador saindo para o banco. Quando a tela do banco abre dentro da sua página, não há ida nem volta: o comprador autentica ali, e o resultado chega pelo webhook do mesmo jeito.

{
  // ...resto da venda
  "metadata": {
    "provider": "sualoja",
    "orderId": "123",
    "sellerTaxId": "12345678000190",
    "sellerEmail": "contato@sualoja.com",
    "returnUrl": "https://sualoja.com/pedido/123"
  }
}

O metadata exige provider, orderId, sellerTaxId e sellerEmail. Os campos estão em Criar Pagamento.

Quando o comprador sai da sua página para o banco, o endereço de volta é escolhido assim:

Quando a tela do banco abre dentro da sua página, o finish mostra uma janela por cima dela e fecha sozinho quando o banco devolve o comprador ao returnUrl. Para isso, o returnUrl precisa estar na mesma origem da página de pagamento (protocolo, domínio e porta) e poder abrir em iframe. Fora disso, a janela não fecha sozinha.

Poder abrir em iframe quer dizer que a página do returnUrl não responde com X-Frame-Options: DENY nem com frame-ancestors 'none'. X-Frame-Options: SAMEORIGIN serve.

Se o comprador fechar a janela, o finish falha com THREEDS_AUTHENTICATION_FAILED e detail igual a "cancelled". Se passar de 15 minutos, o detail é "timeout".

Em alguns cartões, a resposta do POST /v1/payment traz o threeDSToken, e o finish usa esse token para confirmar a autenticação na API, com a chave de tokenização. Você não chama essa confirmação nem lê o token: basta passar a resposta inteira ao finish. O token vale 15 minutos e não vem nos webhooks.

Como alguns cartões autenticam depois da venda com os dados do cartão, o SDK guarda o cartão só em memória até o fim do finish e nunca grava no navegador.

Se sua página usa CSP

Content-Security-Policy: script-src 'self' https://api.avenpayments.com; connect-src 'self' https://api.avenpayments.com; frame-src 'self'

Libere o que o SDK precisa carregar. Se um script for bloqueado, o prepare falha com THREEDS_SCRIPT_LOAD_FAILED, exceto o de análise de fraude. Se a busca da configuração for bloqueada, ele falha com THREEDS_CONFIG_FAILED.

Os endereços do banco e da análise de fraude mudam conforme o cartão. Se não puder liberar endereços que não conhece, deixe script-src, connect-src e frame-src sem restrição na página de pagamento.

Erros

Igual ao tokenizador: o SDK faz throw de um PaymentError com name, code, description e field. O THREEDS_AUTHENTICATION_FAILED traz também detail, com o motivo da falha.