Documentación

Payment Link via API

Suggest Edits

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.

Los Links de Pagos DEUNA son 100% carta blanca, pueden personalizarse con el look and feel de tu marca.

Requisitos

  • Conocimientos básicos de JavaScript y Typescript.
  • API Keys pública y privada de DEUNA.
  • Credenciales para el ADMIN DEUNA.

📘

Para obtener tus credenciales debes estar registrado y haber solicitado las credenciales de acceso en nuestro panel de administrador.

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.

Ejemplo

{
  "order": {
    "order_id":            "ORD_000123",  
    "store_code":          "all",
    "currency":            "MXN",
    "total_tax_amount":    220,
    "items_total_amount":  7000,
    "sub_total":           7000,
    "total_amount":        7220,
    "items": [
      {
        "id":           "789012345",
        "name":         "Event Ticket",
        "description":  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean euismod bibendum laoreet.",
        "quantity":     1,
        "unit_price": {
          "amount":          7220,
          "currency":        "PEN",
          "currency_symbol": "S/"
        },
        "tax_amount": {
          "amount":          0,
          "currency":        "PEN",
          "currency_symbol": "S/"
        },
        "total_amount": {
          "amount":          7220,
          "discount_amount": 0,
          "currency":        "PEN",
          "currency_symbol": "S/",
          "original_amount": 0
        },
        "image_url":    "https://cdn.stg.deuna.io/explore-deuna/assets/ticketevent.png"
      }
    ],
    "include_payment_options": [
                {
                    "payment_method": "credit_card",
                    "processors": [
                        "KUSHKI"
                    ]
                }
      ],
    "redirect_urls": {
      "close":    "https://www.google.com?q=close",
      "success":  "https://www.google.com?q=success",
      "pending":  "https://www.google.com?q=pending",
      "error":    "https://www.google.com?q=failure",
      "fallback": "https://www.google.com?q=fallback"
    }
  },
  "checkout_modules": [
    { "name": "UserInfoPattern"    },
    { "name": "OrderDetailPattern" },
    { "name": "LoginPattern"       }
  ],
  "configuration": {
    "expires_at":             "2025-11-07T03:40:11.054707389Z",
    "payment_link_name":      "creacion template + impuestos",
    "max_completed_purchases": 20,
    "max_payment_retries":     2
  }
}

Descripción de campos

A continuación se documentan los campos requeridos para crear correctamente un Payment Link.

A. Sección order

Esta sección documenta los campos relacionados con la orden.

📘

Para más información sobre órdenes, ve a la Order API.

CampoTipoObligatorioQué ocurre / Para qué sirve
order_idstringSiID interno para identificar y rastrear la orden.
store_codestringSiCódigo de tienda (o "all" para todas).
currencystringSiMoneda ISO 4217 (p.ej. "MXN").
total_tax_amountnumberSiImporte total de impuestos de la orden.
items_total_amountnumberSiSuma de precios base de todos los ítems (sin impuestos).
sub_totalnumberSiitems_total_amount + total_tax_amount.
total_amountnumberSiMonto final a cobrar (sub_total).
itemsarraySiLista de ítems; cada uno describe un producto/servicio.
order.items[].idstringSiID único del ítem.
order.items[].namestringSiNombre que verá el cliente.
order.items[].descriptionstringNoDescripción detallada.
order.items[].quantityintegerSiCantidad de unidades.
order.items[].unit_priceobjectSiPrecio unitario (se muestra en checkout).
└─ amountnumberSiMonto por unidad.
└─ currencystringSiMoneda ISO para el unit_price.
└─ currency_symbolstringSiSímbolo de la moneda.
order.items[].tax_amountobjectNoImpuesto aplicado al ítem.
order.items[].total_amountobjectSiDesglose final del ítem.
└─ amountnumberSiTotal con impuestos y descuentos.
└─ discount_amountnumberSiDescuento aplicado.
└─ original_amountnumberSiPrecio base sin impuestos.
order.items[].image_urlstringNoURL de imagen del ítem (mejora conversión).
redirect_urlsobjectNoURLs a las que redirigir tras cada resultado.
└─ closestringNoAl cerrar el checkout.
└─ successstringNoTras pago exitoso.
└─ pendingstringNoSi queda en estado pendiente.
└─ errorstringNoSi el pago falla.
└─ fallbackstringNoBotón “Regresar” en vistas de error
include_payment_optionsarraySiFiltra métodos de pago y procesadores disponibles en el checkout.
└─ include_payment_options[].payment_methodstringSiTipo de método de pago (p.ej. "credit_card", "oxxopay", etc.).
└─ include_payment_options[].processorsobjectSiLista de nombres de procesadores a habilitar (p.ej. ["KUSHKI"]).

B. Sección checkout_modules

Define cuales módulos deseas que se muestren al abrir el Link de pago en tu widget:

CampoTipoObligatorioQué ocurre / Para qué sirve
checkout_modulesarrayNoLista de módulos de checkout que quieres mostrar.
└─ namestringSiNombre 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

C. Sección 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.

CampoTipoObligatorioQué ocurre / Para qué sirve
expires_atstringNoFecha/hora de caducidad (ISO 8601). Sin este campo, no expira.
payment_link_namestringNoNombre descriptivo para tu Link de Pago (máx. 60 caracteres).
max_completed_purchasesintegerNoLímite de compras exitosas antes de desactivar el enlace.
max_payment_retriesintegerNoLímite de intentos de pago por usuario (incluye rechazos).

2. Añade el Link de Pagos a función JS

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>

Prioridad para mostrar los módulos

La siguiente tabla documenta la prioridad para mostrar cada módulo:

PrioridadFuente de ConfiguraciónDescripción
1Módulos pasados al ejecutar la función .initPaymentWidgeten el campo checkout_modulesLos módulos se muestran según los que se pasan al iniciar el widget.
2Módulos pasados en el Enlace Pago encheckout_modulesSe revisa la orden para verificar si checkout_modules tiene módulos a mostrar.
3Configuración global del comercioSi 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.

Updated 2 days ago