Developer tools

Checkout widget - Android

Accept and process payments in your application using the Checkout widget.

Follow the steps below to capture payments.

Initialize the Widget

Before integrating the Payment Widget, complete the Getting Started - Android.

1. Display the Widget

To display the Checkout Widget, call the initCheckout function passing the following data:

Parameters

AttributesDescription
contextThe context is the context of your Activity in Android. It provides access to application-specific resources and information about the environment in which the application is running.
orderTokenThe orderToken is a unique token generated for the payment order. This token is generated through DEUNA's API and you must implement the corresponding endpoint in your backend to obtain this information.

NOTE: The checkout widget requires an order of type PAYMENT_LINK.

IMPORTANT: When creating the order with DEUNA's API, a redirect URL (redirect_url) should not be defined so that the onSuccess callback executes correctly.
callbacksCallbacks are return functions that are responsible for listening to and handling payment widget events. These events allow managing specific actions based on the payment status. The main callbacks include: onSuccess, onError, onClosed, onCanceled, eventListener
userToken (Optional)The DEUNA user's bearer token. When this is sent, all actions within the widget will be performed on this DEUNA user.

Important: for this userToken to be used and saved cards to be shown to the customer, the email associated with that userToken must be the same as the one sent when creating the order in billing_address.email. If both emails don't match, the flow without showing cards will be used for security.
styleFile (Optional)UUID provided by DEUNA. This applies if you want to configure a custom custom styles file (Change colors, texts, logo, etc). If a valid value is provided for styleFile the checkout widget will use the UI configuration provided by the theme configuration that matches the provided UUID.
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 configuration.
- If not provided: The widget will use the language configured by the merchant.
val deunaSDK: DeunaSDK = ...

deunaSDK.initCheckout(
    context = YOUR_ACTIVITY_CONTEXT,
    orderToken = "YOUR_ORDER_TOKEN",
    callbacks = CheckoutCallbacks().apply {
        onSuccess = { order ->
            deunaSDK.close() // Close the payment widget
            // Your additional code
        }
        onError = { error ->
            deunaSDK.close() // Close the payment widget
            // Error handling
        }
        onClosed = { action ->
            // The payment widget was closed
        }
        onEventDispatch = { event, response ->
            // Listen to payment process events
            // Your code here
        }
    },
    closeEvents = setOf(CheckoutEvent.changeCart, CheckoutEvent.changeAddress) // Close the widget when user chooses to change address or payment method
)

2. Listen to Widget Events

When a transaction is successful or fails, it's important to update your interface to notify users about the transaction result. You can do this by listening to the payment widget events through callbacks.

The instance of the PaymentWidgetCallbacks class passed to the initPaymentWidget function allows you to listen to widget events through callbacks.

📘

Define the respective callbacks to update your app's interface.

Callbacks

CallbackWhen is it triggered?
onSuccessIt's executed when the payment is completed. This callback contains a parameter of type Map<String,Any> with the order information.
onErrorIt's executed when an error occurs. This callback contains a parameter of type PaymentsError which identifies the type of error produced.

See an example of the callback response here.
onClosed (Optional)It's executed when the payment widget is closed.

This callback contains a parameter of type enum CloseAction with the following values:

- userAction: When the widget was manually closed by the user, pressing the close button (X) or the back button on Android without the operation being completed.

- systemAction: When the widget is closed due to the execution of the close function.
onCanceledIt's executed when the user intentionally closes the payment widget (pressing the X button or pressing the back button) without the operation being completed.
onEventDispatch (Optional)It's executed on all events that the widget can produce. This callback contains a parameter of type CheckoutEvent

3. Close the Widget

By default, the payment widget only closes when the user presses the widget's close button or when they press the "back" button on Android.

To close the modal when a payment is successful or when an error occurs, you must call the close function.

deunaSDK.initCheckout(
  context = YOUR_ACTIVITY_CONTEXT,
  orderToken = "YOUR_ORDER_TOKEN",
  callbacks = CheckoutCallbacks().apply {
    onSuccess = { order -> 
      deunaSDK.close() // Close the payment widget
      // Your additional code
    }
  }
)

4. Customize Widget Appearance

Use the setCustomStyle function to customize the Widget appearance.

await DeunaSDK.setCustomStyle({...});

📘

For more information, refer to Style Customization.

Example

val deunaSDK: DeunaSDK = ...

deunaSDK.initCheckout(
    context = YOUR_ACTIVITY_CONTEXT,
    orderToken = "YOUR_ORDER_TOKEN",
    callbacks = CheckoutCallbacks().apply {
        onSuccess = ...
        onError = ...
        onClosed = ...
        onEventDispatch = { event, response ->
            // Listen to payment process events
            // Your code here
          deunaSDK.setCustomStyle(
             data = JSONObject(
                        """
                        {
                          "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"
                                }
                              }
                            }
                          }
                        }
                        """
         ).toMap()
        )
        }
    }
)