Documentación

Embedded Vault

Suggest Edits

Vault via URL / Iframe

You can render the Vault Widget inside an Iframe or in a full tab, in case you can't use the SDKs.

To integrate Payment Vault via URL or iFrame, follow these steps:

1. Initialize an Iframe in your application

Use the DEUNA URL to initialize the Iframe within your website.

URL for integration

https://elements.sandbox.deuna.io/vault?publicApiKey=${apiKey}&firstName=${encodeURIComponent(firstname)}&lastName=${encodeURIComponent(lastname)}&email=${encodeURIComponent(email)}

https://elements.deuna.com/vault?publicApiKey=${apiKey}&firstName=${encodeURIComponent(firstname)}&lastName=${encodeURIComponent(lastname)}&email=${encodeURIComponent(email)}

📘

Include query parameters when initializing the Iframe.

Allowed Attributes in Query Params

AttributeDescription
publicApiKeyThe public key of your account with DEUNA.
firstNameThe name of the user who is being registered or authenticated.
lastNameThe user's last name.
emailThe user's email address.
cssFile (opcional)UUID provided by DEUNA. This applies if you want to configure a custom css file.
orderToken(optional)UUID obtained when creating an order with DEUNA. This query param is required to display installments in the vault.
allowSaveUserInfo(optional)(Boolean) If you want to save the user's card for future use
showSaveCardFlow(optional)(Boolean) If you want to show a new user the toggle to select whether or not they want to save the card for future use. Guest users do not have the option to save the card since it is for single use.
userToken (optional)The bearer token of the DEUNA user. When this is sent, all actions within the widget will be done on this DEUNA user. Additionally, when this userToken is sent, it is not necessary to send either the bearer token or the bearer token. email, firstName, lastName. Only the userTokenand the publicApiKey.

📘

Query parameters must be properly encoded if they contain special characters. This is essential to avoid potential problems in requests.

URL in a web with HTML, CSS, and JavaScript

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vault Widget Integration</title>
    <style>
      /* basic stles for iframe */
      #vault-widget-iframe {
          width: 100%;
          height: 500px; /* Adjust the height */
          border: none;
      }
    </style>
  </head>
  <body>
    <iframe
      id="vault-widget-iframe"
      src="https://elements.sandbox.deuna.io/vault?publicApiKey=${apiKey}&firstName=${encodeURIComponent(firstname)}&lastName=${encodeURIComponent(lastname)}&email=${encodeURIComponent(email)}"
      allow="payment"
    >
    </iframe>

    <script>
      // Listen to postMessage events to receive the card_id or card token)
      window.addEventListener('message', function(event) {
          if (event.origin !== "https://elements.sandbox.deuna.io") {
              return;
          }
          let firstParsedData;
          if (typeof event.data === 'string') {
              firstParsedData = JSON.parse(event.data);
          } else {
              firstParsedData = event.data;
          }

          const parsedData = JSON.parse(firstParsedData);
          console.log('postMessage:', parsedData);

          if (
            parsedData &&
            parsedData.type === "vaultSaveSuccess"
        ) {
          // obtener el card_id (a.k.a card token)
          const cardId = parsedData.data.metadata.createdCard.id;

          // crear pago con el card_id
        }
      });
    </script>
  </body>
</html>

📘

The DEUNA component is responsible for user management and card vaulting.

2. Handle events with postMessage

After integrating the URL, DEUNA sends an event via postMessage with a valid card_id.

📘

Send the card_id in all V2 Purchase requests from your backend to complete payments.

Event handling example

window.addEventListener("message", (event) => {
  if (event.origin !== "URL_DE_CONFIANZA") { // Reemplaza con tu URL de confianza
    return;
  }

  switch (event.data.type) {
    case 'checkoutStarted':
      // Vault está listo
      break;

    case 'vaultSaveSuccess':
      // Tarjeta guardada con éxito, obtén el card_id
      const cardId = event.data.metadata.createdCard.id;
      // Usa card_id para procesar el pago
      
      // stored card sera true si fue una tarjeta seleccionada de las
      // tarjetas guardas, de lo contrario sera false si es nueva
      const storedCard = event.data.metadata.createdCard.storedCard
      break;

    case 'vaultSaveError':
    case 'vaultFailed':
      // Manejo de errores
      const errorCode = event.data.metadata.errorCode;
      const errorMessage = event.data.metadata.errorMessage;
      break;

    case 'vaultProcessing':
      // Pago en proceso
      break;
    case 'onBinDetected':
    	// Cuando el usuario ingresa los primeros 6 dígitos de la tarjeta
    case 'onInstallmentSelected':
    	const planOptionId = event.data.metadata.installment.plan_option_id;

    // Añade más casos según sea necesario
  }
});

📘

For more information about events, refer to Handling events with postMessage.

3. Apply changes to the order after loading

Send a message to the Iframe using postMessage with type refetchOrder and apply changes to an order.

Apply changes to an order works to apply a promotion or discount that affects the order in the Widget.

📘

postMessage message allows the Widget to update an order and display the fees or discount.

Change in order example

if ( parsedData && parsedData.type === elementsLinkEvents.onBinDetected) {
          const cardBrand = parsedData.data?.metadata?.cardBrand
           
          // 1.Verificar si la tarjeta es mastercard  
          if (cardBrand === 'mastercard') {
            
            //Si es así aplicar un descuento del 20% (función del comercio)
            const cartUpdated  = applyDiscount(cart, 20);
            dispatcher(setDiscountedCart(cartUpdated));
            
            //Modifica la orden apuntando a un endpoint de Deuna
            await updateOrder({...});

            //2. Notificale al widget que hay que actualizar la orden e installments
            iframeRef.current?.contentWindow?.postMessage(
              JSON.stringify({
                type: 'refetchOrder',
                data: null // debe siempre ir en null
              }),
              '*'
            );
             // 3. Incluso podrías enviar un postMessage adicional para mostrar
             // un tag promocional, 
            iframeRef.current?.contentWindow?.postMessage(
            JSON.stringify({
              type: elementsLinkEvents.setCustomCSS,
              data: getCustomCSS(cardBrand)
            }),
            '*'
          );
          }
        }


https://elements.sandbox.deuna.io/vault?publicApiKey=${apiKey}&firstName=${encodeURIComponent(firstname)}&lastName=${encodeURIComponent(lastname)}&email=${encodeURIComponent(email)}

https://elements.deuna.com/vault?publicApiKey=${apiKey}&firstName=${encodeURIComponent(firstname)}&lastName=${encodeURIComponent(lastname)}&email=${encodeURIComponent(email)}

Updated 2 days ago