One-Click & Scheduled Payments - Kushki Developer Portal

One-Click & Scheduled Payments te permite registrar la tarjeta de un cliente como una suscripción y cobrarla después, ya sea automáticamente según un calendario o manualmente on demand. Los datos de la tarjeta se tokenizan una sola vez y nunca se almacenan en tus servidores.

¡Ten en cuenta!

La generación del token requiere tu Private Key (Private-Merchant-Id). Nunca la expongas en código de cliente o de frontend: llama siempre al endpoint de token desde tu backend.

Dos modos de cobro

Modo	Cómo funciona
Scheduled	Kushki cobra la tarjeta automáticamente según la `periodicity` que configures (daily, monthly, yearly, etc.)
One-click (on-demand)	Disparas cada cargo manualmente con `POST /subscriptions/v1/card/{subscriptionId}`. Usa `periodicity: "custom"` al crear la suscripción.

Flujo

Solicita un token de suscripción

Llama a POST /subscriptions/v1/card/tokens desde tu backend con los datos de la tarjeta del cliente. Devuelve un token de un solo uso.

{
  "card": {
    "name": "Luis García",
    "number": "4242424242424242",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "123"
  },
  "currency": "PEN"
}

⚠️ Expiración del token: Usa el token de inmediato para crear la suscripción. No lo almacenes.

Crea la suscripción

Llama a POST /subscriptions/v1/card con el token, los detalles del plan y el monto recurrente. La respuesta devuelve un subscriptionId que debes guardar de tu lado.

{
  "token": "gV3ox6100000sAxClU033646vnnJsT83",
  "planName": "Premium",
  "periodicity": "monthly",
  "startDate": "2026-06-01",
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 99.90,
    "ice": 0,
    "iva": 0,
    "currency": "PEN"
  }
}

Cobra la suscripción

Programado: Kushki cobra automáticamente; no necesitas hacer nada.

One-click: Llama a POST /subscriptions/v1/card/{subscriptionId} cuando quieras cobrarle al cliente.

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 99.90,
    "ice": 0,
    "iva": 0,
    "currency": "PEN"
  },
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  }
}

Un cargo exitoso devuelve un ticketNumber y un transactionReference. Usa "fullResponse": "v2" para obtener todos los detalles de la aprobación.

💡 OTP en sandbox: Si se dispara la validación OTP en sandbox, usa 555 tanto para PEN como para USD.

Periodicidades

Valor	Frecuencia
`daily`	Todos los días
`weekly`	Cada semana
`biweekly`	Cada dos semanas
`monthly`	Una vez al mes
`threefortnights`	Cada tres quincenas
`bimonthly`	Cada dos meses
`quarterly`	Cada tres meses
`fourmonths`	Cada cuatro meses
`halfYearly`	Cada seis meses
`yearly`	Una vez al año
`custom`	On-demand: disparas cada cargo manualmente

Tipos de documento

Valor	Descripción
`DNI`	Documento Nacional de Identidad 🇵🇪
`CE`	Carné de Extranjería 🇵🇪
`PAS`	Pasaporte 🇵🇪
`RUC`	Registro Único de Contribuyentes 🇵🇪

Cargos diferidos en suscripciones

Perú admite diferido en los cargos de suscripción. Incluye el objeto deferred en la solicitud de cargo:

Modelo Agregador

Modelo Adquirencia

Envía months como campo de primer nivel (no dentro de deferred):

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 300.00,
    "iva": 0,
    "ice": 0,
    "currency": "PEN"
  },
  "months": 3,
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  }
}

Gestión de suscripciones

Operación	Endpoint	Descripción
Consultar info	`GET /subscriptions/v1/card/search/{subscriptionId}`	Obtén los detalles de la suscripción, la información de la tarjeta y la configuración del plan
Actualizar tarjeta	`PUT /subscriptions/v1/card/{subscriptionId}/card`	Reemplaza la tarjeta registrada por un nuevo token
Actualizar plan	`PATCH /subscriptions/v1/card/{subscriptionId}`	Modifica el monto, la periodicidad o el nombre del plan
Agregar cargo temporal	`PUT /subscriptions/v1/card/{subscriptionId}`	Aplica un cargo o descuento extra por una sola vez en el siguiente ciclo de facturación
Cancelar	`DELETE /subscriptions/v1/card/{subscriptionId}`	Cancela la suscripción de forma permanente

