Smartlinks V2

Los Smartlinks son páginas de pago alojadas por Kushki. Creas un link, lo compartes con tu cliente (por email, WhatsApp, SMS o cualquier canal) y el cliente completa el pago en un formulario alojado por Kushki, sin que necesites integración de frontend.

Tipos de configuración de pago

Tipo	Descripción
`fixed`	Defines el monto al crear el link. El cliente paga exactamente ese monto. Admite flujos de pago único, suscripción y mixto.
`open`	El cliente ingresa el monto en el checkout. Útil para donaciones, facturas con totales variables o flujos de propina.

Métodos de pago soportados

Método	fixed	open
`credit-card`	✅	✅
`cash`	✅	✅
`transfer`	✅	✅
`subscription`	✅	—

Crea un Smartlink

Llama a POST /smartlink/v2/smart-link. Kushki devuelve un smartLinkUrl listo para compartir.

{
  "publicMerchantId": "20000000103802320000",
  "merchantName": "Mi Comercio Perú",
  "paymentConfigType": "fixed",
  "paymentConfig": {
    "paymentType": "unique",
    "amount": {
      "currency": "PEN",
      "subtotalIva": 0,
      "subtotalIva0": 250,
      "iva": 0,
      "ice": 0
    },
    "paymentMethod": ["credit-card", "transfer"]
  },
  "generalConfig": {
    "productName": "Consulta médica",
    "description": "Pago por consulta médica online",
    "productImage": "https://yoursite.com/img/product.png",
    "brandLogo": "https://yoursite.com/img/logo.png",
    "executionLimit": 1,
    "showTimer": false,
    "enabled": true,
    "termsAndConditions": "https://yoursite.com/terms"
  },
  "styleAndStructure": {
    "structure": "checkout"
  },
  "contact": {
    "email": "soporte@micomercio.pe"
  },
  "formConfig": [],
  "language": "es"
}

Respuesta:

{
  "smartLinkUrl": "https://pay.kushkipagos.com/global/4RUvloWDA"
}

Campos de la solicitud

Nivel raíz

Campo	Requerido	Descripción
`publicMerchantId`	Sí	Tu Public Key de Kushki.
`merchantName`	Sí	Nombre que se muestra en la URL del Smartlink.
`paymentConfigType`	No	`fixed` (monto predefinido) u `open` (el cliente ingresa el monto).
`paymentConfig`	No	Configuración de pago para el tipo `fixed`: ver abajo.
`paymentConfig`	No	Configuración de pago para el tipo `open`: ver abajo.
`generalConfig`	Sí	Información del producto, ajustes de visualización y límites de uso: ver abajo.
`styleAndStructure`	Sí	Disposición y estilo visual: ver abajo.
`contact`	Sí	Datos de contacto de soporte.
`formConfig`	Sí	Arreglo de campos personalizados del formulario que se muestran en el checkout (puede ir vacío `[]`).
`language`	No	Idioma del checkout: `es` (español), `en` (inglés), `br` (portugués).

`paymentConfig` — monto predefinido

Campo	Requerido	Descripción
`paymentType`	Sí	`unique` (pago único), `subscription` (recurrente) o `mixed` (ambas opciones).
`amount`	Sí	Objeto de monto: `currency`, `subtotalIva`, `subtotalIva0`, `iva`, `ice`.
`paymentMethod`	Sí	Arreglo de métodos habilitados: `cash`, `credit-card`, `transfer`, `subscription`.
`subscriptionOptions`	No	Requerido cuando `paymentType` es `subscription` o `mixed`.
`mixedOptions`	No	Requerido cuando `paymentType` es `mixed`.
`fastPayments`	No	Métodos de pago rápido a habilitar (por ejemplo, `"APPLE_PAY"`).

`paymentConfig` — monto abierto

