SDK Web

Utilizza il DEUNA Web SDK per visualizzare il Payment Widget, il Payment Vault, Click to Pay, i portafogli nativi, i voucher e le azioni successive in una finestra modale o all'interno di una pagina. Il browser SDK viene distribuito come script classico tramite il CDN di DEUNA.

Caricare l’SDK#

. Assicurati di utilizzare la versione del SDK per la tua integrazione. Testa una versione più recente in ambiente sandbox prima di modificare questo URL in produzione.

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

Lo script espone il singleton window.DeunaSDK. Inoltre, supporta DeunaSDK.newInstance() quando una pagina richiede istanze SDK isolate.

Inizializzazione#

Inizializza una sola volta con la chiave API pubblica per l'ambiente selezionato. Imposta esplicitamente l'ambiente; il SDK utilizza automaticamente la versione di produzione quando env viene omesso.

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

Widget di pagamento aperto#

Crea l’ordine nel backend, restituisci il token al browser e apri 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);
    },
  },
});

Utilizza il callback per aggiornare l'interfaccia. Conferma e completa l'ordine finale tramite un webhook verificato, anziché fidarti esclusivamente dello stato del browser.

Scegli la modalità di presentazione.#

Modal è l'opzione predefinita. L'SDK gestisce l'overlay. close() annulla.

Per un widget integrato, utilizzare entrambi. mode: 'target' e un selettore CSS. Aggiorna l'altezza del contenitore da onResize in modo da evitare troncamenti.

<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),
  },
});

Controlla la presentazione dal tuo sito#

Nascondi il pulsante di pagamento del widget quando il tuo sito gestisce l'ultima azione. Verifica prima della presentazione e disabilita il tuo pulsante mentre la richiesta è in attesa.

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);
});

Il widget attivo espone anche getWidgetState(), refetchOrder()e setCustomStyles(...). Chiama setCustomStyles solo dai callback del BIN della carta o dei piani di finanziamento documentati per il flusso di pagamento.

Esperienze disponibili#

Archiviazione dei pagamenti e Click to Pay

initElements apre automaticamente Payment Vault. Fornisci types per selezionare un'esperienza Elements diversa.

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'} per Click to Pay. Se hai già un utente DEUNA autenticato, passa userToken invece di userInfo.

Apple Pay e Google Pay

Quando rendi un pulsante del portafoglio di proprietà del commerciante, verifica la disponibilità prima di visualizzarlo. Esegui questo passaggio prima del clic in modo che Apple Pay possa aprirsi direttamente dall'azione dell'utente.

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 per il flusso equivalente di Google Pay. Consulta le guide Apple Pay e Google Pay per i requisiti per commercianti e browser.

Continuare un'azione in sospeso

Apri Next Action solo quando la risposta dell'ordine indica che è ancora necessario un'azione da parte del cliente, come una sfida 3DS o un reindirizzamento.

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

Non creare un secondo ordine per questo passaggio. Riutilizza il token per l'ordine che richiede la prossima azione.

Aprire un buono

Utilizza l'esperienza del voucher per i metodi di pagamento in contanti o voucher supportati.

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

Precarica un widget#

Il widget di pagamento e Elements possono essere creati in background durante l'inizializzazione e visualizzati in seguito. La precaricazione riduce la percezione del tempo di apertura, ma utilizza le risorse di rete e del browser in anticipo.

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});

Precarica solo l'esperienza che il cliente è più probabile che apra. La successiva initPaymentWidget o initElements chiamata fornisce il token dell'ordine o dell'utente e visualizza il widget preparato.

Dati fraud-device#

Il widget di pagamento avvia la raccolta dei dati del dispositivo DEUNA quando viene aperto. Se il tuo flusso richiede l'identificatore prima che il widget venga aperto, chiama generateFraudId(...) e invia il valore restituito solo tramite l'ordine o il flusso di rischio documentato.

const fraudId = await DeunaSDK.generateFraudId();

Il comportamento specifico per ogni fornitore e le versioni sono documentati in Integrare l'impronta digitale del dispositivo.

Riferimento a callback e ciclo di vita#

Guide e codice correlati#