The Card vault integrates features like wallets and tokenization without processing the payment.
The Card Vault is a component of DEUNA Payment solutions and contains different types of widgets that allow you to:
- Store credit and debit cards securely in the Vault.
- Make Click To Pay payments with the Click To Pay widget.
You can also integrate the Click To Pay widget via iFrame.
Initialize the widget
Before integrating the Payment Widget, complete the First steps - Web.
1. Display the widget
To display the Vault Widget, call the function initElements passing the following data:
await DeunaSDK.initElements({
orderToken: "<DEUNA order token>", // opcional: Se puede extraer informacion del usuario de la orden
userToken: ..., // opcional
styleFile: ..., // opcional
language: ..., // opcional
hidePayButton: ..., // opcional
widgetExperience: { // OPCIONAL
userExperience: {
showSavedCardFlow: true, // Opcional: muestra toggle/checkbox para guardar tarjetas
defaultCardFlow: true // Opcional: muestra toggle/checkbox para guardar la tarjeta como predeterminada
}
},
userInfo: { // Opcional
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
},
types: ...// opcional, Si no se pasa este valor por defecto se mostrará el VAULT Widget.
callbacks: {
// opcionales
onClosed: (action) => console.log("cerrado desde Payment Widget"),
onSuccess: (data) => console.log("purchaseResponse: ", data),
onInstallmentSelected: (data) => console.log("installment selected"),
onCardBinDetected: (payload) => console.log("bin detected"),
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
},
},
});
Parameters
| Attrobites | Description |
|---|---|
orderToken | The orderToken is a unique token generated for the payment order. This token is generated through the DEUNA API, and you must implement the corresponding endpoint in your backend to obtain this information. You can extract the available user information in billing_address to use within the widget.An orderToken is only required when the vault widget will be configured to show installment options and/or the amount in the action button. |
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. In order for this userToken to be used and the saved cards to be shown to the customer, the email associated with that userToken must be the same one sent when creating the order in billing_address.email.In case you miss an orderToken if the emails do not match, the flow will proceed without displaying the cards for security reasons. |
userInfo | User information to be passed to the widget, possible information available to pass are: email, firstName, lastName.These fields are not required if you use a userToken. |
widgetExperience | Overrides merchant settings. Currently supported by the widget are the following:userExperience.showSavedCardFlow: Shows card saving toggle..userExperience.defaultCardFlow: Displays toggle to save card as default. |
language(Optional) | The payment widget language can be overridden by sending a parameter with a supported language. The main languages available are en (English), es (Spanish), and pt (Portuguese). If this parameter is not sent, the default language will be used. |
callbacks | Callbacks are return functions that are responsible for listening to and handling events from the payment widget. These events allow you to manage specific actions based on the status of the payment. The main callbacks include: onSuccess, onError, onClosed, onCanceled, onCardBinDetected, onInstallmentSelected |
styleFile(Optional) | UID provided by DEUNA. This applies if you want to configure a custom styles custom file(Change colors, texts, logo, etc).If a valid value is provided for tyleFile, the payment widget will use the UI settings provided by the theme configuration that matches the provided UUID. |
paymentMethods (Optional) | A list of allowed payment methods. This parameter determines what type of widget should be rendered. |
target(Optional) | By default, DEUNA widgets are displayed in a modal. If you prefer to display the widget inside a specific HTML element, use the parameter target o specify the ID or class name of the HTML element (using selectors) where you want to render the widget. Examples: #my-container, .my-container |
types (Optional) | An instance with a list of the widget types that the initElements function should render. Allowed values are: vault and click_to_pay . Example: [ { "name": "click_to_pay" } ] If this parameter is not passed, the DEUNA Vault Widget will be displayed by default to store credit and debit cards |
language(Optional) | This parameter allows you to specify the language in which the widget interface will be displayed. It must be provided as a valid language code (for example, "es" for Spanish, "en" for English, "pt" for Portuguese). Behavior: - If provided: The widget will use the language specified in this parameter, regardless of the merchant's settings. - If not provided: The widget will use the language configured by the merchant. |
behavior (Optional) | Use this parameter to configure the widget's behavior. |
hidePayButton (Optional) | If set to true, the widget's payment button will be hidden, allowing for completely manual payment management. This means the user will need to explicitly call the methods isValid() and submit() to process the transaction. |
behavior parameter (optional)
behavior parameter (optional)The initElements method accepts the behavior parameter.
This parameter allows you to customize the behavior of the payment widget, including enabling multi-card payments, among other configuration options.
These settings apply to all payment methods enabled in the widget.
Split Payment on Multiple Cards (Split Payments)
The function Split Payments allows customers to split payments for a purchase between multiple credit/debit cards.
- The option must be enabled in the trade settings.
- Currently, only splitting between two cards is supported at most.
DeunaSDK.initElements({
orderToken: "order_token",
...
behavior:{
paymentMethods:{
creditCard: {
splitPayments: {
// Maximum number of allowed saved cards
maxCards: 2
}
}
}
}
});
Click To Pay Widget
Using the parameter types in the function initElements, make a payment with Click To Pay.
The following code snippet shows how to display the Click To Pay widget.
await DeunaSDK.initElements({
orderToken: "<DEUNA order token>", // Optional, you can extract user info from order
userInfo: { // Opcional
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
},
types: [{ name: "click_to_pay" }],
callbacks: {
// opcionales
onClosed: (action) => console.log("cerrado desde Click to Pay"),
onSuccess: (data) => console.log("purchaseResponse: ", data),
onInstallmentSelected: (data) => console.log("installment selected"),
onCardBinDetected: (payload) => console.log("bin detected"),
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
},
},
});
2. Listen to card vault events
When a card save is successful or fails, you can do this by listening to Vault Widget events using callbacks.
The callbacks passed to the function initElements allows you to listen for widget events. Define the corresponding callbacks to update your app's interface.
Callbacks
| Callback | Trigger |
|---|---|
| onSuccess | Executed when a card is saved successfully. This callback contains a JSON parameter with the order information. |
| onError | Executed when an error occurs while saving the card. This callback contains a JSON parameter which identifies the type of error produced. |
| onClosed (Optional) | Executed when the payment widget is closed. This callback contains a string parameter whose values can be one of the following: - userAction: When the widget was manually closed by the user (by pressing the close X button) without the operation being completed. - systemAction: When the widget closes due to the execution of the close function. |
| onCardBinDetected (Optional) | Executed when the payment widget detects the BIN of an entered credit or debit card or when the user deletes the entered card number. This callback contains a JSON parameter with the bin information and the brand of the entered card. The JSON parameter will be null when the user removes the text entered in the card number field. |
| onInstallmentSelected (Optional) | If the order can be deferred, this callback will be executed when the user selects the months to defer. This callback contains a JSON parameter with the information of the months to defer selected by the user. NOTE: The JSON parameter will be null when the user selects current payment (No installments). |
| onEventDispatch (Optional) | It is executed on all events that the widget can produce. This callback contains a string parameter and the data (JSON) associated with that event. |
Example
await DeunaSDK.initElements({
orderToken: "<DEUNA order token>",
userToken: "...",
callbacks: {
onSuccess: ...,
onCardBinDetected: async (cardBinMetadata) => {
if (cardBinMetadata) {
// ...
}
},
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
}
},
});
3. Close the vault
By default, the Card vault only closes when the user presses the widget's close button.
To close the modal when a payment is successful or when an error occurs, you must call the close function.
await DeunaSDK.close();
The following sample code shows how to close the vault when a card save is successful..
await DeunaSDK.initElements({
orderToken: "<DEUNA order token>", // Mandstory orfer token
callbacks: {
// opcionales
onSuccess: async (data) => {
await DeunaSDK.close(); // Close the payment widget
console.log("purchaseResponse: ", data);
},
},
});
4. Customize the vault`s appeareance
Use the function setCustomStyle to customize the appearance of the Widget.
await DeunaSDK.setCustomStyle({...});
For more information refer to CustomStyle.
Example
await DeunaSDK.initElements({
orderToken: "<DEUNA order token>", // Mandatry: Order token to initialize widget
callbacks: {
onSuccess: ...,
onCardBinDetected: async (cardBinMetadata) => {
await DeunaSDK.setCustomStyle({
theme: {
colors: {
primaryTextColor: "#023047",
backgroundSecondary: "#8ECAE6",
backgroundPrimary: "#F2F2F2",
buttonPrimaryFill: "#FFB703",
buttonPrimaryHover: "#FFB703",
buttonPrimaryText: "#000000",
buttonPrimaryActive: "#FFB703",
},
},
HeaderPattern: {
overrides: {
Logo: {
props: {
url: "https://images-staging.getduna.com/ema/fc78ef09-ffc7-4d04-aec3-4c2a2023b336/test2.png",
},
},
},
},
});
},
},
});
Customize the pay button
Use your own button inside the Widget.
The DEUNA SDK allows you to hide the native “Save” button included in the Payment Vault and replace it with a custom button integrated into the merchant interface.
This feature is ideal for:
- Maintain a user experience consistent with the store's design.
- Integrate card saving into your own workflows or custom steps.
- Have greater control over the exact moment when the payment method save action is triggered.
1. Hide the native button
When initializing the widget, activate the parameter hidePayButton:
- If
hidePayButtonis false or undefined, the widget displays its standard button. - If
hidePayButtonis true, the widget hides the button.
await DeunaSDK.initElements({
orderToken: "order_ABC123",
hidePayButton: true, // ← Hides native button (default: false),
...
});
This setting cannot be changed dynamically after the widget is initialized.
2. Customized button
Approve data and execute payments.
When you use DeunaSDK.initElements(...), the user can employ the following methods to validate and execute the card saving..
| Method | Description | Response |
|---|---|---|
DeunaSDK.isValid() | Validates whether the card information entered is correct and can be saved. | true if the information is valid, false otherwise. |
DeunaSDK.submit() | Executes the card saving process, equivalent to pressing the save button. | { status: "success", message: "card saves succesfully" } o { status: "error", message: "The submit flow is not available" } |
- Use
isValid()before callingsubmit()to avoid errors in the saving process. isValid()andsubmit()can be used at any time, without depending onmanualSubmit.- In
hidePayButtonis true, the save card button will not be displayed and the save will need to be managed withsubmit(). - If the save stream is not yet available,
submit()will return an error with the message "The submit flow is not available". - The responses in
isValidandsubmitreturn a promise. isValid()allows you to keep a payment button in the disabled state until all fields are filled out and valid. This enables its own control logic to decide when to activate the payment button, which is what should subsequently be calledsubmit()