Suscripciones externas a Kushki

04 abril 2025

Cobra con Kushki y administra tus suscripciones de forma externa

Tipos de suscripciones

Con Kushki, tienes 2 opciones para ejecutar cobros de subscripciones creadas externamente:

Transacciones recurrentes sin CVV (con motor externo de suscripciones): ideal para orquestadores de pagos, en este la tokenización de la tarjeta es 100% de tu lado y Kushki se encarga exclusivamente de cursar los cobros.
Transacciones recurrentes con motor externo de suscripciones: utilizas tu propio motor de subscripciones y cursas una transacción inicial en Kushki con la información completa de la tarjeta y luego ejecutas los cobros posteriores sin CVV.

1. Transacciones sin cvv (con motor externo de suscripciones)

Kushki, a través de su adquirencia, permite procesar este tipo de pagos bajo demanda con credenciales tokenizadas fuera de su plataforma (por ejemplo, por un orquestador o motor externo de suscripciones). Para ello, es obligatorio que el comercio cuente con certificación PCI DSS y que gestione correctamente la seguridad, almacenamiento y uso del token de tarjeta.

La aceptación de estas transacciones depende enteramente de la lógica de riesgo y políticas del emisor.

Condiciones de uso

Para que una transacción sea enviada al emisor como un pago recurrente externo a Kushki, es indispensable que no incluya ningún parámetro relacionado con:

Diferidos (como número de cuotas o tipo de diferido),
3DS (autenticación reforzada),
CVV, ni
Criptogramas de seguridad (como los generados por wallets).

Cualquier transacción que contenga uno o más de estos elementos será procesada como un pago único, y así se reportará al emisor, lo que podría afectar la tasa de aprobación.

Aplica en	Disponible	Implementación
Colombia 🇨🇴 México 🇲🇽 Chile 🇨🇱 Perú 🇵🇪	☑ Adquirente ☐ Agregador	API

NOTA: Es requerido validar si este servicio está disponible para tu comercio y activarlo bajo demanda antes de poder usarlo.

Para procesar pagos con un motor de recurrencia externo y omitiendo el envío del cvv es necesario realizar los siguientes pasos:

1. Solicita a Kushki la activación del servicio

Comúnicate con tu ejecutivo de cuenta para solicitar la activación del servicio de aceptación de subscripciones externas, de forma tal que puedas procesar con Kushki los cobros omitiendo el cvv.

2. Solicita un token para cargo con tarjeta, omitiendo el CVV

Para generar un token sin cvv únicamente omitelo en la solicitud. Recuerda que es necesario activar este servicio primero antes de usarlo de lo contrario regresará un error K015 Transacción no permitida sin ccv2.

{
   "card": {
       "name": "John Doe",
       "number": "5451951574925480",
       "expiryMonth": "05",
       "expiryYear": "25"
   },
   "totalAmount": 50,
   "currency": "PEN"
}

3. Realiza el cargo

Para que un cargo se tome como recurrente es necesario enviar el campo externalSubscriptionID con el id de la suscripción de tu motor externo con una longitud igual o menor a 20 caracteres alfanuméricos, de esta forma Kushki identificará que corresponde a una subscripción administrada por un motor externo. Este parámetro lo envías al realizar el charge

{
   "token": "{{token}}",
   "amount": {
       "subtotalIva": 0,
       "subtotalIva0": 50,
       "ice": 0,
       "iva": 0,
       "currency": "PEN",
       "extraTaxes": {
           "iac": 0,
           "tasaAeroportuaria": 0,
           "agenciaDeViaje": 0
       }
   },
   "metadata": {
       "contractID": "157AB"
   },
   "contactDetails": {
       "documentType": "PAS",
       "documentNumber": "1234567890",
       "email": "user@example.com",
       "firstName": "John",
       "lastName": "Doe",
       "phoneNumber": "+513912345678"
   },
   "orderDetails": {
       "siteDomain": "example.com",
       "shippingDetails": {
           "name": "John Doe",
           "phone": "+513912345678",
           "address": "Av. Simón Bolivar 1515",
           "city": "Lima",
           "region": "Pueblo Libre",
           "country": "Perú",
           "zipcode": "15084"
       },
       "billingDetails": {
           "name": "John Doe",
           "phone": "+593912345678",
           "address": "Av. Simón Bolivar 1515",
           "city": "Lima",
           "region": "Pueblo Libre",
           "country": "Perú",
           "zipCode": "15084"
       }
   },
   "productDetails": {
       "product": [
           {
               "id": "198952AB",
               "title": "eBook Digital Services",
               "price": 30,
               "sku": "10101042",
               "quantity": 1
           },
           {
               "id": "198953AB",
               "title": "eBook Virtual Selling",
               "price": 20,
               "sku": "004834GQ",
               "quantity": 1
           }
       ]
   },
   "fullResponse": "v2",
   "externalSubscriptionID": "SUB1228930920"
}

2. Transacciones recurrentes con motor externo de suscripciones

En este modelo, administras las suscripciones con tu motor de elección y ejecutas los cobros con Kushki indicándonos si se trata de una recurrencia inicial o la ejecución del cobro de una recurrencia subsecuente. Para implementar esta opción debes ser PCI compliance debido al manejo de información de datos sensibles de tarjeta.

Aplica en	Disponible	Implementación
Colombia 🇨🇴 México 🇲🇽 Chile 🇨🇱 Perú 🇵🇪	☑ Adquiriencia ☐ Agregador	API

