Payment flow

Initialize the widget

Before integrating the Payment Widget, complete the First steps - Web.

Available Parameters

During the call of the initialize method, you have the preloadWidgets property where you can define all the params to determine the behavior of the payment widget, these are:

await DeunaSDK.initialize({
		...
    preloadWidgets: [
      {
        widget: 'payment',
        params: {
          // --- Display ---
          mode: 'modal',            // 'modal' (default) | 'target'
          target: '#container',     // Required when mode is 'target'. CSS selector of the container element.

          // --- Tokens if available (can be deferred to initPaymentWidget()) ---
          orderToken: 'xxxx-xxxx',  // Order token
          userToken: 'xxxx-xxxx',    // User token

          // --- Localization ---
          language: 'es',           // 'es' | 'pt' | 'en'

          // --- Pre-fill user data ---
          userInfo: {
            firstName: 'John',
            lastName: 'Doe',
            email: '[email protected]',
          },

          // --- Restrict/configure payment methods ---
          paymentMethods: [
            {
              paymentMethod: 'CREDIT_CARD',
              processors: ['STRIPE'],
              configuration: {
                express: false,
                flowType: { type: 'singleStep' }, // 'singleStep' | 'twoStep'
              },
            },
          ],

          // --- Widget behavior ---
          behavior: {
            hidePayButton: false,
            paymentMethods: {
              creditCard: {
                flow: 'purchase',           // 'purchase' | 'tokenize'
                splitPayments: {
                  maxCards: 2,
                },
              },
              paypal: {
                flow: 'purchase',           // 'purchase' | 'tokenize'
              },
              bankTransfer: {
                splitPayments: false,
              },
            },
          },

          // --- Theme & UX ---
          widgetExperience: {
            theme: {
              mainColor: '#000000',
              secondaryColor: '#ffffff',
              backgroundColor: '#f5f5f5',
              font: 'Roboto',
              imageUrl: 'https://example.com/logo.png',
              banner: 'https://example.com/banner.png',
              mainActionButtonText: 'Pay now',
            },
            userExperience: {
              showSavedCardsFlow: true,
              defaultCardFlow: false,
              disableInstallments: false,
            },
            flags: {
              allowSaveUserInfo: true,
            },
          },

          // --- Fraud prevention (optional) ---
          // Provide credentials only for the provider(s) configured on your account.
          fraudCredentials: {
            CYBERSOURCE: { orgId: 'xxx', merchantId: 'xxx' },
            SIGNIFYD: { account: 'xxx', email: 'xxx' },
            SIFT: { accountId: 'xxx', restApiKey: 'xxx' },
            STRIPE: { apiKey: 'xxx' },
            CLEARSALE: { clientId: 'xxx' },
            KONDUTO: { publicKey: 'xxx' },
            KOUNT: {
              dataCollectorUrl: 'https://xxx',
              merchantId: 'xxx',
              clientId: 'xxx',
              environment: 'production',
              version: '1.0',
              isSinglePageApp: true,
            },
            OPENPAY: { merchantId: 'xxx', publicApiKey: 'xxx', sandboxMode: false },
            KOIN: { orgId: 'xxx' },
            RISKIFIED: { storeDomain: 'xxx' },
          },

          // --- Callbacks ---
          callbacks: {
            onSuccess: (data) => {},
            // data: full order/payment response object

            onError: (error) => {},
            // error.type: string
            // error.metadata.code: string
            // error.metadata.message: string

            onClosed: (action) => {},
            // action: 'userAction' | 'systemAction'

            onEventDispatch: (event, payload) => {},
            // event: string — event name
            // payload: object — event data

            onCardBinDetected: (data) => {},
            // data.cardBin: string
            // data.cardBrand: string

            onInstallmentSelected: (data) => {},
            // data.cardBin: string
            // data.installmentPlanOptionId: string

            onPaymentProcessing: () => {},
            // Fires when payment processing starts

            onResize: (dimensions) => {},
            // dimensions.height: number
            // dimensions.width: number
          },
        },
      },
    ],
  });

Display the widget

To display the Payment Widget, call the function initPaymentWidget passing the following data:

await DeunaSDK.initPaymentWidget({
  orderToken: 'xxxx-xxxx', // if not passed into the previous step.
  userToken: 'xxxx-xxxx' // if not passed into the previous step.
});

Alternative Integration

There is another integration flow where you can pass al the params we describe previously into the preloadWidgets property in the Available Parameters section, but this time, those params will be passed during the initPaymentWidget method call.

await DeunaSDK.initPaymentWidget({
  ... // All the params describe into the Available parameters section.
});

From now on, all the explanation including one of the available params, could be passed in the preloadWidgets property of the initialize method or in the initPaymentWidget method, depending on the type of integration you've chosen.

📘
To guarantee the best performance available for the initial widget load, use the preload integration approach.

Payment Flow

When initializing the widget, you can change the payment flow by setting certain parameters in its configuration.

The flowType function sets the flow type for the widget based on the assigned value:

singleStep: Sets the default payment flow, meaning the entire transaction process is carried out in a single instance of the widget.
twoStep: Establishes a two-step payment flow. In a two-step flow, two instances of the widget are created to complete the transaction.
- On the first step, the payment information (disclaimer/cards/accounts) is embedded.
- On the second step, the payment event submit is handled, which initializes a dedicated instance for the payment.

📘
Currently, the payment flow configuration is only available for PayPal.

Global configuration

The payment flow can be configured globally by setting the configuration within the behavior parameter:

{
  orderToken: '<order_token>',
  ...,
  behavior: {
    paymentMethods: {
      flowType: {
        type: 'singleStep' | 'twoStep'
      }
    }
  }
};

Configuration by payment method

Set a separate configuration for each payment method.

{
  orderToken: '<order_token>',
  ...,
  paymentMethods: [
    {
      paymentMethod: 'wallet',
      processors: ['paypal_wallet'],
      configuration: {
        flowType: {
          type: 'singleStep' | 'twoStep'
        },
        ...
      },
      ...
    },
    ...
  ]
};

Express flow

The Express flow is available by default and occurs when only one payment method is integrated.

This flow will always attempt to process the transaction automatically. For this to happen, the following criteria must be met:

The customer has previously authorized a PayPal account.
No installments are required for the transaction.

📘
Currently only available for PayPal.

If installments are required for the transaction, they will be requested from the customer during the payment attempt. In this specific case, it is recommended to disable the Express Flow to show the customer their available accounts and thus pre-select the corresponding installments.

{
    orderToken: "<DEUNA order token>",
    paymentMethods: [
      {
        paymentMethod: "wallet",
        processors: ["paypal_wallet"],
        configuration: {
          express: true // AUTO PURCHASE (by default is true when not sent)
        }
      }
    ]
};

Configuration parameters

Parameter	Type	Default Value	Description
`express`	Boolean	`true`	When `true`, the widget automatically processes the payment if the customer already has a linked PayPal account. When `false`, even if the customer already has a linked PayPal account, the widget allows the user to: a/ Select installments (if applicable) b/ Select the account to use (if the customer has more than one linked PayPal account).