Manage your subscriptions externally and charge with Kushki

Types of subscriptions

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

Recurring 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 on-demand payments.

Recurring 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 charges without CVV.

Important

Due to our risk policies, the above mentioned options require a prior evaluation by the Kushki team. Please contact your account executive or pre-sales engineer to assess feasibility.

1. CVV-less Transactions (with an external subscription engine)

Kushki, through its acquiring services, allows you to process on-demand payments using card credentials tokenized outside of its platform (for example, by an orchestrator or external subscription engine). To use this flow, the merchant must have valid PCI DSS certification and must properly manage the security, storage, and usage of the card token.

The acceptance of these transactions fully depends on the issuer's risk logic and policies.

Usage Conditions

Important

Due to our risk policies, implementing this form of processing requires a prior evaluation by the Kushki team. Please contact your account executive or pre-sales engineer to assess feasibility.

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

If, on the other hand, you want to execute a charge not tied to a subscription, omit the externalSubscriptionIDparameter.

2. Recurring 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 🇨🇱 Ecuador 🇪🇨 Perú 🇵🇪	☑Acquirer ☑ Aggregator	API

Important

Due to our risk policies, implementing this form of processing requires a prior evaluation by the Kushki team. Please contact your account executive or pre-sales engineer to assess feasibility.

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

Important

It's important to save the transactionReferencein the case of an approved transaction, as it will be required for subsequent charges without 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"
}

Validate the card without completing the charge (validateOnly)

If instead of capturing the full amount on the initial recurrence you only need to confirm the card is valid, add the validateOnly field at the root of the charge from the previous step. Kushki processes a merchant-configurable micro-charge and automatically voids it; no funds are retained on the cardholder's card.

Important

validateOnly only applies to the initial-recurrence charge (step 3). Do not send it on subsequent-recurrence charges (step 5).

{
 "token": "{{token}}",
 "validateOnly": true,
 "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"
}

Keep in mind

The validateOnly field must be sent in exact camelCase. If you send it as validateonly (lowercase), the charge is processed as a normal charge and the automatic void of the micro-charge is not triggered.

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

As an alternative to the flow in steps 2 through 5, you can use storeCredential so Kushki explicitly records the cardholder's consent to store their card and use it for future charges. The key difference from the flow above is that initialRecurrenceReference is sent in the token, not in the charge, for the subsequent recurrence.

Initial recurrence with storeCredential

Send storeCredential: true together with transactionMode: "initialRecurrence" when generating the token.

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

Run the initial charge with this token as in step 3, and save the transactionReference from the response.

Subsequent recurrence with storeCredential

Send storeCredential: true, transactionMode: "subsequentRecurrence", and initialRecurrenceReference with the saved transactionReference — this time inside the token request, not in the charge.

Important

In this case, the card object is not required — Kushki uses the card already on file via initialRecurrenceReference.

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

With this token, run the subsequent charge as usual, without including initialRecurrenceReference in the charge.

Keep in mind

storeCredential must be sent in exact camelCase. If the initial token is sent with incorrect casing (storecredential), a subsequent-recurrence token referencing it will fail with {"code": "K105", "message": "Decrypt error"}.

External subscriptions to Kushki

Types of subscriptions#

1. CVV-less Transactions (with an external subscription engine)#

Usage Conditions#

1. Request service activation from Kushki#

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

3. Execute a charge#

2. Recurring transactions with external subscription engine#

Step 1. Request service activation from Kushki#

Step 2. Initial recurrence#

Step 3. Make an initial charge#

Validate the card without completing the charge (validateOnly)#

Step 4. Subsequent recurrence#

Step 5. Perform a subsequent charge#

Card-on-file with explicit cardholder consent (storeCredential)#

Initial recurrence with storeCredential#

Subsequent recurrence with storeCredential#

Types of subscriptions

1. CVV-less Transactions (with an external subscription engine)

Usage Conditions

1. Request service activation from Kushki

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

3. Execute a charge

2. Recurring transactions with external subscription engine

Step 1. Request service activation from Kushki

Step 2. Initial recurrence

Step 3. Make an initial charge

Validate the card without completing the charge (validateOnly)

Step 4. Subsequent recurrence

Step 5. Perform a subsequent charge

Card-on-file with explicit cardholder consent (storeCredential)

Initial recurrence with storeCredential

Subsequent recurrence with storeCredential