Smartlinks

Recibe pagos por canales como chats y redes sociales sin escribir una sola línea de código.

Los Smartlinks son links de pago que puedes compartir para vender en línea sin tener un sitio web. Crea uno en segundos y compártelo por WhatsApp, email, Instagram, Facebook o cualquier otro canal: tus clientes reciben una página de pago alojada por Kushki.

¡Ten en cuenta!

Por nuestras políticas de riesgo, los métodos de pago disponibles y el tipo de integración pueden variar una vez que completes la afiliación. Te indicaremos cómo proceder si este proceso aplica a tu comercio.

Qué puedes hacer con Smartlinks

Todos los métodos de pago

Acepta tarjetas de crédito o débito, transferencia bancaria y efectivo, todo desde un solo link.

Pago único o recurrente

Configura pagos únicos, suscripciones recurrentes o ambos (mixed) en el mismo link.

Monto fijo o abierto

Define un precio predefinido (fixed) o deja que el cliente ingrese cualquier monto dentro de un rango (open).

Totalmente personalizable

Agrega el logo de tu marca, la imagen del producto, los colores y un texto de botón personalizado.

Controles de uso

Limita cuántas veces se puede usar un link, define una fecha de expiración o deshabilítalo cuando quieras.

Campos de formulario personalizados

Recolecta datos adicionales de tus clientes (nombre, email, fechas, selecciones y más) con campos de formulario configurables.

ID del Smartlink

Cuando creas un Smartlink, Kushki devuelve un smartLinkUrl. El smartlinkId es el último segmento de esa URL y se usa como parámetro de ruta en todas las demás operaciones (Get, Update, Delete).

https://uat.kshk.co/global/u2Ab4qE_b
                            └─────────┘
                            smartlinkId = u2Ab4qE_b

Estructura de la petición

Para crear un Smartlink debes enviar estos objetos de nivel superior:

Objeto	Propósito
`publicMerchantId`	Tu Public Key
`merchantName`	Nombre que se muestra en la URL del Smartlink
`paymentConfig`	Monto, método y tipo de pago
`generalConfig`	Detalles del producto, límites y expiración
`styleAndStructure`	Diseño visual y colores de marca
`contact`	Contacto de soporte para quien paga
`formConfig`	Campos personalizados que se muestran en el formulario de pago
`language`	Idioma del formulario: `es` (por defecto), `en`, `br`

Configuración del pago

Tipo de monto

El campo paymentConfigType controla cómo se define el monto:

fixed — Monto predefinido

open — Monto definido por el cliente

Tú defines el monto exacto. El cliente no lo puede cambiar. Usa paymentConfig (sin espacio al final).

Campos requeridos:

Campo	Descripción
`paymentType`	`unique`, `subscription` o `mixed`
`amount`	Objeto de monto
`paymentMethod`	Array: `cash`, `credit-card`, `transfer`, `subscription`

Usa subscription en paymentMethod cuando paymentType sea subscription.

Tipo de pago

Cuando usas paymentConfigType: fixed, el campo paymentType controla el modelo de cobro:

unique — Pago único

subscription — Solo recurrente

mixed — Pago único + recurrente

Un solo cargo. No necesitas configuración de recurrencia.

Configuración general

El objeto generalConfig controla la presentación del producto y el comportamiento del link:

Campo	Requerido	Descripción
`productName`	✅	Nombre del producto o servicio
`description`	✅	Descripción del producto en formato HTML (por ejemplo, `<p>Descripción</p>`)
`productImage`	✅	URL de la imagen del producto
`brandLogo`	✅	URL del logo de tu marca
`executionLimit`	✅	Número máximo de usos. Usa `0` para que no haya límite; si defines un valor, el link se deshabilita al alcanzarlo.
`showTimer`	✅	Muestra un contador de tiempo en la página de pago
`enabled`	✅	Indica si el Smartlink está activo
`termsAndConditions`	✅	Texto de términos y condiciones
`promotionalText`	❌	Mensaje promocional que se muestra en la página de pago
`expirationDate`	❌	Fecha de expiración como timestamp UTC (Epoch) (por ejemplo, `1585717199999`)
`buyButtonText`	❌	Requerido si `structure` es `cover`
`payButtonText`	❌	Texto personalizado del botón de pago. Máximo 20 caracteres.
`hidePayButtonAmount`	❌	Oculta el monto en el botón de pago. Por defecto: `false`

