General widget settings
Configure localization, URLs, authentication, and shared behavior across DEUNA checkout widgets.
En esta página
The following settings allow you to customize the checkout behavior and appearance to suit each merchant's specific needs.
Language#
The checkout interface language is automatically configured based on the country in which your business operates.
This setting aims to ensure a localized experience for shoppers, reducing friction and improving conversion rates.
- The language is defined through the tokenization of orders.
- Language can be dynamically specified for each order.
Base URL#
If you'd like to customize a specific base URL for your payment links, then you can request it from our support team. This customization allows you to tailor the experience to your brand identity.
Example: https://payhere.yourbrand.deuna.com
Enable user authentication#
DEUNA lets you configure whether your shoppers complete checkout as guests or as authenticated users, with access to their saved cards and previous purchase data. This behavior is controlled by two variables:
| Variable | Type | Description |
|---|---|---|
user_authentication_flow | boolean | Enables the authenticated user flow (login, OTP, saved cards). |
init_with_guest_user | boolean | Enables the guest user flow (no login). |
Both variables are configured inside widgets_general_config.user_experience when creating or updating your merchant configuration:
{
"widgets_general_config": {
"user_experience": {
"user_authentication_flow": true,
"init_with_guest_user": false
}
}
}How is it decided whether a user sees the authenticated flow?
If you set user_authentication_flow: true, DEUNA determines which user to show (and therefore, which saved cards) following a priority order. A value defined at a higher level always overrides the levels below it:
| Priority | Source | Description |
|---|---|---|
| 1(highest) | Query param userToken | If the merchant explicitly sends a userToken when initializing the widget, that user is used regardless of any other configuration. |
| 2 | Merchant configuration | If no userToken is sent, the configuration defined in widgets_general_config.user_experience is used. |
| 3 (lowest) | Order / billing email | If there's no userToken and no applicable configuration, the decision is based solely on the email received in the order or billing data. |
Example — initializing with an explicit userToken:
deunaSDK.initElements({
orderToken: "YOUR_ORDER_TOKEN",
userToken: "YOUR_USER_TOKEN", // overrides merchant config and order email
// ...other initialization parameters
});Overriding at initialization: onlyCardEnrollment
Parameters sent inside behavior when initializing the WebSDK let you override certain flows defined in your merchant configuration, without changing that configuration itself.
onlyCardEnrollment hides an authenticated user's saved cards, allowing only the enrollment of a new card. This is recommended when the merchant manages the display of the user's saved cards from their own UI, and only needs DEUNA to handle the card-enrollment form.
onlyCardEnrollment overrides the outcome of the priority table above: even if a userToken or an active user_authentication_flow would normally show saved cards, this flag forces them to stay hidden for that session.
External authorizer (userToken) | OTP (user_authentication_flow) | onlyCardEnrollment | Saved cards visible? |
|---|---|---|---|
| ✅ | ❌ | ❌ | ✅ |
| ✅ | ❌ | ✅ | ❌ |
| ❌ | ✅ | ❌ | ✅ |
| ❌ | ✅ | ✅ | ❌ |
Example — Vault Widget WebSDK configuration:
await DeunaSDK.initElements({
orderToken: "<ORDER_TOKEN>",
userToken: "<AUTHENTICATION_TOKEN>",
userInfo: { /* ... */ },
behavior: {
onlyCardEnrollment: true,
// ...other behavior overrides
},
callbacks: { /* ... */ },
},
});OTP channels#
When a shopper logs in at checkout, DEUNA sends a one-time password (OTP) by email or SMS. Both channels are enabled by default. Use the otp_channels setting to disable SMS for your merchant account; email always remains available.
Contact your DEUNA account manager to apply this setting.
Choose a configuration mode
| Mode | sms_enabled | Available channels | Returning shopper behavior |
|---|---|---|---|
| Default | true or omitted | Email and SMS | DEUNA uses the channel from the shopper's last successful login. |
| Email only | false | DEUNA ignores an SMS preference and sends the OTP by email. |
The sms_enabled variable is configured inside widgets_general_config.otp_channels. Select an example to disable SMS or restore the default behavior:
curl --request PATCH \
--url https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations \
--header 'Authorization: Bearer YOUR_MERCHANT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"widgets_general_config": {
"otp_channels": {
"sms_enabled": false
}
}
}'const response = await fetch("https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations", {
method: "PATCH",
headers: {
"Authorization": "Bearer YOUR_MERCHANT_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"widgets_general_config": {
"otp_channels": {
"sms_enabled": false
}
}
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"PATCH",
"https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations",
headers={
"Authorization": "Bearer YOUR_MERCHANT_TOKEN",
"Content-Type": "application/json"
},
json={
"widgets_general_config": {
"otp_channels": {
"sms_enabled": False
}
}
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations",
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_MERCHANT_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"widgets_general_config" => [
"otp_channels" => [
"sms_enabled" => false
]
]
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations"))
.header("Authorization", "Bearer YOUR_MERCHANT_TOKEN")
.header("Content-Type", "application/json")
.method("PATCH", HttpRequest.BodyPublishers.ofString("{\n \"widgets_general_config\": {\n \"otp_channels\": {\n \"sms_enabled\": false\n }\n }\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("PATCH", "https://api.sandbox.deuna.io/api/v1/merchants/{merchant_id}/checkout/configurations", strings.NewReader("{\n \"widgets_general_config\": {\n \"otp_channels\": {\n \"sms_enabled\": false\n }\n }\n }"))
if err != nil { panic(err) }
request.Header.Set("Authorization", "Bearer YOUR_MERCHANT_TOKEN")
request.Header.Set("Content-Type", "application/json")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}{
"widgets_general_config": {
"otp_channels": {
"sms_enabled": false
}
}
}For production, replace https://api.sandbox.deuna.io with https://api.deuna.io. Test the change in sandbox before applying it in production.
Understand shopper behavior
DEUNA remembers the channel each shopper used for their last successful login and uses it for the next OTP. This gives returning shoppers the code through the channel they previously selected, unless your merchant configuration disables that channel.
- Default configuration: DEUNA sends the OTP through the shopper's preferred channel.
- SMS disabled: DEUNA sends the OTP by email, even when the shopper's preferred channel is SMS.
- The restriction applies to authenticated OTP flows in Payment Widget, Payment Link, and Payment Vault. Guest flows aren't affected.
- When SMS is disabled, the SMS option doesn't appear in the OTP view.
- Resend code uses the channel currently in use.
Frequently asked questions
Does this apply to all my shoppers?
Yes. The setting applies to the merchant account, not to individual shoppers.
Do I need to change my integration?
No. The widget reads the setting during initialization. You don't need to change the SDK configuration or order-creation request.
What happens if I don't configure otp_channels?
Both email and SMS remain enabled, and the shopper flow doesn't change.
Enable card saving#
Besides deciding whether a user checks out as a guest or as an authenticated user, you can configure how card-saving behaves during payment.
| Variable | Type | Description |
|---|---|---|
show_saved_cards_flow | boolean | Displays a checkbox that lets the shopper decide whether to save their card during payment. When disabled (false, the default), the card is saved automatically without asking, which improves conversion on future purchases. |
default_card_flow | boolean | Displays an additional checkbox letting the user decide whether that card should be marked as the default for future purchases. Disabled by default. |
Both variables are also configured inside widgets_general_config.user_experience:
{
"widgets_general_config": {
"user_experience": {
"show_saved_cards_flow": true,
"default_card_flow": true
}
}
}Enable card saving#
It is possible to display a checkbox that allows the shopper to decide whether to save their card at checkout. This option is useful in guest flows.
The default behavior is not to display the checkbox and automatically save the card to improve conversion.
Allow card deletion#
Controls whether shoppers can delete saved cards in the Vault Widget. Recommended for subscription and recurring billing models to prevent accidental payment method removal and involuntary churn.
| Variable | Type | Default | Description |
|---|---|---|---|
allow_card_deletion | boolean | true | Determines if shoppers can delete cards. When false, all deletion actions are hidden. |
Configure inside widgets_general_config.user_experience:
{
"widgets_general_config": {
"user_experience": {
"allow_card_deletion": false
}
}
}UI behavior
| State | Active cards | Expired cards | Default card | Single card view |
|---|---|---|---|---|
false (Disabled) | Hides "Delete" from the menu (only "Set as default" is shown). | Hides the trash icon. | Hides the actions menu entirely to avoid empty popovers. | Hides the delete button. |
true or omitted (Default) | Standard deletion available in menu. | Trash icon visible and active. | Standard deletion available in menu. | Delete button visible and active. |
Visual styles#
Customize your widget using CustomStyle.
Adapt your customers' visual experience to your brand guidelines.