Smartlinks

Smartlinks V2 te permite generar una URL de pago alojada que compartes con tus clientes en México 🇲🇽. No necesitas integración de frontend: Kushki aloja el formulario de pago. Los clientes abren el link, completan los campos personalizados, eligen un método de pago y pagan.

Los Smartlinks admiten:

Montos Fixed — defines el precio y el cliente paga exactamente ese monto

Montos Open — el cliente ingresa el monto en el checkout (útil para donaciones, facturas o recargas)

Tipos de pago — pago único, suscripción o mixto (pago único + opción de suscripción)

Métodos de pago — tarjeta de crédito, transferencia bancaria y efectivo

Cómo funciona

Crea un Smartlink

Llama a POST /smartlink/v2/smart-link con tu configuración. Devuelve un smartLinkUrl listo para compartir.

Monto fijo — pago único:

{
  "publicMerchantId": "20000000103802320000",
  "merchantName": "mi-comercio-mexico",
  "paymentConfigType": "fixed",
  "paymentConfig": {
    "paymentType": "unique",
    "paymentMethod": ["credit-card", "transfer", "cash"],
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 500,
      "iva": 0,
      "currency": "MXN"
    }
  },
  "generalConfig": {
    "productName": "Producto de ejemplo",
    "description": "Descripción del producto",
    "productImage": "https://yoursite.com/product.jpg",
    "brandLogo": "https://yoursite.com/logo.png",
    "executionLimit": 100,
    "showTimer": false,
    "enabled": true,
    "termsAndConditions": "https://yoursite.com/terms"
  },
  "styleAndStructure": {
    "structure": "checkout",
    "buttonStyle": "round",
    "primaryColor": "#1A4CFF"
  },
  "contact": {
    "email": "user@example.com",
    "phoneNumber": "+525512345678"
  },
  "formConfig": [
    {
      "name": "nombres",
      "label": "Nombre completo",
      "type": "input",
      "required": true,
      "selected": true
    }
  ],
  "language": "es"
}

Respuesta:

{
  "smartLinkUrl": "https://pay.kushkipagos.com/smartlink/abc123xyz"
}

Comparte la URL con tu cliente

Envía el smartLinkUrl por correo, SMS o WhatsApp, o incrústalo como botón en tu sitio. El cliente lo abre en su navegador: no necesita app ni SDK.

El cliente completa el pago

El cliente completa los campos personalizados del formulario, elige su método de pago y finaliza la transacción. Kushki se encarga de todo el flujo de pago.

Obtén, actualiza o elimina el Smartlink

Usa GET /smartlink/v2/smart-link/{smartlinkId} para obtener la configuración actual, PATCH para actualizar campos (por ejemplo, deshabilitar el link o cambiar el límite de usos) y DELETE para eliminarlo de forma permanente.

Tipos de configuración de pago

`paymentConfigType`	Descripción
`fixed`	Defines el monto y el cliente paga exactamente ese valor
`open`	El cliente ingresa el monto en el checkout

Métodos de pago

Valor	Descripción
`credit-card`	Tarjeta de crédito o débito
`transfer`	Transferencia bancaria
`cash`	Efectivo en puntos de recaudo aliados
`subscription`	Pagos recurrentes con tarjeta

Tipos de pago

Valor	Descripción
`unique`	Pago único
`subscription`	Pagos recurrentes por suscripción
`mixed`	Ofrece al cliente las opciones de pago único y de suscripción

Tipos de campo del formulario

Los campos personalizados de formConfig pueden ser de cualquiera de estos tipos:

Tipo	Descripción
`input`	Campo de texto libre (nombre, correo, etc.)
`select`	Lista desplegable de opciones
`date`	Selector de fecha
`area`	Área de texto de varias líneas
`checkbox`	Casillas de selección múltiple
`radio`	Botones de opción de selección única

Configuración de monto abierto

Para paymentConfigType: "open", usa el objeto paymentConfig (ojo con el espacio al final: es una propiedad distinta de paymentConfig):

{
  "paymentConfigType": "open",
  "paymentConfig ": {
    "paymentType": "unique",
    "paymentMethod": ["credit-card", "transfer"],
    "currency": "MXN",
    "taxEnabled": false,
    "minAmount": 100,
    "maxAmount": 10000
  }
}

Campo	Descripción
`currency`	`MXN`
`taxEnabled`	Si se aplica IVA en el checkout
`taxPercentage`	Tasa de IVA (si `taxEnabled: true`)
`defaultAmount`	Monto sugerido precargado
`minAmount`	Monto mínimo que el cliente puede ingresar
`maxAmount`	Monto máximo que el cliente puede ingresar

Campos de configuración general

Campo	Obligatorio	Descripción
`productName`	✅	Nombre del producto o servicio
`description`	✅	Descripción breve que se muestra en el checkout
`productImage`	✅	URL de la imagen del producto
`brandLogo`	✅	URL del logo de tu marca
`executionLimit`	✅	Cantidad máxima de veces que se puede usar este link
`showTimer`	✅	Muestra un contador de tiempo en la página de pago
`enabled`	✅	`true` para activar el link
`termsAndConditions`	✅	URL de tu página de términos y condiciones
`expirationDate`	Opcional	Timestamp Unix — el link expira después de esa fecha
`buyButtonText`	Opcional	Texto personalizado del botón de pago

Estilo y estructura

Campo	Opciones	Descripción
`structure`	`checkout`, `cover`	Disposición de la página
`coverModel`	`left`, `center`, `right`	Posición de la imagen (solo en la disposición `cover`)
`buttonStyle`	`square`, `semi`, `round`	Estilo de las esquinas del botón de pago
`primaryColor`	Color hexadecimal	Color principal de la marca
`secondaryColor`	Color hexadecimal	Color secundario de la marca

Moneda

Moneda	Código	Notas
Peso mexicano	`MXN`	Dos decimales — los montos usan centavos (por ejemplo, `500.00`)

Idioma

Define el idioma de la página de checkout con el campo language:

Valor	Idioma
`es`	Español
`en`	Inglés
`br`	Portugués

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Crear un Smartlink

Genera una URL de pago alojada con la configuración de tu producto, el branding, los campos del formulario y los métodos de pago.

Consultar un Smartlink

Obtén la configuración actual y el estado de un Smartlink por su ID.

Actualizar un Smartlink

Modifica un Smartlink existente: habilítalo o deshabilítalo, actualiza el límite de usos o cambia campos de configuración.

Eliminar un Smartlink

Elimina un Smartlink de forma permanente. Esta acción no se puede deshacer.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Cómo funciona#

Tipos de configuración de pago#

Métodos de pago#

Tipos de pago#

Tipos de campo del formulario#

Configuración de monto abierto#

Campos de configuración general#

Estilo y estructura#

Moneda#

Idioma#

Autenticación#

Uso de la API#

Endpoints disponibles#