Estilo y estructura

El objeto styleAndStructure controla el diseño visual de la página de pago:

Campo	Requerido	Valores	Descripción
`structure`	✅	`checkout`, `cover`	Tipo de diseño. `checkout` es un formulario estándar; `cover` agrega una sección de portada visual.
`coverModel`	❌*	`left`, `center`, `right`	Alineación de la imagen de portada. *Requerido cuando `structure` es `cover`.
`buttonStyle`	❌*	`square`, `semi`, `round`	Forma del botón de pago. *Requerido cuando `structure` es `cover`.
`primaryColor`	❌	Hex (por ejemplo, `#00E6B2`)	Color primario de la marca
`secondaryColor`	❌	Hex (por ejemplo, `#023366`)	Color secundario de la marca

Campos del formulario

El array formConfig define los campos personalizados que se muestran en el formulario de pago. Puedes incluir hasta 6 tipos de campo distintos. Todos los ítems comparten estos campos comunes:

Campo	Descripción
`label`	Etiqueta que ve el cliente
`type`	Tipo de campo (ver abajo)
`name`	Identificador interno del campo
`split`	`true` = campo de media anchura · `false` = campo de anchura completa
`required`	Indica si el campo es obligatorio

input

select

date

area

checkbox

radio

Campo de texto de una línea. Útil para nombre, correo y otros textos cortos.

Campos adicionales: placeholder, disabled, value (requerido si disabled: true), validateEmail

Define validateEmail: true en cualquier campo input donde esperes que el cliente ingrese un correo. El formulario valida el formato antes de enviarse.

Gestionar Smartlinks

Una vez creado un Smartlink, puedes consultarlo, actualizarlo o eliminarlo de forma permanente usando el smartlinkId.

Eliminar un Smartlink es permanente. El link deja de estar accesible una vez eliminado.

Códigos de error

Código	Mensaje	Causa
`WCH001`	El cuerpo de la petición es inválido	Cuerpo mal formado o faltan campos requeridos
`WCH002`	Ha ocurrido un error inesperado	Error inesperado del servidor
`WCH003`	Smartlink no encontrado, no disponible o expirado	`smartlinkId` inválido, link deshabilitado o link expirado
`WCH009`	Credenciales inválidas	`Private-Merchant-Id` inválido
`WCH012`	Moneda del smartlink inválida	Moneda no soportada para el país del comercio

Autenticación

Todos los endpoints de Smartlink usan tu Private Merchant ID:

El publicMerchantId se envía en el cuerpo de la petición (no como cabecera) cuando creas un Smartlink.

Usar la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Crear un Smartlink

Crea un nuevo link de pago y devuelve el smartLinkUrl que compartes con tus clientes.

Consultar un Smartlink

Obtiene la configuración completa de un Smartlink existente a partir del smartlinkId.

Actualizar un Smartlink

Actualiza cualquier campo de configuración de un Smartlink existente a partir del smartlinkId.

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.

Qué puedes hacer con Smartlinks#

ID del Smartlink#

Estructura de la petición#

Configuración del pago#

Tipo de monto#

Tipo de pago#

Configuración general#

Estilo y estructura#

Campos del formulario#

Gestionar Smartlinks#

Códigos de error#

Autenticación#

Usar la API#

Endpoints disponibles#

Qué puedes hacer con Smartlinks

ID del Smartlink

Estructura de la petición

Configuración del pago

Tipo de monto

Tipo de pago

Configuración general

Estilo y estructura

Campos del formulario

Gestionar Smartlinks

Códigos de error

Autenticación

Usar la API

Endpoints disponibles