Integrar Payment Link
Esta página provee una guía detallada para integrar la funcionalidad de Link de Pagos a tu aplicación través de API.
Comienza a utilizar el Payment Link
El Payment Link DEUNA te permite crear enlaces de pago para compras.
El Payment Link 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.
Requerimientos
- Conocimientos básicos de JavaScript y Typescript.
- API URLS:
- Sandbox:
https://api.sandbox.deuna.io
- Producción:
https://api.deuna.io
- Sandbox:
- Merchand ID de DEUNA:
- Sandbox: Credenciales de prueba para la implementación inicial.
- Producción: Credenciales productivas para las pruebas controladas y lanzamiento a producción.
- Credenciales para el Admin DEUNA.
- API Keys pública y privada de DEUNA.
Solicita las credenciales a tu TPM DEUNA.
Recursos
Integrar Payment Link
A continuación encontrarás cómo crear un link de pago a través de API.
Integra el Payment Link siguiendo los pasos:
1. Crea un Link de Pagos
Haz un pedido al endpoint Crear Payment Link para crear el Link de pago.
Ejemplo de request
{
"order_type": "PAYMENT_LINK",
"payer_info": {
"email": "[email protected]" // email of the user
},
"order": {
"order_id": "{{identificador orden del comercio}}",
"currency": "MXN",
"items_total_amount": 150000, //Monto con 2 decimales sin punto
"sub_total": 150000,
"total_amount": 150000,
"store_code": "all",
// URL to redirect back after payment is attempted
"redirect_urls": {
"success": "https://www.google.com?q=success", // redirect on successful payment
"error": "https://www.google.com?q=failure", // redirect on failure payment
"close": "https://www.google.com?q=close" // redirect on user closing the payment link
},
"payer_info":{
"email": "[email protected]" // email of the user
},
"billing_address": {
"country": "MX",
"country_code": "MX",
"email": "[email protected]" // email of the user
},
"items": [ // items the user is purchasing
{
"id": "79", // required
"name": "Pago de impuesto", // required
"description": "Pago de servicio de agua", // required
"type": "virtual", // required to send "virtual"
"total_amount": { // required
"amount": 150000,
"currency": "MXN"
},
"unit_price": { // required
"amount": 150000,
"currency": "MXN"
},
"quantity": 1, // required
"category": "Pago de servicios", // required
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&s" // required
}
],
"webhook_urls": { // API Endpoint into which we will send you the order status updates
"notify_order": "https://webhook.site/54a29453-05fd-4875-a861-08071421a609"
}
}
}
Ejemplo de response
{
"token": "638f7ec0-9f1f-4898-8b42-a1ac2d555216",
"order_type": "PAYMENT_LINK",
"order": {
"order_id": "4167f4a3-0081-4b3d-82ba-cf8da04e5cc4",
"store_code": "all",
"currency": "MXN",
"tax_amount": 0,
"display_tax_amount": "MXN 0.00",
"shipping_amount": 0,
"display_shipping_amount": "MXN 0.00",
"items_total_amount": 150000,
"display_items_total_amount": "MXN 1500.00",
"sub_total": 150000,
"display_sub_total": "MXN 1500.00",
"total_amount": 150000,
"display_total_amount": "MXN 1500.00",
"items": [
{
"id": "79",
"name": "Pago de impuesto",
"description": "Pago de servicio de agua",
"options": "",
"total_amount": {
"amount": 1000,
"original_amount": 0,
"display_amount": "MXN 1500.00",
"display_original_amount": "MXN 0.00",
"currency": "MXN",
"currency_symbol": "",
"total_discount": 0,
"display_total_discount": "MXN 0.00"
},
"unit_price": {
"amount": 1000,
"display_amount": "MXN 1500.00",
"currency": "MXN",
"currency_symbol": ""
},
"tax_amount": {
"amount": 0,
"display_amount": " 0.00",
"currency": "",
"currency_symbol": ""
},
"quantity": 1,
"uom": "",
"upc": "",
"sku": "",
"isbn": "",
"brand": "",
"manufacturer": "",
"category": "taxation",
"color": "",
"size": "",
"weight": {
"weight": 0,
"unit": ""
},
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&s",
"details_url": "",
"type": "virtual",
"taxable": false,
"discounts": [],
"included_in_subscription": false,
"item_details": []
}
],
"discounts": [],
"shipping_address": {
"id": 0,
"user_id": "",
"first_name": "",
"last_name": "",
"phone": "",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "",
"state_name": "",
"country_code": "",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "",
"updated_at": "",
"identity_document_type": "",
"email": "",
"state_code": "",
"country": ""
},
"shipping_options": {
"type": "",
"details": {
"store_name": "",
"address": "",
"address_coordinates": {
"lat": 0,
"lng": 0
},
"contact": {
"name": "",
"phone": ""
},
"additional_details": {
"pickup_time": "0001-01-01T00:00:00Z",
"stock_location": ""
}
}
},
"user_instructions": "",
"metadata": {},
"status": "pending",
"payment": {
"data": {
"amount": {
"amount": 0,
"currency": ""
},
"metadata": {},
"from_card": {
"card_brand": "",
"first_six": "",
"last_four": "",
"bank_name": "",
"country_iso": "",
"credential_source": "",
"expiry_month": "",
"expiry_year": ""
},
"updated_at": "0001-01-01 00:00:00 +0000 UTC",
"method_type": "",
"merchant": {
"store_code": "",
"id": "",
"affiliation_code": "",
"mcc": ""
},
"created_at": "0001-01-01 00:00:00 +0000 UTC",
"id": "",
"processor": "",
"customer": {
"email": "",
"id": "",
"first_name": "",
"last_name": ""
},
"status": "",
"reason": "",
"external_transaction_id": "",
"merchant_payment_processor_name": "",
"authorization_code": "",
"installment_interest_calculations": null,
"three_ds_details": {},
"merchant_payment_processor_id": ""
}
},
"gift_card": [],
"redirect_url": "",
"webhook_urls": null,
"total_discount": 0,
"display_total_discount": "MXN 0.00",
"shipping": {
"original_amount": 0,
"total_discount": 0,
"discounts": []
},
"cash_change": 0,
"shipping_method": {
"code": "",
"name": "",
"min_delivery_date": "",
"max_delivery_date": "",
"cost": 0,
"display_cost": "",
"tax_amount": 0,
"display_tax_amount": "",
"scheduler": []
},
"shipping_methods": [],
"timezone": "",
"scheduled_at": "",
"billing_address": {
"id": 0,
"user_id": "",
"first_name": "",
"last_name": "",
"phone": "",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "",
"state_name": "",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "2025-04-30T01:45:30Z",
"updated_at": "2025-04-30T01:45:30Z",
"email": "[email protected]",
"identity_document_type": "",
"country": "",
"state_code": ""
},
"payment_link": "https://pay.bancoazteca.deuna.com//638f7ec0-9f1f-4898-8b42-a1ac2d555216",
"display_shipping_tax_amount": "MXN 0.00",
"display_total_tax_amount": "MXN 0.00",
"shipping_tax_amount": 0,
"total_tax_amount": 0,
"user_id": "",
"include_payment_options": [],
"redirect_urls": {
"success": "https://www.google.com?q=success",
"pending": "",
"error": "https://www.google.com?q=failure",
"fallback": "",
"close": "https://www.google.com?q=close"
},
"created_at": "2025-04-30 01:45:30.06298093 +0000 UTC",
"updated_at": "",
"payer_info": {
"email": "[email protected]",
"person_type": "UNKNOWN_PERSON"
},
"discount_amount": 0,
"shipping_discount_amount": 0,
"device_fingerprint": "",
"expired_at": "",
"version": "0",
"fraud": null,
"total_interest_amount": 0,
"display_total_interest_amount": "MXN 0.00",
"payment_method": "",
"token": "",
"statement_descriptor": "",
"callback_urls": null
},
"custom_fields": [],
"checkout_modules": []
}
Descripción de campos
A continuación se documentan los campos requeridos para crear correctamente un Payment Link.
Sección order
order
Esta sección documenta los campos relacionados con la orden.
Para más información sobre órdenes, ve a la Order API.
Campo | Tipo | Obligatorio | Qué ocurre / Para qué sirve |
---|---|---|---|
order_id | string | Si | ID interno para identificar y rastrear la orden. |
store_code | string | Si | Código de tienda (o "all" para todas). |
currency | string | Si | Moneda ISO 4217 (p.ej. "MXN"). |
total_tax_amount | number | Si | Importe total de impuestos de la orden. |
items_total_amount | number | Si | Suma de precios base de todos los ítems (sin impuestos). |
sub_total | number | Si | items_total_amount + total_tax_amount. |
total_amount | number | Si | Monto final a cobrar (sub_total). |
items | array | Si | Lista de ítems; cada uno describe un producto/servicio. |
order.items[].id | string | Si | ID único del ítem. |
order.items[].name | string | Si | Nombre que verá el cliente. |
order.items[].description | string | No | Descripción detallada. |
order.items[].quantity | integer | Si | Cantidad de unidades. |
order.items[].unit_price | object | Si | Precio unitario (se muestra en checkout). |
amount | number | Si | Monto por unidad. |
currency | string | Si | Moneda ISO para el unit_price. |
currency_symbol | string | Si | Símbolo de la moneda. |
order.items[].tax_amount | object | No | Impuesto aplicado al ítem. |
order.items[].total_amount | object | Si | Desglose final del ítem. |
amount | number | Si | Total con impuestos y descuentos. |
discount_amount | number | Si | Descuento aplicado. |
original_amount | number | Si | Precio base sin impuestos. |
order.items[].image_url | string | No | URL de imagen del ítem (mejora conversión). |
redirect_urls | object | No | URLs a las que redirigir tras cada resultado. |
close | string | No | Al cerrar el checkout. |
success | string | No | Tras pago exitoso. |
pending | string | No | Si queda en estado pendiente. |
error | string | No | Si el pago falla. |
fallback | string | No | Botón “Regresar” en vistas de error |
include_payment_options | array | Si | Filtra métodos de pago y procesadores disponibles en el checkout. |
include_payment_options[].payment_method | string | Si | Tipo de método de pago (p.ej. "credit_card", "oxxopay", etc.). |
include_payment_options[].processors | object | Si | Lista de nombres de procesadores a habilitar (p.ej. ["KUSHKI"]). |
Sección checkout_modules
checkout_modules
Define cuales módulos deseas que se muestren al abrir el Link de pago en tu widget:
Campo | Tipo | Obligatorio | Qué ocurre / Para qué sirve |
---|---|---|---|
checkout_modules | array | No | Lista de módulos de checkout que quieres mostrar. |
name | string | Si | Nombre del módulo (UserInfoPattern , OrderDetailPattern , LoginPattern ). |
Si no envías
checkout_modules
, se usan la configuración por defecto en tu aplicación. Para más información , ve a Personalización de Payment Links
Sección configuration
configuration
Estos campos corresponden a las configuraciones y personalización de Links de pago.
Para ver más detalle de cada funcionalidad, ve a Crear Payment Links.
Campo | Tipo | Obligatorio | Qué ocurre / Para qué sirve |
---|---|---|---|
expires_at | string | No | Fecha/hora de caducidad (ISO 8601). Sin este campo, no expira. |
payment_link_name | string | No | Nombre descriptivo para tu Link de Pago (máx. 60 caracteres). |
max_completed_purchases | integer | No | Límite de compras exitosas antes de desactivar el enlace. |
max_payment_retries | integer | No | Límite de intentos de pago por usuario (incluye rechazos). |
2. Recupera el campo de redirect
En la respuesta, recupera el campo order.payment_link
para redireccionar al usuario a la pantalla de pago.
Integra el Payment Link en una aplicación o compártelo por un medio de comunicación propio.
Debes tener una interfaz y lógica de procesamiento de pagos propia para integrar el Payment Link en tu aplicación.
En la respuesta de llamada se encuentra el link de pago en el campo payment_link
.
Integra el Payment Link en una función en javascript, dónde se realice un href.location
que redireccione al link generado.
Ejemplo
function openDeunaPayment() {
const paymentLink = "https://api.deuna.io/payment-links/{payment-link-id}";
window.location.href = paymentLink; // Abre el enlace en la misma ventana - Opens the link in the same window
}
<!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>
3. Obten el estatus del pago
Haz un pedido a Obtener Orden para consultar el estado del pago.
Usa el token generado anteriorimente para la orden.
Ejemplo de response
{
"token": "bb0aa546-8d96-4121-8cc2-981f2e3082d1",
"order_type": "PAYMENT_LINK",
"order": {
"order_id": "8000-123-293467",
"store_code": "all",
"currency": "MXN",
"tax_amount": 0,
"display_tax_amount": "MXN 0.00",
"shipping_amount": 0,
"display_shipping_amount": "MXN 0.00",
"items_total_amount": 166746,
"display_items_total_amount": "MXN 1,500.00",
"sub_total": 166746,
"display_sub_total": "MXN 1,500.00",
"total_amount": 166746,
"display_total_amount": "MXN 1,500.00",
"items": [
{
"id": "8000-123-293467",
"name": "PAGO REGULAR SERVICIO DE AGUA",
"description": "PAGO REGULAR SERVICIO DE AGUA Contrato: 14932 Periodo Inicial: 202501 Periodo Final: 202502",
"options": "",
"total_amount": {
"amount": 166746,
"original_amount": 0,
"display_amount": "MXN 1,500.00",
"display_original_amount": "MXN 0.00",
"currency": "MXN",
"currency_symbol": "",
"total_discount": 0,
"display_total_discount": "MXN 0.00"
},
"unit_price": {
"amount": 166746,
"display_amount": "MXN 1,500.00",
"currency": "MXN",
"currency_symbol": ""
},
"tax_amount": {
"amount": 0,
"display_amount": " 0.00",
"currency": "",
"currency_symbol": ""
},
"quantity": 1,
"uom": "",
"upc": "",
"sku": "",
"isbn": "",
"brand": "",
"manufacturer": "",
"category": "curso",
"color": "",
"size": "",
"weight": {
"weight": 0,
"unit": ""
},
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&",
"details_url": "",
"type": "virtual",
"taxable": false,
"discounts": [],
"included_in_subscription": false,
"item_details": []
}
],
"discounts": [],
"shipping_address": {
"id": 0,
"user_id": "",
"first_name": "ROBERTO ANTONIO",
"last_name": "MILLAN FLORES",
"phone": "+52 5619179755",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "55770",
"state_name": "",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": true,
"created_at": "2025-04-30T00:05:19Z",
"updated_at": "2025-04-30T00:05:19Z",
"identity_document_type": "",
"email": "[email protected]",
"state_code": "",
"country": "MX"
},
"shipping_options": {
"type": "",
"details": {
"store_name": "",
"address": "",
"address_coordinates": {
"lat": 0,
"lng": 0
},
"contact": {
"name": "",
"phone": ""
},
"additional_details": {
"pickup_time": "0001-01-01T00:00:00Z",
"stock_location": ""
}
}
},
"user_instructions": "",
"metadata": {},
"status": "succeeded",
"payment": {
"data": {
"amount": {
"amount": 166746,
"currency": "MXN"
},
"metadata": {
"authorization_code": "020815"
},
"from_card": {
"card_brand": "mastercard",
"first_six": "520416",
"last_four": "8095",
"installment": {
"installments": 1,
"plan_id": "",
"plan_option_id": "",
"installment_type": "",
"installment_rate": 0,
"installment_amount": 0
},
"bank_name": "Banco Nacional De Mexico, S.A.",
"country_iso": "MX",
"credential_source": "",
"expiry_month": "04",
"expiry_year": "2028"
},
"updated_at": "2025-04-30 00:05:20.824900873 +0000 UTC",
"method_type": "credit_card",
"merchant": {
"store_code": "all",
"id": "ba8537e7-4f9d-4306-94f9-784c99304bde",
"affiliation_code": "127",
"mcc": "4900"
},
"created_at": "2025-04-30 00:05:19.747601 +0000 UTC",
"id": "8000-123-293467",
"processor": "baz_gateway",
"customer": {
"email": "[email protected]",
"id": "88635a0c-2bca-4f43-80a0-d6ebbd31709a",
"first_name": "",
"last_name": ""
},
"status": "processed",
"reason": "",
"external_transaction_id": "100740865324",
"merchant_payment_processor_name": "9269029",
"processor_error": {
"code": "",
"message": ""
},
"authorization_code": "020815",
"installment_interest_calculations": null,
"routing_strategy": "Procesamiento sin 3DS + Antifraude",
"three_ds_details": {},
"data_sync": {
"iso8583_processing_code": "",
"iso8583_response_code": "",
"iso8583_response_code_description": "",
"switch_name": "PROSA"
},
"merchant_payment_processor_id": "12235b03-e48c-4ca6-8e7c-c18676df1546"
}
},
"gift_card": [],
"redirect_url": "",
"webhook_urls": null,
"total_discount": 0,
"display_total_discount": "MXN 0.00",
"shipping": {
"original_amount": 0,
"total_discount": 0,
"discounts": []
},
"cash_change": 0,
"shipping_method": {
"code": "",
"name": "",
"min_delivery_date": "",
"max_delivery_date": "",
"cost": 0,
"display_cost": "",
"tax_amount": 0,
"display_tax_amount": "",
"scheduler": []
},
"shipping_methods": [],
"timezone": "",
"scheduled_at": "",
"billing_address": {
"id": 0,
"user_id": "",
"first_name": "ROBERTO ANTONIO",
"last_name": "MILLAN FLORES",
"phone": "+52 5619179755",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "M 64 L 21 GALEANA",
"address2": "",
"city": "Ojo de Agua",
"zipcode": "55770",
"state_name": "Estado de México",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "2025-04-30T00:05:19Z",
"updated_at": "2025-04-30T00:05:19Z",
"email": "[email protected]",
"identity_document_type": "",
"country": "",
"state_code": "MEX"
},
"payment_link": "https://pay.bancoazteca.deuna.com//bb0aa546-8d96-4121-8cc2-981f2e3082d1",
"display_shipping_tax_amount": "MXN 0.00",
"display_total_tax_amount": "MXN 0.00",
"shipping_tax_amount": 0,
"total_tax_amount": 0,
"user_id": "",
"include_payment_options": [],
"redirect_urls": {
"success": "https://www.google.com?q=success",
"pending": "https://www.google.com?q=pending",
"error": "https://www.google.com?q=error",
"fallback": "",
"close": "https://www.google.com?q=close"
},
"created_at": "2025-04-30 00:00:24.145522886 +0000 UTC",
"updated_at": "2025-04-30 00:05:20.921803615 +0000 UTC",
"payer_info": {
"email": "[email protected]",
"person_type": "UNKNOWN_PERSON"
},
"discount_amount": 0,
"shipping_discount_amount": 0,
"device_fingerprint": "",
"expired_at": "",
"version": "0",
"fraud": {
"analysis": {
"score": 0.4589535,
"processor": "SIFT",
"risk_level": "low",
"status": "automatic_decision",
"type": "",
"fraud_decision": "low_risk",
"details": "Everything Else",
"processor_response": "order_looks_ok_payment_abuse"
}
},
"total_interest_amount": 0,
"display_total_interest_amount": "MXN 0.00",
"payment_method": "",
"token": "",
"statement_descriptor": "",
"browser_details": {
"screen_height": 753,
"screen_width": 339,
"user_agent": "",
"ip_address": "",
"color_depth": 24,
"java_enabled": false,
"java_script_enabled": false,
"language": "es-ES",
"time_zone_offset": 0,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8"
},
"callback_urls": null
},
"custom_fields": [],
"checkout_modules": [],
"refunds": []
}
4. Escucha eventos del Link de pago
Usa los Webhooks de DEUNA para escuchar los eventos del Link de Pago.
Configura los reintentos de entrega como un máximo de tres intentos.
El
notification_type
debe serasync
ya que solo se ejecuta una acción cuando la notificación falla.
"payment.pending",
"payment.processed",
"payment.denied",
"payment.refunded",
"payment.partial_refunded",
"payment.partial_refunding",
"payment.voided",
"payment.cancelled",
"payment.captured",
"payment.authorized",
"payment.authorizing",
"payment.processing",
"payment.capturing",
"payment.refunding",
"payment.pending_3ds",
"order.expired"
Data de integración
Revisa la data de integración para una integración más rápida.
Prioridad para mostrar los módulos
La siguiente tabla documenta la prioridad para mostrar cada módulo:
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 el Enlace Pago 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. |
Tarjetas de prueba
Usa las tarjetas de prueba con:
- Montos menores a 50,000 MXN = APROBADO
- Montos mayores a 50,000 MXN y menores a 100,000 MXN = DECLINADO
Número de tarjeta:Con 3DS (MPI DEUNA)4000000000002503
(challenge exitoso)4000000000002370
(challenge fallido)4000000000002701
(frictionless exitoso)4000000000002925
(frictionless fallido)- Fecha expiración:
05/26
- CVV:
123
- Nombre de Tarjetahabiente:
Prueba por Deuna
Número de tarjeta:Sin 3DS4111111111111111
(credito)5474925432670366
(credito)4152313289903408
(debito)5200828282828210
(debito)4242424242424242
(credito)4622943127013705
- Fecha de expiración:
05/26
- CVV:
123
- Nombre de Tarjetahabiente:
Prueba por Deuna
Updated about 14 hours ago