Para procesar pagos recurrentes sin el envío del cvv es necesario realizar los siguientes pasos:

Paso 1. Solicita a Kushki la activación del servicio

Comúnicate con tu ejecutivo para solicitar la activación del servicio de aceptación de subscripciones externas, de forma tal que puedas procesar con Kushki los cobros omitiendo el cvv.

Paso 2. Recurrencia inicial

Si es la primera vez ejecutando la recurrencia inicial (initialRecurrence), es necesario enviar todos los datos transaccionales de la tarjeta, incluyendo el cvv y el campo transactionMode con el valor de initialRecurrence para generar un token el cuál podrá ser usado posteriormente para realizar un cargo.

   "card": {
       "name": "John Doe",
       "number": "5451951574925480",
       "expiryMonth": "05",
       "expiryYear": "25",
       "cvv": "123"
   },
   "totalAmount": 50,
   "currency": "PEN",
   "transactionMode": "initialRecurrence"
}

Paso 3. Realiza un cargo inicial

Después de generar un token, puedes realizar un cargo. Para ello, envía la información requerida.

{
 "token": "{{token}}",
 "amount": {
   "subtotalIva": 0,
   "subtotalIva0": 50,
   "ice": 0,
   "iva": 0,
   "currency": "PEN",
   "extraTaxes": {
       "iac": 0,
       "tasaAeroportuaria": 0,
       "agenciaDeViaje": 0
   }
 },
 "metadata": {
   "contractID": "157AB"
 },
 "contactDetails": {
   "documentType": "PAS",
   "documentNumber": "1234567890",
   "email": "user@example.com",
   "firstName": "John",
   "lastName": "Doe",
   "phoneNumber": "+513912345678"
 },
 "orderDetails": {
   "siteDomain": "example.com",
   "shippingDetails": {
     "name": "John Doe",
     "phone": "+513912345678",
     "address": "Av. Simón Bolivar 1515",
     "city": "Lima",
     "region": "Pueblo Libre",
     "country": "Perú",
     "zipcode": "15084"
   },
   "billingDetails": {
     "name": "John Doe",
     "phone": "+593912345678",
     "address": "Av. Simón Bolivar 1515",
     "city": "Lima",
     "region": "Pueblo Libre",
     "country": "Perú",
     "zipCode": "15084"
   }
 },
 "productDetails": {
   "product": [
     {
       "id": "198952AB",
       "title": "eBook Digital Services",
       "price": 30,
       "sku": "10101042",
       "quantity": 1
     },
     {
       "id": "198953AB",
       "title": "eBook Virtual Selling",
       "price": 20,
       "sku": "004834GQ",
       "quantity": 1
     }
   ]
 },
 "fullResponse": "v2"
}

Paso 4. Recurrencia subsecuente

Si requieres procesar un cobro omitiendo el cvv, es requerido haber ejecutado una recurrencia inicial (paso 1). Debes enviar la información transaccional de la tarjeta, omitiendo el cvv de la tarjeta y enviando el campo transactionMode con el valor de subsequentRecurrence para generar un token el cuál podrá ser usado posteriormente para realizar un cargo.

{
   "card": {
       "name": "John Doe",
       "number": "5451951574925480",
       "expiryMonth": "05",
       "expiryYear": "25"
   },
   "totalAmount": 50,
   "currency": "PEN",
   "transactionMode": "subsequentRecurrence"
}

Paso 5. Realiza un cargo subsecuente

Para poder realizar un cargo sin cvv es necesario enviar el campo adicional initialRecurrenceReference con el valor del transactionReference obtenido en la respuesta del paso 3 al realizar el charge.

{
 "token": "{{token}}",
 "amount": {
   "subtotalIva": 0,
   "subtotalIva0": 50,
   "ice": 0,
   "iva": 0,
   "currency": "PEN",
   "extraTaxes": {
       "iac": 0,
       "tasaAeroportuaria": 0,
       "agenciaDeViaje": 0
   }
 },
 "metadata": {
   "contractID": "157AB"
 },
 "contactDetails": {
   "documentType": "PAS",
   "documentNumber": "1234567890",
   "email": "user@example.com",
   "firstName": "John",
   "lastName": "Doe",
   "phoneNumber": "+513912345678"
 },
 "orderDetails": {
   "siteDomain": "example.com",
   "shippingDetails": {
     "name": "John Doe",
     "phone": "+513912345678",
     "address": "Av. Simón Bolivar 1515",
     "city": "Lima",
     "region": "Pueblo Libre",
     "country": "Perú",
     "zipcode": "15084"
   },
   "billingDetails": {
     "name": "John Doe",
     "phone": "+593912345678",
     "address": "Av. Simón Bolivar 1515",
     "city": "Lima",
     "region": "Pueblo Libre",
     "country": "Perú",
     "zipCode": "15084"
   }
 },
 "productDetails": {
   "product": [
     {
       "id": "198952AB",
       "title": "eBook Digital Services",
       "price": 30,
       "sku": "10101042",
       "quantity": 1
     },
     {
       "id": "198953AB",
       "title": "eBook Virtual Selling",
       "price": 20,
       "sku": "004834GQ",
       "quantity": 1
     }
   ]
 },
 "fullResponse": "v2",
 "initialRecurrenceReference": "6c21b4b4-d78d-4e50-8f89-b9f81b0ff509"
}