External subscriptions to Kushki

December 19, 2023

Manage your subscriptions externally and charge with Kushki

Types of subscriptions

With Kushki, you have 2 options to manage your subscriptions externally:

COF transactions without CVV (with external subscription engine): ideal for payment orchestrators, in this case the tokenization of the card is 100% on your side and Kushki is exclusively in charge of processing the payments.
COF transactions with external subscription engine: use your own subscription engine and submit an initial transaction in Kushki with full card information and then execute subsequent payments without CVV.

1.Transactions COF without cvv with an external subscription engine

Recurring transactions without CVV (with external subscription engine

This solution, ideal for orchestrators (strictly requires PCI compliance), allows you to manage card tokenization with your own subscription engine and only process charges with Kushki while omitting the cvv.

Applies in	Available	Implementation
Colombia 🇨🇴 México 🇲🇽 Chile 🇨🇱 Perú 🇵🇪	☑Acquirer ☐ Aggregator	API

NOTE: It is required to validate if this service is available for your commerce and activate it on demand before being able to use it.

To process payments with an external recurrence engine and omitting the cvv, you need to follow these steps:

1. Request service activation from Kushki

Contact your account executive to request the activation of the external subscription acceptance service so that you can process charges with Kushki while omitting the cvv.

2. Request a token for card charge, omitting the cvv

To generate a token without cvv, simply omit it in the request. Remember that it is necessary to activate this service first before using it; otherwise, it will return a K015 error, Transaction not allowed without ccv2.

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

3. Execute a charge

For a charge to be considered recurrent, it is necessary to send the externalSubscriptionID field with the ID of the subscription from your external engine, with a length equal to or less than 20 alphanumeric characters. This way, Kushki will identify that it corresponds to a subscription managed by an external engine. You can do this when executing one-time 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. COF transactions (With external subscription engine)

In this model, you manage the subscriptions with your engine of choice and execute the charges with Kushki indicating whether it is an initial recurrence or the execution of the charge for a subsequent recurrence. To implement this option you must be PCI compliant due to the handling of sensitive card data.

Applies in	Available	Implementation
Colombia 🇨🇴 México 🇲🇽 Chile 🇨🇱 Perú 🇵🇪	☑Acquirer ☐ Aggregator	API

To process one-click or recurring payments without sending the cvv, you need to follow these steps:

Step 1. Request service activation from Kushki

Contact your account executive to request the activation of the external subscription acceptance service so that you can process charges with Kushki while omitting the cvv.

Step 2. Initial recurrence

If it is the first time executing the initial recurrence (initialRecurrence), it is necessary to send all the transactional data of the card, including the cvv and the transactionMode field with the value of initialRecurrence to generate a token which can be used later to make a charge.

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

Step 3. Make an initial charge

After generating a token, you can make a charge. To do this, send the required information.

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

Step 4. Subsequent recurrence

If you need to process a charge omitting the cvv, it is required to have executed an initial recurrence (step 1). You must send the card’s transactional information, omitting the card’s cvv and sending the transactionMode field with the value of subsequentRecurrence to generate a token which can be used later to make a charge.

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

Step 5. Perform a subsequent charge

In order to charge without cvv it is necessary to send the additional field initialRecurrenceReference with the value of the transactionReference obtained in the response of step 3 when performing the 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"
}