Enlace de pago a través de API
En esta página
Esta página proporciona una guía detallada para integrar la funcionalidad Enlace de pago en su aplicación a través de API.
El Enlace de Pago DEUNA te permite crear enlaces de pago para compras.
El Enlace de Pago facilita y agiliza el proceso de pago a través de la plataforma DEUNA y reduce drásticamente la necesidad de cualquier desarrollo.
Requisitos#
- Conocimientos básicos de JavaScript y Typecript.
- URL de API:
- Caja de arena:
https://api.sandbox.deuna.io - Producción:
https://api.deuna.io
- Caja de arena:
- DEUNA merchant ID:
- Sandbox: prueba de credenciales para la implementación inicial
- Producción: Credenciales de producción para pruebas y lanzamiento controlados.
- Credenciales de administrador DEUNA
- Claves API públicas y privadas de DEUNA
1. Crea un enlace de pago#
Realizar una solicitud al Crear orden punto final con el order_type establecer como PAYMENT LINK.
Esto crea un token de pedido asociado con el enlace de pago.
Solicitud de ejemplo
JSON
{
"order_type": "PAYMENT_LINK",
"payer_info": {
"email": "mramos@deuna.com" // 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": "mramos@deuna.com" // email of the user
},
"billing_address": {
"country": "MX",
"country_code": "MX",
"email": "mramos@deuna.com" // 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 respuesta
JSON
{
"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": "jmoscoso@deuna.com",
"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": "mramos@deuna.com",
"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": []
}Campos de enlace de pago#
Los campos necesarios para crear un enlace de pago se documentan a continuación.
order campos
Esta sección documenta los campos relacionados con el pedido.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| order_id | string | Sí | ID interno del pedido |
| store_code | string | Sí | Código de tienda |
| moneda | string | Sí | Moneda ISO 4217 |
| total_tax_amount | number | Sí | Monto total del impuesto |
| items_total_amount | number | Sí | Suma de los precios base de todos los artículos antes de impuestos. |
| sub_total | number | Sí | artículos_total_monto + total_impuesto_monto. |
| total_amount | number | Sí | Importe total extraído del sub_total. |
| artículos | array | Sí | Lista de artículos |
| order.items[].id | string | Sí | Unique item ID |
| order.items[].name | string | Sí | Nombre del artículo para el cliente. |
| order.items[].description | string | No | Descripción detallada |
| order.items[].quantity | integer | Sí | cantidad de artículos |
| order.items[].unit_price | object | Sí | Precio unitario |
| cantidad | number | Sí | Cantidad unitaria |
| moneda | string | Sí | Moneda ISO para unidad_precio |
| currency_symbol | string | Sí | símbolo de moneda |
| order.items[].tax_amount | object | No | Impuesto aplicado al artículo |
| order.items[].total_amount | object | Sí | Importe total final |
| cantidad | number | Sí | Importe total después de impuestos y descuentos |
| discount_amount | number | Sí | Importe descontado (si corresponde) |
| original_amount | number | Sí | Precio original sin impuestos |
| order.items[].image_url | string | No | URL de la imagen del artículo |
| redirect_urls | object | No | Redirigir URL a cada resultado |
| cerrar | string | No | Cierra la caja |
| éxito | string | No | Para pagos exitosos |
| pendiente | string | No | Para pagos pendientes |
| error | string | No | Por fallas en el pago |
| respaldo | string | No | Botón Atrás en pantallas de error |
| include_payment_options | array | Sí | Filtra los métodos de pago y procesadores disponibles al finalizar la compra. |
| include_payment_options[].payment_method | string | Sí | Tipo de método de pago |
| include_payment_options[].processors | object | Sí | Lista de nombres de procesadores para habilitar |
checkout_modules campos
Defina qué módulos desea mostrar al abrir el enlace de pago en su widget:
| campo | tipo | Requiere | Qué ocurre / Para qué sirve |
|---|---|---|---|
| checkout_modules | array | No | Lista de módulos de pago para mostrar |
| nombre | string | Sí | Nombre del módulo: UserInfoPattern, OrderDetailPattern, LoginPattern |
configuration campos
Estos campos corresponden a la configuración y personalización de los Enlaces de Pago.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| expires_at | string | No | Fecha/hora de caducidad (ISO 8601). Sin este campo, la fecha/hora no caducará. |
| payment_link_name | string | No | Nombre descriptivo de su enlace de pago (máximo 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. Obtenga el campo de redireccionamiento#
En la respuesta API, useorder.payment_link para redirigir al usuario a la pantalla de pago.
Integra el enlace de pago en una aplicación o compártelo a través de tu página web.
En la respuesta a la llamada, encontrarás el enlace de pago en el campo payment_link.
Integrar el Enlace de Pago en una función javascript, donde un href.location que redirige al enlace generado.
JavaScript
function openDeunaPayment() {
const paymentLink = "https://api.deuna.io/payment-links/{payment-link-id}";
window.location.href = paymentLink; // Opens the link in the same window
}JavaScript
<!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>Tarjetas de prueba#
Utilice tarjetas de prueba para procesar pagos de prueba:
- Montos menores a 50,000 mxn = Aprobados
- Montos mayores a 50,000 mxn y menores a 100,000 mxn = Rechazados
3DS (MPI DEUNA)
Número de tarjeta:
- 4000000000002503 (desafío exitoso)
- 4000000000002370 (desafío fallido)
- 4000000000002701 (éxito sin fricciones)
- 4000000000002925 (fallo sin fricción)
- Fecha de caducidad: 26/05
- CVV: 123
- Tarjeta más fría:
Prueba por Deuna
Sin 3DS
Número de tarjeta:
4111111111111111(crédito)5474925432670366(crédito)4152313289903408(débito)5200828282828210(débito)4242424242424242(crédito)4622943127013705- Fecha de caducidad: 26/05
- CVV: 123
- Titular de la tarjeta:
Prueba por Deuna
3. Obtener el estado del pago#
Realizar una solicitud al Obtener pedido punto final para verificar el estado del pago.
Utilice el token de pedido en la solicitud.
Ejemplo de respuesta
JSON
{
"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": "juridicomillan@gmail.com",
"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": "juridicomillan@gmail.com",
"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": "juridicomillan@gmail.com",
"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": "mramos@deuna.com",
"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. Escuche los eventos del enlace de pago#
Uso Webhooks de DEUNA para escuchar eventos de enlace de pago.
Establezca los reintentos de entrega en un máximo de tres intentos.