The Next Action widget is a 3DS and Payment methods post-payment flow facilitator.
The Next Action widget acts as an intelligent orchestrator that:
- Takes control of the flow after a payment has been successfully initiated via the Purchase API DEUNA.
- Automatically handles the required next actions of a payment flow.
Use cases
| Use case | Scenario | Next Action function |
|---|---|---|
| 3DS authentication | A customer attempts to pay with a credit or debit card that requires 3DS authentication. After the DEUNA Purchase API call, it is determined that a 3DS challenge is required. | Next Action is responsible for: - Redirection to the issuing bank or the acquirer's 3DS service. - Management of the iFrame or authentication modal. - Listen for the result to resume the flow. The widget displays the 3DS flow and notifies your application of the authentication result via callbacks. onSuccess either onError. |
| Alternative payment methods | A customer chooses an APM that, by its nature, requires a redirect to an external page to complete the process. This may include entering credentials or approval in a digital wallet. DEUNA's Purchase API indicates the need for this redirect. | When the DEUNA Purchase API indicates the need for a redirect to an APM, the Next Action Widget takes the provided redirect URL and handles the entire process: 1. Redirects the user to the APM provider's payment page. 2. Wait for user interaction on the external page. 3. Monitor the outcome of the interaction and, once completed, return the user to your site. 4. Notify your application of successful or failed payment completion via callbacks. |
Sequence diagram
Visual Experiences
The Next Action Widget integrates flexibly into your checkout flow, regardless of whether you use DEUNA's payment widgets or build your own user interface.
When you use DEUNA's payment widgets, Next Action is seamlessly integrated.
If you prefer to build your own payment form or APM selection experience, the Next Action Widget orchestrates subsequent flows.
A flow happens as follows:
- A user interacts with your UX-UI.
- Your backend sends the request to the DEUNA Purchase API.
- Next Action is triggered if further action is required.
Requirements
To use the 3DS widget, you need:
- At least one active Connection with reference type.
- An initialized Payment widget.
Initialize the widget
Before integrating the Payment Widget, complete the Getting Started guides for your platform.
1. Show the widget
With aCreated order, display the Payment Widget in your application:
- Use the
initNextActionfunction to invoke the Next Action widget. - Call the global object function
DeunaSDK. - Pass the
orderToken, received from your backend. - Configure the callbacks necessary to manage the results..
await DeunaSDK.initNextAction({
orderToken: "<DEUNA order token>", // requerido
language: ..., // opcional
callbacks: {
// opcionales
onClosed: (action) => console.log("cerrado desde Payment Widget"),
onSuccess: (data) => console.log("purchaseResponse: ", data),
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
},
},
});
deunaSDK.initNextAction(
orderToken: "<DEUNA order token>",
callbacks: NextActionCallbacks(
onSuccess: { order in
self.deunaSDK.close() // Cierra el widget de pago
},
onError: { type in
// Manejo de errores
},
onClosed: { action in
// Widget cerrado
}
),
)
let deunaSDK: DeunaSDK = ....
deunaSDK.initNextAction(
context = YOUR_ACTIVITY_CONTEXT,
orderToken = "<DEUNA order token>",
callbacks = NextActionCallbacks().apply {
onSuccess = { data ->
deunaSDK.close() // Cierra el DialogFragment del widget de pago
// Tu código adicional
}
onError = { error ->
// Manejo de errores
}
onClosed = { action ->
// Widget cerrado
}
},
)
import { DeunaSDK, DeunaWidget } from "@deuna/react-native-sdk";
const deunaSDK = DeunaSDK.initialize({
publicApiKey: "YOUR_PUBLIC_API_KEY",
environment: "sandbox",
});
const YourScreen = () => {
const onShowPaymentWidget = () => {
deunaSDK.initNextAction({
orderToken: "<DEUNA order token>", // requerido
callbacks: {
// opcionales
onClosed: (action) => console.log("cerrado desde Payment Widget"),
onSuccess: (data) => console.log("purchaseResponse: ", data),
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
},
},
});
};
return (
<View>
<DeunaWidget instance={deunaSDK} />
<Button
onPress={onShowPaymentWidget}
title="Show Next Action Widget"
></Button>
</View>
);
};
Parameters
| Attributes | Description |
|---|---|
orderToken(Required) | 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. |
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(Required) | 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. |
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 to specify the ID or class name of the HTML element (using selectors) where you want to render the widget. Examples: #my-container, .my-container |
language(Optional) | Specifies the widget interface language Must be a valid language code: "es" for Spanish, "en" for English, "pt" for Portuguese. Behavior: - If delivered, then the widget uses the specified language independently of the merchant configuration. - If not delivered, then the widget uses the merchant configuration. |
2. Listen to Next Action events
Listen to Next Action events by callbacks and get purchase results.
The callbacks that are passed to initNextAction allow you to listen to widget events.
Define the respective callbacks to update your app UI.
Callbacks
| Callback | Trigger |
|---|---|
onSuccess(Required) | It is executed when the subsequent action has been completed successfully. This callback contains a JSON type parameter with the order information. |
onError(Required) | Executed when an error occurs while saving the card. This callback contains a JSON type parameter that identifies the type of error produced. |
onClosed (Optional) | Runs 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 or the option Cancel) without the operation being completed.- systemAction: When the widget is closed due to the execution of the function close. |
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.initNextAction({
orderToken: "<DEUNA order token>",
userToken: "...",
callbacks: {
onSuccess: ...,
onError: (error) => console.log("error", error),
onEventDispatch: (event, payload) => {
console.log("onEventDispatch: ", { event, payload });
}
},
});
3. Close the widget
Next Action widget closes when the user presses the widget's cancel button.
To close the modal when a payment is successful or if an error occurs, call the function close:
await DeunaSDK.close();
deunaSDK.close();
await deunaSDK.close();
await deunaSDK.close();
Example
await DeunaSDK.initNextAction({
orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
callbacks: {
// opcionales
onSuccess: async (data) => {
await DeunaSDK.close(); // Cierra el widget de pago
console.log("successResponse: ", data);
},
},
});
deunaSDK.initNextAction(
orderToken: "<DEUNA order token>",
callbacks: NextActionCallbacks(
onSuccess: { order in
self.deunaSDK.close() // Cierra el widget de pago
}
),
)
deunaSDK.initNextAction(
context = YOUR_ACTIVITY_CONTEXT,
orderToken = "<DEUNA order token>",
callbacks = NextActionCallbacks().apply {
onSuccess = { data ->
deunaSDK.close() // Cierra el DialogFragment del widget de pago
// Tu código adicional
}
},
)
deunaSDK.initNextAction({
orderToken: "<DEUNA order token>", // Obligatorio: Token de la orden para inicializar el widget
callbacks: {
// opcionales
onSuccess: async (data) => {
await deunaSDK.close(); // Cierra el widget de pago
console.log("successResponse: ", data);
},
},
});