SDK Web

Utilize o SDK da DEUNA para renderizar o Widget de Pagamento, o Vault de Pagamento, Click to Pay, carteiras nativas, cupons e ações subsequentes em um modal ou dentro de uma página. O SDK do navegador é distribuído como um script clássico através do CDN da DEUNA.

Carregar o SDK#

Fixe a versão do SDK que você está utilizando na sua integração. Teste uma versão mais recente no ambiente de sandbox antes de alterar esta URL no ambiente de produção.

<script
  crossorigin
  src="https://cdn.deuna.io/web-sdk/v1.7/index.js">
</script>

O script expõe o singleton window.DeunaSDK. Além disso, ele suporta DeunaSDK.newInstance() quando uma página precisa de instâncias do SDK isoladas.

Inicialização#

Inicialize uma vez com a chave da API pública para o ambiente selecionado. Defina o ambiente explicitamente; o SDK usa o ambiente de produção quando env é omitido.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
});

Abrir widget de pagamento#

Crie o pedido no seu backend, retorne o token ao navegador e abra o Payment Widget:

await DeunaSDK.initPaymentWidget({
  orderToken,
  language: 'en',
  callbacks: {
    onSuccess: async (order) => {
      await DeunaSDK.close();
      showConfirmation(order);
    },
    onError: (error) => showRetry(error),
    onClosed: (action, metadata) => {
      console.log('Widget closed', action, metadata);
    },
    onEventDispatch: (event, payload) => {
      analytics.track(event, payload);
    },
  },
});

Utilize o callback para atualizar a interface. Confirme e finalize o pedido final a partir de um webhook verificado, em vez de confiar apenas no estado do navegador.

Escolha um modo de apresentação#

O modal é o padrão. O SDK controla a sobreposição e close() a desativa.

Para um widget incorporado, utilize tanto mode: 'target' e um seletor CSS. Atualize a altura do contêiner a partir de onResize para evitar que o conteúdo seja cortado.

<div id="payment-widget"></div>

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#payment-widget',
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#payment-widget').style.height = `${height}px`;
    },
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
  },
});

Controle a submissão a partir da sua página#

Esconda o botão de pagamento do widget quando a sua página é responsável pela etapa final. Valide antes de enviar e desative o seu botão enquanto a promessa estiver pendente.

await DeunaSDK.initPaymentWidget({
  orderToken,
  hidePayButton: true,
  callbacks,
});

payButton.addEventListener('click', async () => {
  if (!(await DeunaSDK.isValid())) return;

  payButton.disabled = true;
  const result = await DeunaSDK.submit();
  payButton.disabled = false;

  if (result.status === 'error') showRetry(result);
});

O widget ativo também expõe getWidgetState(), refetchOrder()e setCustomStyles(...). Chame setCustomStyles apenas a partir dos callbacks do BIN do cartão ou dos pagamentos parcelados, conforme documentado para o fluxo de pagamento.

Experiências disponíveis#

Armazenamento de Pagamentos e Pagamento com Clique

initElements Abre o Payment Vault por padrão. Forneça types para selecionar uma experiência diferente do Elements.

await DeunaSDK.initElements({
  orderToken,
  userInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    email: 'ada@example.com',
  },
  types: [{name: 'vault'}],
  callbacks: {
    onSuccess: (credential) => useSavedCredential(credential),
    onError: (error) => showRetry(error),
    onClosed: (action) => console.log(action),
  },
});

Uso {name: 'click_to_pay'} para o Click to Pay. Se você já possui um usuário DEUNA autenticado, passe userToken em vez de userInfo.

Apple Pay e Google Pay

Quando você renderiza um botão de carteira de propriedade do comerciante, verifique a disponibilidade antes de exibi-lo. Execute esta etapa antes do clique para que o Apple Pay possa ser aberto diretamente a partir do gesto do usuário.

const userInfo = {email: 'ada@example.com'};
const availableWallets = await DeunaSDK.getWalletsAvailable({
  orderToken,
  userInfo,
});

applePayButton.hidden = !availableWallets.includes('APPLE_PAY');

applePayButton.addEventListener('click', () => {
  DeunaSDK.initElements({
    orderToken,
    userInfo,
    types: [{name: 'APPLE_PAY'}],
    callbacks: {
      onSuccess: (credential) => useSavedCredential(credential),
      onError: (error) => showRetry(error),
      onClosed: () => showPaymentMethods(),
    },
  });
});

Uso GOOGLE_PAY para o fluxo equivalente do Google Pay. Consulte as guias do Apple Pay e guia do Google Pay para os requisitos do comerciante e do navegador.

Continue uma ação pendente

Abra a Próxima Ação somente quando a resposta do pedido indicar que a ação do cliente ainda é necessária, como um desafio 3DS ou redirecionamento.

await DeunaSDK.initNextAction({
  orderToken,
  callbacks: {
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Não crie um segundo pedido para esta etapa. Utilize o token para o pedido que requer a próxima ação.

Abra um cupom

Utilize a experiência do voucher para métodos de pagamento suportados em dinheiro ou voucher.

await DeunaSDK.initVoucherWidget({
  orderToken,
  callbacks: {
    onSuccess: (order) => showVoucherInstructions(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Pré-carregue um widget#

O widget de pagamento e o Elements podem ser criados offline durante a inicialização e exibidos posteriormente. O pré-carregamento reduz o tempo percebido de abertura, mas utiliza os recursos de rede e do navegador mais cedo.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
  preloadWidgets: [
    {
      widget: 'payment',
      params: {language: 'en'},
    },
  ],
});

// After the backend returns the order token:
await DeunaSDK.initPaymentWidget({orderToken});

Pré-carregue apenas a experiência que o cliente provavelmente abrirá. A chamada posterior initPaymentWidget ou initElements fornece o token do pedido ou do usuário e revela o widget preparado.

Dados de dispositivos para prevenção de fraudes#

O widget de pagamento inicia a coleta de dados do dispositivo DEUNA quando é aberto. Se o seu fluxo precisar do identificador antes de um widget ser aberto, chame generateFraudId(...) e envie o valor retornado apenas através do pedido ou do fluxo de risco documentado.

const fraudId = await DeunaSDK.generateFraudId();

O comportamento específico do provedor e a versão são documentados em Integrar impressão digital do dispositivo.

Referência do ciclo de vida e callbacks#

Guias e código relacionados#