Cobra con Kushki y administra tus suscripciones de forma externa

Tipos de suscripciones

Con Kushki, tienes 2 opciones para ejecutar cobros bajo demanda de subscripciones creadas por fuera de Kushki:

Transacciones 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 bajo demanda.

Transacciones COF 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.

2.1. Transacciones COF de Reserva y Captura (PreAuth): Similar a la opción anterior, pero en lugar de cobrar inmediatamente, realizas una pre-autorización (reserva de fondos) inicial y subsecuente, permitiendo capturar el dinero posteriormente (ideal para validación de stock o envíos).

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

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 suscripciones 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 suscripción, omite el parámetro externalSubscriptionID

2. Transacciones COF (con motor externo de subscripciones)

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ú 🇵🇪	☑ Adquirente ☐ Agregador	API

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.

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.

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

Es importante que guardes el transactionReference en caso de una transacción aprobada ya que será requerido para realizar posteriores cargos sin cvv. Adicionalmente, sabrás que la marca (Visa/Mastercard) reconoció la transacción como COF porque recibirás el objeto network en la respuesta.

{
  "details": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 2000,
      "iva": 0,
      "ice": 0,
      "currency": "CLP"
    },
    "approvalCode": "123456",
    "approvedTransactionAmount": 25000,
    "binInfo": {
      "bank": "BANCO DEL PACIFICO, S.A.",
      "binCard": "511054",
      "cardCountry": "Ecuador",
      "lastFourDigits": "6094",
      "type": "credit"
    },
    "cardHolderName": "USER",
    "created": 1768585326000,
    "merchantId": "20000000107129060000",
    "merchantName": "DESCENTRALIZADA TEST",
    "messageFields": {
      "f15": "1234",
      "f38": "123456",
      "f39": "00",
      "f63": "123123456"
    },
    "paymentBrand": "Mastercard",
    "processorBankName": "Kushki Operadora S.A.",
    "recap": "601617108519",
    "requestAmount": 25000,
    "responseCode": "000",
    "responseText": "Approved or completed successfully.",
    "transactionId": "821768585326341640960",
    "transactionReference": "89d1f9b2-360e-48b2-9355-87e19afb18be",
    "transactionStatus": "APPROVAL",
    "transactionType": "SALE",
    "network": {
      "scheme": "mastercard",
      "transactionIdentifier": "1231234561234"
    }
  },
  "ticketNumber": "821768589326410330",
  "transactionReference": "89d1f9b2-360e-48b2-9355-87e19afb18be"
}

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

2.1 Transacciones COF de Reserva (Pre-autorizaciones)

Producto en versión beta 🔐👨‍

Estamos trabajando en nuestra versión beta. ¡Manténte atento a su lanzamiento oficial! También puedes contactar a tu gerente de cuenta para más información.

Además de los cargos directos, la funcionalidad de Card on File (COF) soporta el flujo de reserva de fondos (Pre-autorización) y confirmación posterior (Captura). Esto es ideal para modelos de suscripción donde el monto final puede variar o requiere confirmación de stock/envío.

Puedes implementar este flujo de dos maneras:

Con Tokenización: Utilizando tokens temporales de Kushki.

Sin Tokenización (Directo): Enviando los datos de tarjeta directamente (Requiere PCI Compliance alto).

Escenario A: Pre-autorización con Token

Este flujo utiliza la tokenización estándar de Kushki para asegurar los datos sensibles de la tarjeta.

Paso 1. Genera el Token Inicial

Para la primera transacción, genera un token enviando la tarjeta completa y estableciendo el modo como recurrencia inicial.

Endpoint: /card/v1/tokens

Campo clave: "transactionMode": initialRecurrence

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

Paso 2. Ejecuta la Pre-autorización Inicial

Utiliza el token generado para solicitar la reserva de fondos usando el servicio de preautorización /card/v1/preAuthorization.

En la respuesta exitosa, recibirás el campo transactionReference. Debes almacenar este valor en tu base de datos asociado al usuario/suscripción. Este será el identificador obligatorio para realizar cobros futuros. Adicionalmente, sabrás que la marca (Visa/Mastercard) reconoció la transacción como COF porque recibirás el objeto network en la respuesta.

{
  "value": {
    "details": {
      "amount": {
        "subtotalIva": 0,
        "subtotalIva0": 2000,
        "iva": 0,
        "ice": 0,
        "currency": "CLP"
      },
      "approvalCode": "123456",
      "approvedTransactionAmount": 25000,
      "binInfo": {
        "bank": "BANCO DEL PACIFICO, S.A.",
        "binCard": "511054",
        "cardCountry": "Ecuador",
        "lastFourDigits": "6094",
        "type": "credit"
      },
      "cardHolderName": "USER",
      "created": 1768585326000,
      "merchantId": "20000000107129060000",
      "merchantName": "DESCENTRALIZADA TEST",
      "messageFields": {
        "f15": "1234",
        "f38": "123456",
        "f39": "00",
        "f63": "123123456"
      },
      "paymentBrand": "Mastercard",
      "processorBankName": "Kushki Operadora S.A.",
      "recap": "601617108519",
      "requestAmount": 25000,
      "responseCode": "000",
      "responseText": "Approved or completed successfully.",
      "transactionId": "821768585326341640960",
      "transactionReference": "89d1f9b2-360e-48b2-9355-87e19afb18be",
      "transactionStatus": "APPROVAL",
      "transactionType": "SALE",
      "network": {
        "scheme": "mastercard",
        "transactionIdentifier": "1231234561234"
      }
    },
    "ticketNumber": "821768589326410330",
    "transactionReference": "89d1f9b2-360e-48b2-9355-87e19afb18be"
  }
}

