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.

Importante

Debido a nuestras políticas de riesgo, la implementación de estas opciones requiere una evaluación previa del equipo de Kushki. Comúnicate con tu ejecutivo comercial o ingeniero de preventa para evaluar la factibilidad.

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

Importante

Debido a nuestras políticas de riesgo, la implementación de esta forma de procesamiento requiere una evaluación previa del equipo de Kushki. Comúnicate con tu ejecutivo comercial o ingeniero de preventa para evaluar la viabilidad.

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": "30"
   },
   "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"
}

Si por el contrario, deseas ejecutar un cargo no atado a una subscripción, omite el parámetro externalSubscriptionID

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

Importante

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": "30",
       "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.

Importante

Es importante que guardes el transactionReference en caso de una transacción aprobada ya que será requerido para realizar posteriores cargos sin cvv.

{
 "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"
}

Valida la tarjeta sin completar el cobro (validateOnly)

Si en lugar de capturar el monto completo en la recurrencia inicial solo necesitas confirmar que la tarjeta es válida, agrega el campo validateOnly en la raíz del charge del paso anterior. Kushki procesa un micro-cobro configurable por comercio y lo anula automáticamente; no se retiene ningún monto en la tarjeta del titular.

Importante

validateOnly solo aplica al cargo de la recurrencia inicial (paso 3). No lo envíes en cargos de recurrencia subsecuente (paso 5).

{
 "token": "{{token}}",
 "validateOnly": true,
 "amount": {
   "subtotalIva": 0,
   "subtotalIva0": 50,
   "ice": 0,
   "iva": 0,
   "currency": "MXN",
   "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"
}

A tener en cuenta

El campo validateOnly debe enviarse exactamente en camelCase. Si lo envías como validateonly (minúsculas), el cargo se procesa como un cargo normal y la anulación automática del micro-cobro no se activa.

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": "30"
   },
   "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"
}

Card-on-file con consentimiento explícito del titular (storeCredential)

Como alternativa al flujo de los pasos 2 a 5, puedes usar storeCredential para que Kushki registre explícitamente el consentimiento del titular para almacenar su tarjeta y usarla en cobros futuros. La diferencia clave frente al flujo anterior es que el initialRecurrenceReference se envía en el token de la recurrencia subsecuente, y no en el charge.

Recurrencia inicial con storeCredential

Envía storeCredential: true junto con transactionMode: "initialRecurrence" al generar el token.

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

Realiza el cargo inicial con este token como en el paso 3 y guarda el transactionReference de la respuesta.

Recurrencia subsecuente con storeCredential

Envía storeCredential: true, transactionMode: "subsequentRecurrence" y initialRecurrenceReference con el transactionReference guardado, esta vez dentro de la solicitud del token — no en el charge.

Importante

En este caso no es necesario enviar el objeto card — Kushki usa la tarjeta ya registrada mediante initialRecurrenceReference.

{
   "totalAmount": 50,
   "currency": "PEN",
   "transactionMode": "subsequentRecurrence",
   "storeCredential": true,
   "initialRecurrenceReference": "6c21b4b4-d78d-4e50-8f89-b9f81b0ff509"
}

Con este token, realiza el cargo subsecuente de forma habitual, sin necesidad de incluir initialRecurrenceReference en el charge.

A tener en cuenta

storeCredential debe enviarse exactamente en camelCase. Si el token inicial se envía con la grafía incorrecta (storecredential), un token de recurrencia subsecuente que lo referencie fallará con el error {"code": "K105", "message": "Decrypt error"}.

Suscripciones externas a Kushki

Tipos de suscripciones#

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

Condiciones de uso#

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

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

3. Realiza el cargo#

2. Transacciones recurrentes con motor externo de suscripciones#

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

Paso 2. Recurrencia inicial#

Paso 3. Realiza un cargo inicial#

Valida la tarjeta sin completar el cobro (validateOnly)#

Paso 4. Recurrencia subsecuente#

Paso 5. Realiza un cargo subsecuente#

Card-on-file con consentimiento explícito del titular (storeCredential)#

Recurrencia inicial con storeCredential#

Recurrencia subsecuente con storeCredential#

Tipos de suscripciones

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

Condiciones de uso

1. Solicita a Kushki la activación del servicio

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

3. Realiza el cargo

2. Transacciones recurrentes con motor externo de suscripciones

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

Paso 2. Recurrencia inicial

Paso 3. Realiza un cargo inicial

Valida la tarjeta sin completar el cobro (validateOnly)

Paso 4. Recurrencia subsecuente

Paso 5. Realiza un cargo subsecuente

Card-on-file con consentimiento explícito del titular (storeCredential)

Recurrencia inicial con storeCredential

Recurrencia subsecuente con storeCredential