Payment Widget for Web

Payment Widget displays the payment methods eligible for an existing order and processes the selected method through DEUNA. It supports cards and configured alternative payment methods without exposing sensitive credentials to merchant JavaScript.

Before you beginAsk Athia about this#

Complete Get started with the Web SDK, create the order on your backend, and return only its order_token to the browser.

Open Payment WidgetAsk Athia about this#

await DeunaSDK.initPaymentWidget({
  orderToken,
  language: 'en',
  callbacks: {
    onSuccess: async () => {
      await DeunaSDK.close();
      await verifyOrderOnBackend();
    },
    onError: ({type, metadata}) => {
      showRecovery({type, code: metadata.code});
    },
    onClosed: (action, metadata) => {
      restorePaymentMethods(action, metadata);
    },
    onCardBinDetected: ({cardBin, cardBrand}) => {
      updateCardOffers(cardBin, cardBrand);
    },
    onInstallmentSelected: ({cardBin, installmentPlanOptionId}) => {
      rememberPlan(cardBin, installmentPlanOptionId);
    },
    onPaymentProcessing: () => disableDuplicateActions(),
    onEventDispatch: (event, payload) => trackSafeEvent(event, payload),
  },
});

Integration sequenceAsk Athia about this#

ParametersAsk Athia about this#

Modal or embeddedAsk Athia about this#

Modal is the default. For embedded mode:

<div id="deuna-payment" aria-label="Payment details"></div>

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#deuna-payment',
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#deuna-payment').style.height = `${Math.ceil(height)}px`;
    },
    onSuccess: verifyOrderOnBackend,
    onError: showRecovery,
  },
});

The selector must match one stable element. Do not render it inside an element that is display: none during initialization or clips overflow.

Filter payment methodsAsk Athia about this#

Omit paymentMethods to let the order and merchant configuration determine eligibility. Supply one method to open its form directly, or multiple methods to restrict the choice.

await DeunaSDK.initPaymentWidget({
  orderToken,
  paymentMethods: [
    {paymentMethod: 'credit_card'},
    {paymentMethod: 'wallet', processors: ['click_to_pay']},
  ],
  callbacks,
});

Routing can choose among configured card processors, so a credit-card entry does not normally need a processors list.

Own the submit buttonAsk Athia about this#

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

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

  payButton.disabled = true;
  const result = await DeunaSDK.submit();
  if (result.status === 'error') showRecovery(result);
  payButton.disabled = false;
});

The active instance also exposes getWidgetState(), getSelectedPaymentMethod(), refetchOrder(), setOrderData(...), setCustomStyles(...), and close(). Use only methods relevant to the active experience and serialize updates so an old order token cannot overwrite a new checkout.

Split cards and installmentsAsk Athia about this#

Use the documented nested behavior for a configured two-card flow:

behavior: {
  paymentMethods: {
    creditCard: {
      splitPayments: {maxCards: 2},
    },
  },
}

See Split card payments for reconciliation and testing. Use onInstallmentSelected for the exact installmentPlanOptionId; never infer it from visible copy.

Error and close handlingAsk Athia about this#

Do not show raw provider messages. Map known types and codes to localized customer guidance, record safe diagnostics, and fall back to a generic retry message.

Related referencesAsk Athia about this#