Smartlinks te permite generar una URL de pago compartible que abre un formulario de checkout alojado por Kushki. Comparte el link por correo, WhatsApp o cualquier canal: tu cliente lo abre, llena el formulario y paga. No necesitas integración de frontend.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.
Conceptos clave#
Tipos de configuración de pago#
| Tipo | Descripción |
|---|
fixed | El monto lo defines tú; el cliente no lo puede cambiar. |
open | El cliente ingresa el monto dentro de un rango definido (minAmount / maxAmount). |
Tipos de pago (dentro de fixed)#
| Valor | Descripción |
|---|
unique | Pago único |
subscription | Cargo recurrente: el cliente queda inscrito en una suscripción |
mixed | Cargo único + inscripción a una suscripción en un mismo flujo |
| Valor | Descripción |
|---|
checkout | Diseño de checkout en línea estándar |
cover | Diseño de portada a página completa con imagen principal y botón de llamada a la acción |
Métodos de pago en Colombia#
| Valor | Método |
|---|
credit-card | Tarjeta de crédito y débito |
cash | Efectivo en puntos de pago (Baloto, Efecty, Bancolombia, etc.) |
transfer | Transferencia bancaria PSE |
subscription | Usa este valor cuando paymentType sea subscription |
Crear un Smartlink#
Llama a Create a Smartlink desde tu backend con tu publicMerchantId y los objetos de configuración. La respuesta devuelve un smartLinkUrl listo para compartir.Objetos requeridos#
| Objeto | Descripción |
|---|
publicMerchantId | Tu Public Merchant ID |
merchantName | Nombre que aparece en el slug de la URL del smartlink |
paymentConfig | Monto, tipo de pago y métodos aceptados; ver abajo |
generalConfig | Información del producto, vencimiento, límites de uso y textos de la interfaz |
styleAndStructure | Estructura del diseño y colores de marca |
contact | Correo y teléfono de soporte que se muestran en la página de checkout |
paymentConfig — monto predefinido#
{
"paymentConfigType": "fixed",
"paymentConfig": {
"paymentType": "unique",
"amount": {
"subtotalIva": 0,
"subtotalIva0": 50000,
"iva": 0,
"currency": "COP"
},
"paymentMethod": ["credit-card", "cash", "transfer"]
}
}
paymentConfig — monto abierto#
{
"paymentConfigType": "open",
"paymentConfig": {
"paymentType": "unique",
"paymentMethod": ["credit-card", "transfer"],
"currency": "COP",
"minAmount": 10000,
"maxAmount": 500000,
"defaultAmount": 50000,
"taxEnabled": false
}
}
Campos de generalConfig#
| Campo | Descripción |
|---|
productName | Nombre del producto o servicio que se muestra en el formulario |
description | Descripción en formato HTML |
productImage | URL de la imagen del producto |
brandLogo | URL del logo de tu marca |
executionLimit | Número máximo de veces que se puede usar el link. 0 = sin límite. |
expirationDate | Timestamp UTC (Epoch): el link vence después de esta fecha |
enabled | Indica si el link está activo |
termsAndConditions | URL de tu página de términos y condiciones |
showTimer | Muestra un contador de tiempo en el formulario |
buyButtonText | Texto del botón CTA (requerido si structure es cover) |
payButtonText | Texto personalizado del botón de pago |
hidePayButtonAmount | Oculta el monto en el botón de pago |
Campos de styleAndStructure#
| Campo | Descripción |
|---|
structure | "checkout" o "cover" |
primaryColor | Color primario de la marca en hexadecimal (por ejemplo, "#E83D42") |
secondaryColor | Color secundario de la marca en hexadecimal |
coverModel | Variante del diseño de portada (requerido si structure es cover) |
buttonStyle | Estilo del botón (requerido si structure es cover) |
Puedes agregar campos personalizados a tu formulario de Smartlink con el arreglo formConfig. Se admiten seis tipos de campo:| Tipo | Descripción |
|---|
input | Campo de texto libre (nombre, correo, número de referencia, etc.) |
select | Lista desplegable con opciones |
date | Calendario para elegir una fecha |
checkbox | Selector verdadero/falso (por ejemplo, aceptación de términos) |
file | Campo para subir un archivo |
disclaimer | Bloque de texto de solo lectura (sin entrada del cliente) |
Cada elemento de formConfig incluye label, type, name, placeholder, required y disabled. En los campos input, envía validateEmail: true para exigir la validación de formato de correo.
Smartlinks de suscripción#
Cuando paymentType es subscription, incluye un objeto subscriptionOptions:{
"paymentConfig": {
"paymentType": "subscription",
"paymentMethod": ["subscription"],
"amount": {
"subtotalIva0": 50000,
"subtotalIva": 0,
"iva": 0,
"currency": "COP"
},
"subscriptionOptions": {
"periodicity": "monthly",
"planName": "Plan mensual",
"startDate": "2025-06-01",
"terms": "https://micomercio.com/terminos"
}
}
}
mixed (cargo único + inscripción a una suscripción), incluye también mixedOptions con numberOfFees, periodicity y subscriptionDay.
Gestionar Smartlinks#
| Operación | Cuándo usarla |
|---|
| Get | Obtén la configuración completa del Smartlink por smartlinkId |
| Update | Modifica un Smartlink existente: monto, métodos, textos, estilo |
| Delete | Desactiva un Smartlink de forma permanente. Una vez eliminado, la URL deja de funcionar. |
Autenticación#
Usar la API#
https://api.kushkipagos.com/
Endpoints disponibles#
Crear un Smartlink
Genera una URL de pago alojada con la configuración de tu producto, monto y marca.
Consultar un Smartlink
Obtiene la configuración completa de un Smartlink existente por su ID.
Actualizar un Smartlink
Modifica un Smartlink existente: monto, métodos de pago, textos o estilos.
Eliminar un Smartlink
Desactiva un Smartlink de forma permanente. La URL deja de funcionar de inmediato.
¿Tienes alguna sugerencia sobre esta documentación? Contact us.
