Integración: Link de Pagos
Esta documentación detalla los pasos necesarios para integrar la funcionalidad de Link de Pagos en una aplicación de pago. Nuestro Link de Pagos permite a los comercios crear enlaces de pago para sus clientes, lo que facilita y agiliza el proceso de pago a través de la plataforma de DEUNA y reduce drásticamente la necesidad de hacer algún desarrollo. Nuestros Links de Pagos son 100% carta blanca, es decir, pueden personalizarse con el look and feel de tu marca.
Nota
Esta referencia cubre el paso a paso de instalación de nuestro Link de Pagos. Si prefieres aprender haciendo, echa un vistazo a una integración de muestra.
Antes de Comenzar
- Este documento supone que ya tienes un conocimiento básico de JavaScript y Typescript.
- Disponer de las credenciales de DEUNA. Para poder obtener tus credenciales como el Private API Key debes estar registrado y haber solicitado las credenciales de acceso de tu comercio en nuestro panel de administrador.
Configuración
1. Creación de un Link de Pagos
La metodología para generar un enlace de pago consiste en la tokenización de una orden de tipo PAYMENT_LINK.
No obstante, es importante destacar que existen modificaciones en lo que respecta al objeto de la orden, que se detallan a continuación:
El
order_type
de la orden a tokenizar debe ser de tipoPAYMENT_LINK
curl --location --request POST 'https://api.stg.deuna.io:443/merchants/orders' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{x-api-key}}' \
--data-raw '{
"order_type": "PAYMENT_LINK",
"order": {
"user_id": "95469909-0d54-4e1b-955e-7e0ba9328fbf",
"order_id": "order-test-123",
"store_code": "all",
"total_amount": 5000,
"currency": "MXN",
"items_total_amount": 5000,
"sub_total": 5000,
"items": [
{
"id": "SP40355793993780",
"name": "producto test",
"description": "descripcion de producto",
"total_amount": {
"amount": 5000,
"currency": "MXN",
"currency_symbol": "$",
"original_amount": 5000
},
"unit_price": {
"amount": 5000,
"currency": "MXN",
"currency_symbol": "$"
},
"quantity": 1,
"image_url": "https://cdn.shopify.com/s/files/1/0586/8339/2052/products/pizza-con-chorizo-jamon-y-queso-1080x671.jpg?v=1656095183",
"included_in_subscription": true
}
],
"include_payment_options": [
{
"payment_method": "credit_card",
"processors": ["dlocal"]
}
],
"billing_address": {
"first_name": "Jhon",
"last_name": "Doe",
"phone": "+549222222",
"identity_document": "1111111111-1",
"lat": -0.1602236,
"lng": -78.49664,
"address1": "Av. del Parque, Quito 170132, Ecuador",
"address2": "12",
"city": "Quito",
"zipcode": "170132",
"state_name": "Pichincha",
"state_code": "PICHINCHA",
"country": "EC",
"country_code": "EC",
"additional_description": "12",
"address_type": "home",
"email": "[email protected]"
}
},
"checkout_modules": [
{
"name": "LoginPattern",
"url": "http://cdn.deuna.com/my-pattern/index.js"
},
{
"name": "PaymentFormPattern"
}
]
}'
Respuesta:
{
"data": {
"id": "3d095a95-7da4-4e62-a57c-8c9c4d7dd9db",
"user_id": "930fedbb-a07c-44db-8514-ecf73fdee1a7",
"card_holder": "Esteban Posada",
"card_holder_dni": "185396924",
"company": "visa",
"last_four": "1111",
"first_six": "411111",
"expiration_date": "11/25",
"is_valid": true,
"verified_by": "card_verifier",
"verified_at": "0001-01-01T00:00:00Z",
"created_at": "2023-07-06T15:48:13.796043849Z",
"updated_at": "2023-07-06T15:48:13.796056921Z",
"deleted_at": null
}
}
Configuración del Body para Link de Pagos
Aquí un ejemplo de cómo debería ser el body
para una orden de Link de Pagos.
La propiedad
checkout_modules
define los módulos que de manera dinámica queremos mostrar.
Atributo | Sub-atributo | Requerido | Tipo | Ejemplo | Descripción |
---|---|---|---|---|---|
order_type | requerido | string | PAYMENT_LINK | Tipo de la orden. Es esencial definir esta orden como "PAYMENT_LINK ". | |
checkout_modules | name | requerido | string | LoginPattern | Nombre del módulo, puede ser alguno de la lista de módulos disponibles. |
url | opcional | string | https://cdn.deuna.com/my-pattern/index.js | Esta URL se usa para el caso de los módulos remotos, el patron se aloja en un repositorio independiente, ademas con este mecanismo se puede especificar un versión especifica del módulo. |
Configuración del Objeto order
para Link de Pagos
order
para Link de PagosAquí un ejemplo de las propiedades del objeto order
del body
de un Link de Pagos.
La propiedad
include_payment_options
define los métodos de pago disponibles para la orden.
Atributo | Sub-atributo | Requerido | Tipo | Ejemplo | Descripción |
---|---|---|---|---|---|
order_id | requerido | string | ORDE_ID_XYZ | Representa al identificador de la orden dentro del comercio | |
store_code | opcional | string | all | El store_code corresponde al código de una tienda, es decir, el comercio podría tener múltiples tiendas (sucursales) para los cuales el store_code sirve como identificar de las mismas, en caso de ser un comercio sin tiendas (sucursales) el valor por defecto deberá ser all | |
currency | requerido | string | MXN | Representa la moneda de uso comercial en 3 caracteres según ISO 3166-1 alpha-3 | |
items_total_amount | opcional | integer | 10000 | Total de los items de la orden, expresados en centavos | |
shipping_amount | opcional | integer | 100 | Valor del monto de envío, expresado en centavos | |
subtotal | opcional | integer | 10100 | Monto del subtotal de la orden, expresado en centavos | |
total_tax_amount | opcional | integer | 100 | Total de impuestos de la orden, expresado en centavos | |
total_amount | requerido | integer | 10200 | Total a pagar por la orden, expresado en centavos | |
include_payment_options | opcional | array | Opciones de pago disponibles para esta orden. Y caso de estar vacío llegan los métodos de pago asociados a la tienda. | ||
payment_method | requerido | string | credit_card | Nombre del método de pago a tokenizar. Si el valor de esta propiedad es "credit_card " o "debit_card " entonces se omitirá la propiedad "processors". El merchant deberá de tener configurado por lo menos un procesador para este método de pago, de lo contrario la tokenización de la orden fallará. | |
processors | opcional | array | [”amex”] | Nombre del método de pago a tokenizar. Si el valor de esta propiedad es "credit_card " o "debit_card " entonces se omitirá la propiedad "processors". El merchant deberá de tener configurado por lo menos un procesador para este método de pago, de lo contrario la tokenización de la orden fallará | |
redirect_urls | success | opcional | string | http://domain.success.com | Enlace de redirección cuando la orden es procesada exitosamente |
pending | opcional | string | http://domain.pending.com | Enlace de redirección cuando la orden es procesada y queda en un estado pending | |
error | opcional | string | http://domain.error.com | Enlace de redirección cuando la orden es procesada erróneamente | |
fallback | opcional | string | http://domain.fallback.com | Enlace de redirección del botón de Regresar en vistas de error. Si no está presente, se redirige al la vista que levantó el Payment Link. |
Link de Pagos
El enlace de pago (de único uso) se devuelve a través del atributo payment_link
en la respuesta retornada por la tokenización:
{
...
"payment_link": "https://pay.stg.deuna.com/{{order_token}}",
...
}
Un link de pago de "único uso" significa que solo se puede utilizar una vez. Una vez que la transacción se completa, el link ya no está disponible para su uso.
2. Integrar el Link de Pagos
Una vez que haya configurado la funcionalidad de Link de pagos, deberá integrarla en su aplicación de pago. Esto implica la creación de una interfaz de usuario para que los usuarios puedan hacer uso de sus enlaces de pago, así como la implementación de la lógica de procesamiento de pagos en su aplicación.
<!DOCTYPE html>
<html>
.
.
<body>
<div class="container">
<h1>Realizar Pago</h1>
<p>Haz clic en el botón "Pagar con Deuna" para continuar con el pago.</p>
<button id="payButton" class="pay-button" onclick="openDeunaPayment()">Pagar con Deuna</button>
</div>
<script src="app.ts"></script>
</body>
</html>
function openDeunaPayment() {
const paymentLink = "https://pay.stg.deuna.com/{{order_token}}";
window.location.href = paymentLink; // Abre el enlace en la misma ventana
}
3. Probar la funcionalidad de Link de pagos
Previo a la implementación de la funcionalidad de Link de Pagos en su aplicación, resulta fundamental llevar a cabo una serie de pruebas rigurosas con el propósito de garantizar el correcto funcionamiento de la misma. Estas pruebas pueden abarcar desde la integración con la plataforma de pagos en línea hasta la realización de pruebas de usuario en su aplicación.
4. Lanzar la funcionalidad de Link de pagos
Una vez que haya completado las pruebas de la funcionalidad de Link de Pagos y esté seguro de su correcto funcionamiento, está listo para implementarla en su aplicación de pagos. Asegúrese de informar adecuadamente a los usuarios sobre esta nueva funcionalidad y brinde instrucciones claras sobre cómo aprovecharla al máximo.
Siguiendo estos pasos, podrá llevar a cabo la integración de la funcionalidad de Link de Pagos en su aplicación de pagos, proporcionando a sus usuarios una vía rápida y segura para efectuar pagos en línea.
Módulos Principales
Actualmente soportamos módulos que te permitirán diseñar tu solución de manera personalizada. Estos incluyen:
Autenticación
Módulo | Descripción |
---|---|
Login Pattern | Experiencia clásica de autenticación que permite a los usuarios iniciar sesión ingresando su correo electrónico manualmente. |
LoginWithOrderEmail Pattern | Experiencia de autenticación basada en el correo electrónico incluido en la orden tokenizada, con acceso a tarjetas almacenadas. |
Datos Personales
Módulo | Descripción |
---|---|
UserInfo Pattern | Formulario clásico de datos personales con reglas personalizables. |
UserInfoSummary Pattern | Módulo de resumen del UserInfoPattern |
Además puedes agregar módulos remotos. Es decir, patrones alojados en un repositorio independiente a través de una URL. Revisa más en el apartado de configuración.
Direcciones
Módulo | Descripción |
---|---|
AddressMapWithSummary Pattern | Módulo de direcciones. Facilita a los usuarios la adición de su dirección actual o la entrada manual, aprovechando la funcionalidad de mapas. |
Detalle de la Orden
Módulo | Descripción |
---|---|
OrderDetailPattern Pattern | Módulo que resumen la orden a través de un drawer superior. |
Pagos
Módulo | Descripción |
---|---|
CardPattern | Módulo que muestra el formulario de tarjetas de crédito y débito. Solo será visible si como parte de los métodos de pago esta TC/TD. |
PaymentMethodsPattern | Módulo que muestra el resto de métodos de pago disponibles para la orden. |
UserCardPattern | SI el usuario es autenticado, se mostrarán sus tarjetas de crédito en este módulo. |
BillingPattern | Se muestra la solicitud de dos datos para facturación |
Ejemplo con BillingPattern:
Además puedes agregar módulos remotos. Es decir, patrones alojados en un repositorio independiente a través de una URL. Revisa más en el apartado de configuración.
Prioridad para mostrar los módulos
Prioridad | Fuente de Configuración | Descripción |
---|---|---|
1 | Módulos pasados al ejecutar la función .initPaymentWidget en el campo checkout_modules | Los módulos se muestran según los que se pasan al iniciar el widget. |
2 | Módulos pasados en la orden encheckout_modules | Se revisa la orden para verificar si checkout_modules tiene módulos a mostrar. |
3 | Configuración global del comercio | Si no se pasa en los checkout_modules en la función .initPaymentWidget ni en checkout_modules al momento de crear la order, se toman los checkout_modules configurados a nivel comercio. |
Preguntas Frecuentes
Obtén respuestas a preguntas comunes acerca de nuestro Payment Link
¿Qué es el Link de Pagos DEUNA y cuál es su propósito?
El Link de Pagos DEUNA es una funcionalidad que permite a los comercios crear enlaces de pago para sus clientes. Su propósito es simplificar y agilizar el proceso de pago, además de ofrecer opciones de personalización.¿Qué significa que el link de pago sea de "Único uso"?
Un link de pago de "UNICO USO" significa que solo se puede utilizar una vez. Una vez que la transacción se completa, el link ya no está disponible para su uso.¿Puedo personalizar la apariencia del Link de Pagos DEUNA en mi aplicación?
Sí, el Link de Pagos DEUNA permite personalizaciones, como incluir el logo del comercio y cambiar los colores de la barra de estilo y los botones.¿Puedo personalizar la página de agradecimiento (thank you page) después de que se genere el pago a través del Link de Pagos DEUNA?
Sí, una vez que se complete el pago, se mostrará una thank you page que indicará si la transacción fue exitosa o si ocurrió un error. Te permitimos definir una URL de success en la tokenización de la orden, con la redirección a tu propia página de agradecimiento personalizada para procesar información adicional o realizar acciones específicas.¿Se envía OTP (Código de Verificación) para todos los métodos de pago?
El envío de OTP se realiza de acuerdo a ciertos criterios, y no siempre es necesario. Para obtener detalles sobre cuándo se requiere OTP, consulta la documentación proporcionada.¿Pueden mis clientes continuar como invitado a pesar de que estén registrados en la red de DEUNA?
Sí, podrán continuar como invitado desde la pantalla de OTP, pero no podrán acceder a la información de tarjetas guardadas en tu cuenta.¿Qué sucede si intento acceder a un link de pago que ha caducado?
Si intentas acceder a un link de pago que ha caducado, se mostrará una pantalla de error con instrucciones claras sobre cómo proceder.¿Se puede procesar órdenes con diferentes métodos de pago, como tarjetas de crédito/débito, SPEI o OXXO?
Sí, el Link de Pagos DEUNA admite diferentes métodos de pago, incluyendo tarjetas de crédito/débito, SPEI (transferencias) y OXXO (referencia de pago), según estén disponibles en la orden.¿Pueden mis clientes realizar cambios en el monto a pagar dentro del Link de Pagos DEUNA?
No es posible modificar el monto a pagar dentro del Link de Pagos DEUNA. Cualquier cambio en el monto debe realizarse en la sección correspondiente del comercio electrónico, generando una nueva orden tokenizada y un nuevo link de pago.¿Dónde puedo obtener más ayuda o realizar preguntas adicionales sobre el Link de Pagos DEUNA?
Cualquier pregunta adicional o necesidad de asistencia adicional puede ser atendida comunicándote con el equipo de soporte de DEUNA. Puedes enviar un correo electrónico a [email protected] para obtener la asistencia necesaria.Updated 14 days ago