Payment Button

El Payment Button (Webcheckout) te permite crear una página de pago alojada con una sola llamada al API. En vez de construir y mantener tu propio formulario de pago, Kushki genera una URL a la que rediriges a tu cliente: ahí elige su método de pago preferido y completa la transacción en una página 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.

Cómo funciona

Crear un Webcheckout

Llama al endpoint Create a payment button desde tu backend usando tu Private Merchant ID. Envía los detalles de la orden: productos, monto, métodos de pago aceptados y una URL de redirección.

Kushki devuelve un webcheckoutUrl: una página de checkout alojada, única y lista para usar.

Redirigir al cliente

Redirige a tu cliente al webcheckoutUrl. Verá una página de checkout alojada por Kushki, precargada con el resumen de su orden, y podrá pagar con cualquiera de los métodos de pago que configuraste.

Métodos de pago aceptados 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 por PSE

El cliente completa el pago

Cuando el cliente termina (o abandona) el checkout, Kushki lo redirige a tu redirectURL. Usa el webcheckoutId que se devuelve al crear el botón para consultar el estado de la transacción si lo necesitas.

Campos de la solicitud

Campo	Obligatorio	Descripción
`kind`	✅	Siempre `"webcheckout"`
`redirectURL`	✅	URL a la que se envía al cliente después de completar o abandonar el checkout
`products`	✅	Array de objetos de producto — se muestran en el resumen de la orden
`paymentConfig`	✅	Configuración del pago; incluye el monto y los métodos aceptados
`contactDetail`		`name` y `email` del cliente — precargan el formulario de checkout
`transactionType`		Envía `"PRE_AUTH"` para crear una preautorización (flujo de autorización y captura)
`additionalInformation`		Campos clave-valor adicionales que se muestran en el resumen de compra de la página de checkout

Array `products`

Cada elemento de products describe una línea del resumen de checkout:

Campo	Obligatorio	Descripción
`name`	✅	Nombre del producto
`description`	✅	Descripción del producto
`quantity`	✅	Cantidad
`unitPrice`	✅	Precio unitario en COP

Objeto `paymentConfig`

Campo	Obligatorio	Descripción
`amount`	✅	Desglose del monto — consulta Amount Object más abajo
`paymentMethod`		Array de métodos de pago aceptados. Si lo omites, se muestran todos los métodos disponibles para tu comercio.

Objeto amount

{
  "paymentConfig": {
    "amount": {
      "subtotalIva": 42017,
      "subtotalIva0": 0,
      "iva": 7983,
      "currency": "COP"
    }
  }
}

Campo	Descripción
`subtotalIva`	Base gravable del monto (antes de IVA)
`subtotalIva0`	Monto no gravado (IVA = 0)
`iva`	Valor del IVA
`currency`	Siempre `COP` para Colombia

El total que se muestra en la página de checkout es subtotalIva + subtotalIva0 + iva.

Ejemplo de solicitud

{
  "kind": "webcheckout",
  "contactDetail": {
    "email": "user@example.com",
    "name": "Andrés Martínez"
  },
  "redirectURL": "https://www.micomercio.com/gracias",
  "products": [
    {
      "name": "Tenis Trekking Pro",
      "description": "Talla 42, color negro",
      "quantity": 1,
      "unitPrice": 250000
    }
  ],
  "paymentConfig": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 250000,
      "iva": 0,
      "currency": "COP"
    },
    "paymentMethod": ["credit-card", "cash", "transfer"]
  }
}

Ejemplo de respuesta

{
  "webcheckoutId": "T3iDy0G4I",
  "webcheckoutUrl": "https://webcheckout.kushkipagos.com/webcheckout/T3iDy0G4I"
}

Redirige al cliente de inmediato al webcheckoutUrl: los links son de un solo uso y expiran al terminar la sesión.

Flujo de preautorización

Para crear una preautorización (reservar fondos sin capturarlos), envía transactionType: "PRE_AUTH" en paymentConfig. Después de que el cliente autorice el pago en la página de checkout, capturas los fondos por separado con el API de Card.

{
  "paymentConfig": {
    "transactionType": "PRE_AUTH",
    "amount": { ... }
  }
}

Autenticación

Este endpoint requiere tu Private Key. Nunca la expongas en código del cliente ni del frontend.

Usar la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Crear un Payment Button

Genera una URL de Webcheckout alojada, precargada con los detalles de tu orden y los métodos de pago aceptados. Devuelve un webcheckoutUrl al que rediriges al cliente.

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

Cómo funciona#

Campos de la solicitud#

Array products#

Objeto paymentConfig#

Objeto amount#

Ejemplo de solicitud#

Ejemplo de respuesta#

Flujo de preautorización#

Autenticación#

Usar la API#

Endpoints disponibles#

Cómo funciona

Campos de la solicitud

Array `products`

Objeto `paymentConfig`

Objeto amount

Ejemplo de solicitud

Ejemplo de respuesta

Flujo de preautorización

Autenticación

Usar la API

Endpoints disponibles