Campo	Requerido	Descripción
`paymentType`	Sí	Siempre `unique`.
`paymentMethod`	Sí	Arreglo de métodos habilitados: `cash`, `credit-card`, `transfer`.
`currency`	Sí	`PEN` o `USD`.
`taxEnabled`	Sí	`true` para aplicar impuestos.
`taxPercentage`	No	Porcentaje de impuesto. Requerido si `taxEnabled` es `true`.
`defaultAmount`	No	Monto precargado (debe estar entre `minAmount` y `maxAmount`).
`minAmount`	No	Monto mínimo que el cliente puede ingresar.
`maxAmount`	No	Monto máximo que el cliente puede ingresar.

`generalConfig`

Campo	Requerido	Descripción
`productName`	Sí	Nombre del producto o servicio que se muestra en el checkout.
`description`	Sí	Descripción (admite HTML).
`productImage`	Sí	URL de la imagen del producto.
`brandLogo`	Sí	URL del logo de tu marca.
`executionLimit`	Sí	Cuántas veces se puede usar el link. Envía `0` para uso ilimitado.
`showTimer`	Sí	Muestra un contador de tiempo en la página de checkout.
`enabled`	Sí	`true` para activar el link de inmediato.
`termsAndConditions`	Sí	URL de tus términos y condiciones.
`expirationDate`	No	Timestamp de expiración (epoch UTC).
`promotionalText`	No	Mensaje promocional que se muestra en el checkout.
`buyButtonText`	No	Texto personalizado del botón de compra. Requerido si `structure` es `cover`.
`payButtonText`	No	Texto personalizado del botón de pago.
`hidePayButtonAmount`	No	`true` para ocultar el monto en el botón de pago.

`styleAndStructure`

Campo	Requerido	Descripción
`structure`	Sí	`checkout` (formulario estándar) o `cover` (diseño de portada a página completa).
`coverModel`	No	Alineación de la imagen para `cover`: `left`, `center` o `right`. Requerido para `cover`.
`buttonStyle`	No	Forma del botón: `square`, `semi` o `round`. Requerido para `cover`.
`primaryColor`	No	Color primario de marca en hexadecimal.
`secondaryColor`	No	Color secundario de marca en hexadecimal.

Campos personalizados del formulario (`formConfig`)

Agrega hasta 6 tipos de campos personalizados para recolectar información de tu cliente en el checkout:

Tipo	Descripción
`Input`	Campo de texto de una línea (por ejemplo, nombre o ID de orden).
`Select`	Lista desplegable con opciones predefinidas.
`Date`	Calendario selector de fecha.
`Area`	Área de texto de varias líneas.
`Checkbox`	Selección múltiple de una lista.
`Radio`	Selección única de una lista.

Otras operaciones

Método	Endpoint	Descripción
`GET`	`/smartlink/v2/smart-link/{smartlinkId}`	Obtén la configuración actual y las estadísticas de uso de un Smartlink.
`PATCH`	`/smartlink/v2/smart-link/{smartlinkId}`	Actualiza la configuración de un Smartlink existente.
`DELETE`	`/smartlink/v2/smart-link/{smartlinkId}`	Elimina un Smartlink de forma permanente. Los links eliminados quedan inhabilitados de inmediato.

Autenticación

Todos los endpoints requieren tu Private Key:

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Crear un Smartlink

Genera la URL de una página de pago alojada. Configura el tipo de monto, los métodos de pago, la disposición y los campos personalizados del formulario.

Consultar un Smartlink

Obtén la configuración completa y el número de usos de un Smartlink existente.

Actualizar un Smartlink

Modifica los ajustes de un Smartlink existente sin eliminarlo ni volverlo a crear.

Eliminar un Smartlink

Elimina un Smartlink de forma permanente. Los clientes que intenten usar la URL la verán como no disponible.

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

Tipos de configuración de pago#

Métodos de pago soportados#

Crea un Smartlink#

Campos de la solicitud#

Nivel raíz#

paymentConfig — monto predefinido#

paymentConfig — monto abierto#

generalConfig#

styleAndStructure#

Campos personalizados del formulario (formConfig)#

Otras operaciones#

Autenticación#

Uso de la API#

Endpoints disponibles#