Flujo de preautorización

Para suscripciones que requieren reservar fondos antes de la captura:

Autoriza

POST /subscriptions/v1/card/{subscriptionId}/authorize: reserva los fondos sin cobrar. Devuelve un ticketNumber.

Captura

POST /subscriptions/v1/card/{subscriptionId}/capture: captura el monto reservado. Envía el ticketNumber de la autorización.

Ejemplo de respuesta (completa)

{
  "details": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 99.90,
      "ice": 0,
      "iva": 0,
      "currency": "PEN"
    },
    "approvalCode": "000000",
    "approvedTransactionAmount": 99.90,
    "binInfo": {
      "bindCard": "445652",
      "cardCountry": "Peru",
      "lastFourDigits": "9860",
      "type": "credit"
    },
    "merchantName": "Mi Comercio Perú",
    "paymentBrand": "Visa",
    "responseCode": "000",
    "responseText": "Transacción aprobada",
    "transactionStatus": "APPROVAL",
    "transactionType": "SALE",
    "maskedCreditCard": "445652XXXXXX9860"
  },
  "ticketNumber": "028590538321035813"
}

Network Tokens (BETA)

Perú admite tokenizar las tarjetas de suscripción usando tarjetas con network token (tokens provisionados por Visa o Mastercard a través de wallets digitales como Apple Pay).

Cuando solicites un token de suscripción (POST /subscriptions/v1/card/tokens), envía isNetworkToken: true e incluye el objeto networkToken:

Campo	Descripción
`deviceType`	Tipo de dispositivo desde el que se origina la transacción tokenizada
`requestorId`	ID único que la red de tarjetas asigna al solicitante del token
`source`	Origen del token
`walletId`	Identificador de la wallet digital: `"01"` para Apple Pay, `"04"` para otras wallets
`authenticationLevel`	Nivel de autenticación aplicado durante el provisionamiento del token
`mvv`	Merchant Verification Value de 10 dígitos (solo transacciones Visa)

⚠️ BETA: Esta funcionalidad está disponible en Perú. Contacta a tu account manager de Kushki antes de activarla.

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de suscripción

Tokeniza una tarjeta para uso recurrente. Devuelve un token de un solo uso para crear la suscripción.

Crear una suscripción

Registra la tarjeta y configura el plan: periodicidad, monto, fecha de inicio y datos de contacto.

Cobrar una suscripción

Dispara un cargo on-demand sobre una suscripción. También se usa para cargos diferidos.

Consultar una suscripción

Obtén la configuración completa y los detalles de la tarjeta de una suscripción existente.

Actualizar la tarjeta

Reemplaza la tarjeta registrada por un nuevo token, por ejemplo tras el vencimiento de la tarjeta o un cargo fallido.

Actualizar una suscripción

Modifica el monto, la periodicidad o el nombre del plan de una suscripción existente.

Agregar un cargo temporal

Aplica un cargo o descuento extra por una sola vez en el siguiente ciclo de facturación, sin modificar el plan base.

Cancelar una suscripción

Cancela una suscripción de forma permanente. El cliente no volverá a ser cobrado.

Autorizar (preautorización)

Reserva fondos en la tarjeta de la suscripción sin capturarlos de inmediato.

Capturar

Captura un monto previamente autorizado en una suscripción.

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

Pagos One-Click y Programados

Dos modos de cobro#

Flujo#

Periodicidades#

Tipos de documento#

Cargos diferidos en suscripciones#

Gestión de suscripciones#

Flujo de preautorización#

Ejemplo de respuesta (completa)#

Network Tokens (BETA)#

Autenticación#

Uso de la API#

Endpoints disponibles#

Dos modos de cobro

Flujo

Periodicidades

Tipos de documento

Cargos diferidos en suscripciones

Gestión de suscripciones

Flujo de preautorización

Ejemplo de respuesta (completa)

Network Tokens (BETA)

Autenticación

Uso de la API

Endpoints disponibles