Manage your subscriptions externally and charge with Kushki

Types of subscriptions

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

Transactions without CVV (with external subscription engine): Ideal for payment orchestrators; in this scenario, card tokenization is handled 100% on your side, and Kushki is exclusively responsible for processing on-demand charges.

COF transactions with external subscription engine: You use your own subscription engine and process an initial transaction in Kushki with full card information, and then execute subsequent charges without a CVV.

COF Reserve and Capture Transactions (PreAuth): Similar to the previous option, but instead of charging immediately, you perform an initial and subsequent pre-authorization (funds reservation), allowing you to capture the funds later (ideal for stock validation or shipping).

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

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 merchant 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. 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

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

It is important to save the transactionReference for an approved transaction, as it will be required to perform subsequent charges without a CVV. Additionally, you will know that the card network (Visa/Mastercard) recognized the transaction as COF because you will receive the network object in the response.

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

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

2.1 Reserve Funds (Pre-authorization)

Product in beta version 🔐👨‍

We are working on our__ beta __version. Stay tuned for its official launch! You can also contact your account manager for more information.

In addition to direct charges, the Card on File (COF) functionality supports the funds reservation (Pre-authorization) and subsequent confirmation (Capture) flow. This is ideal for subscription models where the final amount may vary or requires stock/shipping confirmation.

You can implement this flow in two ways:

With Tokenization: Using Kushki temporary tokens.

Without Tokenization (Direct): Sending card data directly (Requires high PCI Compliance).

Scenario A: Pre-authorization with Token

This flow uses Kushki's standard tokenization to secure sensitive card data.

Step 1. Generate the Initial Token

For the first transaction, generate a token by sending the full card data and setting the mode as initial recurrence.

Endpoint: /card/v1/tokens

Key field: "transactionMode": initialRecurrence

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

Step 2. Execute the Initial Pre-authorization

Use the generated token to request funds reservation using the pre-authorization service /card/v1/preAuthorization.

In the successful response, you will receive the transactionReference field. You must store this value in your database associated with the user/subscription. This will be the mandatory identifier for performing future charges. Additionally, you will know that the card network (Visa/Mastercard) recognized the transaction as COF because you will receive the network object in the response.

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

Step 3. Subsequent Recurrence (Future)

For subsequent renewals (month 2, month 3, etc.):

Generate a new token omitting the CVV, but this time indicate that it is a subsequent recurrence:

"transactionMode": subsequentRecurrence

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

Execute the Pre-authorization sending the transactionReference you saved in Step 2 within the initialRecurrenceReference field.

// Subsequent Pre-authorization Request{
  "token": "nuev_token_generado_subsecuente",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 39,
    "currency": "PEN"
  },
  "fullResponse": "v2",
  "initialRecurrenceReference": "saved_transactionReference"
}

Scenario B: Pre-authorization without Token (Direct Integration)

If your integration handles card data directly (Server-to-Server), the flow is simplified by not requiring the intermediate tokenization step, but you maintain the chain of trust logic.

Step 1. Initial Direct Pre-authorization

Send the card data along with the initial recurrence indicator. In this initial pre-authorization, you must send the CVV.

Endpoint: /card/v2/preAuthorization

Key field: "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"
}

As in the token flow, you will know that the transaction was successfully registered under the COF model because the response will include the network object. Remember to save the transactionReference from this response.

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

Step 2. Subsequent Direct Pre-authorization

For future charges, send the pre-authorization request again indicating that it is subsequent and attaching the initial pre-authorization reference in the initialRecurrenceReference field.

Key field 1: "transactionMode": subsequentRecurrence

Key field 2: "initialRecurrenceReference": transactionReference

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

External subscriptions to Kushki

Types of subscriptions#

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

Usage Conditions#

Usage Conditions#

1. Request service activation from Kushki#

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

3. Execute a charge#

2. COF transactions (With external subscription engine)#

Step 1. Request service activation from Kushki#

Step 2. Initial recurrence#

Step 3. Make an initial charge#

Step 4. Subsequent recurrence#

Step 5. Perform a subsequent charge#

2.1 Reserve Funds (Pre-authorization)#

Scenario A: Pre-authorization with Token#

Step 1. Generate the Initial Token#

Step 2. Execute the Initial Pre-authorization#

Step 3. Subsequent Recurrence (Future)#

Scenario B: Pre-authorization without Token (Direct Integration)#

Step 1. Initial Direct Pre-authorization#

Step 2. Subsequent Direct Pre-authorization#

Types of subscriptions

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

Usage Conditions

Usage Conditions

1. Request service activation from Kushki

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

3. Execute a charge

2. COF transactions (With external subscription engine)

Step 1. Request service activation from Kushki

Step 2. Initial recurrence

Step 3. Make an initial charge

Step 4. Subsequent recurrence

Step 5. Perform a subsequent charge

2.1 Reserve Funds (Pre-authorization)

Scenario A: Pre-authorization with Token

Step 1. Generate the Initial Token

Step 2. Execute the Initial Pre-authorization

Step 3. Subsequent Recurrence (Future)

Scenario B: Pre-authorization without Token (Direct Integration)

Step 1. Initial Direct Pre-authorization

Step 2. Subsequent Direct Pre-authorization