Paso 3. Recurrencia Subsecuente (Futura)

Para las siguientes renovaciones (mes 2, mes 3, etc.):

Genera un nuevo token omitiendo el cvv, pero esta vez indica que es una recurrencia subsecuente:

"transactionMode": subsequentRecurrence

{
  "card": {
    "name": "John Doe",
    "number": "4444441181077714",
    "expiryMonth": "08",
    "expiryYear": "28"
  },
  "totalAmount": 10,
  "currency": "USD",
  "transactionMode": "subsequentRecurrence"
}

Ejecuta la Pre-autorización enviando el transactionReference que guardaste en el Paso 2 dentro del campo initialRecurrenceReference.

// Request de Pre-autorización Subsecuente
{
  "token": "nuev_token_generado_subsecuente",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 39,
    "currency": "PEN"
  },
  "fullResponse": "v2",
  "initialRecurrenceReference": "transactionReference_guardado_"
}

Escenario B: Pre-autorización Sin Token (Integración Directa)

Si tu integración maneja los datos de tarjeta directamente (Server-to-Server), el flujo se simplifica al no requerir el paso intermedio de tokenización, pero mantienes la lógica de la cadena de confianza.

Paso 1. Pre-autorización Inicial Directa

Envía los datos de la tarjeta junto con el indicador de inicio de recurrencia. En esta preautorización inicial deberás enviar el cvv.

Endpoint: /card/v2/preAuthorization

Campo clave: "transactionMode": initialRecurrence

{
  "card": {
    "name": "John Doe",
    "number": "4259078012341233",
    "expiryMonth": "12",
    "expiryYear": "30",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 4000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN"
  },
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "transactionMode": "initialRecurrence",
  "fullResponse": "v2"
}

Al igual que en el flujo con token, sabrás que la transacción se registró correctamente bajo el modelo COF porque la respuesta incluirá el objeto network. Recuerda guardar el transactionReference de esta respuesta.

{
  "details": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 4000,
      "ice": 0,
      "iva": 0,
      "currency": "MXN",
      "isDeferred": false
    },
    "approvalCode": "123456",
    "approvedTransactionAmount": 4000,
    "binInfo": {
      "bank": "WELLSFARGO",
      "binCard": "425907",
      "cardCountry": "United States of America",
      "lastFourDigits": "1233",
      "type": "credit"
    },
    "cardHolderName": "John Doe",
    "created": 1712159361000,
    "merchantId": "20000000101835540000",
    "merchantName": "CENTRALIZADA NUEVA PRUEBA GOB",
    "messageFields": {
      "f38": "123456",
      "f39": "00"
    },
    "paymentBrand": "Visa",
    "processorBankName": "Kushki",
    "recap": "409415159483",
    "requestAmount": 4000,
    "responseCode": "000",
    "responseText": "Approval and completed successfully Accepted and processed.",
    "transactionId": "821712159361453407367",
    "transactionReference": "ba48f90b-43ef-4cff-b842-7bc34c41f78e",
    "transactionStatus": "APPROVAL",
    "transactionType": "PREAUTHORIZATION",
          "network": {
        "scheme": "mastercard",
        "transactionIdentifier": "1231234561234"
      }
  },
  "ticketNumber": "821712159361453410",
  "transactionReference": "ba48f90b-43ef-4cff-b842-7bc34c41f78e"
}

Paso 2. Pre-autorización Subsecuente Directa

Para los cobros futuros, envía nuevamente la petición de pre-autorización indicando que es subsecuente y adjuntando la referencia de la preautorización inicial en el campo initialRecurrenceReference.

Campo clave 1: "transactionMode": subsequentRecurrence

Campo clave 2: "initialRecurrenceReference": transactionReference_guardado

{
  "card": {
    "name": "John Doe",
    "number": "4259078012341233",
    "expiryMonth": "12",
    "expiryYear": "30",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 4000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN",
    "isDeferred": false
  },
  "transactionMode": "subsequentRecurrence",
  "initialRecurrenceReference": "c76e2057-fe15-4f90-990c-5d35d130f018",
  "fullResponse": "v2"
}

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 COF (con motor externo de subscripciones)#

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

Paso 2. Recurrencia inicial#

Paso 3. Realiza un cargo inicial#

Paso 4. Recurrencia subsecuente#

Paso 5. Realiza un cargo subsecuente#

2.1 Transacciones COF de Reserva (Pre-autorizaciones)#

Escenario A: Pre-autorización con Token#

Paso 1. Genera el Token Inicial#

Paso 2. Ejecuta la Pre-autorización Inicial#

Paso 3. Recurrencia Subsecuente (Futura)#

Escenario B: Pre-autorización Sin Token (Integración Directa)#

Paso 1. Pre-autorización Inicial Directa#

Paso 2. Pre-autorización Subsecuente Directa#

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 COF (con motor externo de subscripciones)

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

Paso 2. Recurrencia inicial

Paso 3. Realiza un cargo inicial

Paso 4. Recurrencia subsecuente

Paso 5. Realiza un cargo subsecuente

2.1 Transacciones COF de Reserva (Pre-autorizaciones)

Escenario A: Pre-autorización con Token

Paso 1. Genera el Token Inicial

Paso 2. Ejecuta la Pre-autorización Inicial

Paso 3. Recurrencia Subsecuente (Futura)

Escenario B: Pre-autorización Sin Token (Integración Directa)

Paso 1. Pre-autorización Inicial Directa

Paso 2. Pre-autorización Subsecuente Directa