Payment Widget - Web
El Payment Widget es una componente web que acepta pagos en mas de 50+ metodos de pago simplificando la validacion de campos, el manejo de errores y cumplimiento con estandares PCI DSS. Úselo dentro de su experiencia de checkout ó como un componente independiente.
Adicionalmente, puedes usar nuestras capacidades avanzadas de pago solo con una integraccion. Esto incluye compras con soporte a:
- MSI (Meses sin Intereses)
- MCI (Meses con Intereses)
- Flujo 3DS
- Autorización y Captura
- OTP (one-time password) con tarjetas Diners Club
- Revision manual
Requisitos
Si cuentas con estos requisitos entonces estas listo para comenzar a integrarlo:
- Tener una cuenta registrada y un par de credenciales de desarrollo. Refiérase a la seccion Empecemos DEUNA para conocer mas acerca al respecto.
- Conocimientos en desarrollo con Javascript o Typescript
- NPM versión mínima 9.x o posterior
Paso 1: Agregar el widget de pago a tu sitio web
Carga nuestro widget por medio de la URL oficial para el ambiente deseado. Como buena practica, procura usar nuestro CDN para alta disponibilidad y no desde tu propio servidor. El atribute crossorigin
brinda soporte para CORS, definiendo como el elemento script
maneja llamadas de origin cruzado.
Agrega el siguiente script en tu archivo html
<script crossorigin src="https://cdn.getduna.com/payment-widget/v2.0.0/index.js" type="application/javascript"></script>
Paso 2: Configurar el widget de pago
Crea una instancia de DeunaPay
const deunaPay = new window.DeunaPay();
Ahora debes configurar el widget de pago usando el token de una orden y el ambiente (Sandbox o Producción)
await deunaPay.configure({
env:"sandbox", // or production,
orderToken: "YOUR_ORDER_TOKEN",
showPromotionsBanner: true, // Optional
onEventDispatch: (event, payload) => { // Optional
console.log("✅ onEventDispatch: ", { event, payload });
},
});
Parámetros
Parámetro | Descripción |
---|---|
env | Ambiente de pruebas (sandbox) o producción (production) |
orderToken | El token de una orden previamente generada usando la API de DEUNA https://docs.deuna.com/reference/order_token |
onEventDispatch (Opcional) | Callback para escuchar todos los eventos del widget de pagos |
showPromotionsBanner (Opcional) | Si se pasa el valor false, el banner de promociones en el widget de pagos no será visible. Valor por defecto false . |
userToken (Opcional) | El bearer token del usuario de DEUNA. Cuando este es enviado, todas las acciones dentro del widget van a hacer sobre este usuario de DEUNA. Importante: para que este userToken sea usado y se le muestren las tarjetas guardadas al cliente, el correo asociado a ese userToken debe ser el mismo que se envía al crear la orden en billing_address.email . En caso que ambos correos no coincidan, se usará el flujo sin mostrar las tarjetas por seguridad. |
Paso 3: Mostrar el widget de pago
Para mostrar el widget de pago llama a la función show con los callbacks respectivos para escuchar los eventos del widget de pago.
await deunaPay.show({
callbacks: {
onClose: () => console.log("Payment widget was closed"),
onPaymentSuccess: (order) => {
// YOUR_CODE_HERE
},
onPaymentFailure: (error) => console.log(error),
onCardBinDetected: async (metadata, refetchOrder) => {
// YOUR_CODE_HERE
},
onInstallmentSelected: async (metadata, refetchOrder) => {
// YOUR_CODE_HERE
},
},
});
Parámetros
Parámetro | Descripción |
---|---|
onClose (Opcional) | Se ejecuta cuando el widget de pago se cierra. Este callback únicamente se ejecuta si el widget fue mostrado dentro del modal por defecto y este modal es cerrado por el usuario o el modal fue cerrado mediante la llamada a la función close . |
onPaymentSuccess (Opcional) | Se ejecuta cuando se completo el pago. |
onPaymentFailure (Opcional) | Se ejecuta cuando ocurrió un error al procesar el pago. |
onCardBinDetected (Opcional) | Se ejecuta cuando el widget de pago detecta el bin de una tarjeta de crédito o debito ingresada o cuando el usuario borra el número de la tarjeta ingresada. |
onInstallmentSelected (Opcional) | Si la orden se puede diferir este callback se ejecutara cuando el usuario seleccione los meses a diferir. |
target (Opcional) | Permite mostrar el widget de pago en un elemento html personalizado. Si no se define este campo por defecto el widget se mostrará en un modal. |
NOTA: En los callbacks
onCardBinDetected
yonInstallmentSelected
el parámetrorefetchOrder
es una función que se puede utilizar para refrescar los datos de la orden en el formulario de pagos. El dato retornado por la funciónrefetchOrder
es unPromise
con los datos de la orden o un valor nulo si ocurrió un error al momento de ejecutar la funciónrefetchOrder
.
Ejemplo:
await deunaPay.show({
callbacks: {
onCardBinDetected: async (metadata, refetchOrder) => {
if (!metadata || !metadata?.cardBin){
return;
}
const order = await refetchOrder();
if(order){
// YOUR CODE HERE
}
},
},
});
Paso 4: Eventos del widget de pago.
Cuando una transacción es exitosa o falla es importante actualizar tu interfaz para notificar a los usuarios sobre el resultado de la transacción (Ejemplo: Redireccionar a una vista de compra exitosa o una vista de error). Esto lo puedes realizar escuchando los eventos del widget de pago mediante los callbacks onPaymentSuccess
y onPaymentFailure
.
Si el pago fue exitoso el callback onPaymentSuccess
se ejecutará en donde el parámetro de dicho callback será un JSON similar al siguiente.
{
"order_id": "payment_link_1874356",
"sub_total": 2682,
"total_amount": 2682,
.
.
.
}
Si el pago no se pudo procesar el callback onPaymentFailure
se ejecutará en donde el parámetro de dicho callback será un JSON similar al siguiente.
{
"event": "purchaseError",
"metadata": {
"errorCode": "DP-10026",
"errorMessage": "transaction declined"
},
"order": {
"order_id": "payment_link_62981504",
.
.
.
}
}
El siguiente ejemplo muestra como escuchar cuando un pago fue exitoso
await deunaPay.show({
callbacks: {
onPaymentSuccess: (order) => {
// YOUR_CODE_HERE
},
},
});
Paso 5 (Opcional): Mostrar el widget en un elemento html personalizado
Por defecto el payment widget se muestra en un modal. Si deseas mostrarlo en un elemento html personalizado debes definir el campo target
al momento de llamar a la función show
.
El siguiente código de ejemplo muestra el widget en un elemento html personalizado
<div id="deuna"></div>
await deunaPay.show({
target: "#deuna", // Use # at the beginning to reference one element by its ID
});
Paso 6 (Opcional): Método para cerrar Widget
Por defecto, el widget se cierra al presionar el botón de cerrar (X) del mismo. Sin embargo, hemos incluido un método adicional que permite forzar el cierre del widget a través de código.
La ventaja de este método es que puedes personalizar cuándo cerrar el modal, no limitándote únicamente a la acción del botón de cerrar del widget. Por ejemplo, después de que el proceso de pago finaliza, puedes cerrar el modal utilizando este código y luego redireccionar al usuario a otra página.
![](https://files.readme.io/f0271e0-image.png)
Para forzar el cierre del modal usa la función close
.
await deunaPay.close();
El siguiente ejemplo muestra como cerrar el modal después de que el pago fue exitoso.
await deunaPay.show({
callbacks: {
onPaymentSuccess: async (order) => {
await deunaPay.close();// close the modal
// YOUR_CODE_HERE
},
},
});
Updated 2 months ago