Manage your Scheduled Charges

January 19, 2024

Update the data of a scheduled charge, apply discounts or cancel automatic charges

This functionality is available for the following models:

☑ Acquirer
☑ Aggregator

Kushki allows you to manage your customer’s existing subscriptions without the need of creating them every time. This will help you to keep the same subscription ID after changes are made. The most common actions are:

Obtain Subscription Data

You can check all the data available for a subscription that was already created so that you can show them on screen for your customers. You can also save the information we return in your databases. You don’t need to worry, because we will not give you any sensitive card data.

First, you must find the subscription ID whose data you need to check. Then, make a call to our subscription query endpoint from your back-end; don’t forget to include the subscription ID as path parameter.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'GET',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000', // Test environment 
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000"

payload = {}

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Replace this with your Private Key
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000');
$request->setRequestMethod('GET');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

According to the response you got, show on screen the information you requested, or save it in your database.

Update Subscription Data

When the recurring payment plan of your customers has changed, you may update data for a subscription that has been already created without the need of requesting again the card data.

These are the data that you can update:

Plan name
Execution schedule for charges (periodicity)
Contact data
Amount to charge
Date for charge execution (startDate)
Subscription cancellation date (endDate)
Logic for charge retries

First, you need to find the ID of the subscription you want to update. Then, make a call to our subscription update endpoint from your back end; don’t forget to include the subscription ID as a path parameter.

Make sure you submit only the information you need to change so that the rest of the subscription data are maintained. For example, if one of your customers with a Basic Plan for 10 USD monthly wants to upgrade to a Professional Plan for 35 USD monthly, you only need to submit the amount and the name of the new plan when calling to our endpoint.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'PATCH',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Configured in test mode
  headers: {'content-type': 'application/json'}
  body: {
    amount: {subtotalIva: 0, subtotalIva0: 35, ice: 0, iva: 0, currency: 'USD'},
    planName: 'Profesional'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = "{\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":35,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"planName\":\"Profesional\"}"

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Replace this with your Private Key
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"amount":{"subtotalIva":0,"subtotalIva0":35,"ice":0,"iva":0,"currency":"USD"},"planName": "Profesional"}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('PATCH');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

According to the response you get, redirect the user to a success or fail screen to inform the customer if the subscription was updated correctly or if an error occurred.

Update payment information for a scheduled charge

If for any reason you need to update the payment method for a subscription (for example, a card expired, the card was updated or replaced, insufficient balance, etc.) you can update the card details without changing the subscription information (frequency, amount, subscription details, etc.). Depending on the type of integration, it is necessary to send the new card data to obtain a token and subsequently send the token obtained to the endpoint [update recurring charge card data](https://api-docs.kushkipagos. com/docs/online-payments/one-click-and-scheduled-payments%2Foperations%2Fupdate-a-subscription-v-1-card-card).

Kushki.js integration (front end)

If you are getting the token from your front end with the Kushki.js library, follow the steps below:

Consumes the requestSubscriptionToken() method

In your Kushki.js implementation, you need to consume the requestSubscriptionToken() method available in the library, sending the required parameters.

var callback = function(response) {
  if(!response.code){
    console.log(response.token);
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
}

kushki.requestSubscriptionToken({
  card: {
    name: "Juan Guerra",
    number: "4544980425511225",
    cvc: "345",
    expiryMonth: "12",
    expiryYear: "28"
},
  currency: "USD"
}, callback); // Also you can set the function directly

If the request was successful, you will receive a response with the token as shown below

{ 
  "token": "90a9f2d93ba508c38971890454897fd4"
}

For more information, see the implementation of the requestSubscriptionToken method.

Update card details on a recurring charge

If the token generation was successful, you must consume the endpoint update recurring charge card data by sending the token obtained in the previous step and the subscriptionId with the id of the subscription to be updated.

For more information, see the endpoint implementation update recurring charge card data.

API integration (back end)

In your implementation using API, you need to consume the endpoint request a recurring charge token, sending the new card data.

For more information, see the endpoint implementation request a recurring charge token.

Update card details on a recurring charge

For more information, see the endpoint implementation update recurring charge card data.

Apply a temporary discount

Kushki allows you to offer discount periods for your customers. Once the discount period you established is over, we will automatically charge the card the original amount when the subscription was created.

First, you must find the ID of the subscription to which the discount will be applied. Then, make a call to our temporary discount endpoint for subscriptions from your back end; don’t forget to include the subscription ID as a path parameter.

The value you specify will be the amount that Kushki will charge to the card for the number of periods you defined. For example, your customer registered their card for a subscription of 30 USD monthly; if you want Kushki to charge 20 USD for two months, submit the amount and number 2, to stand for the number of periods.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'PUT',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Test environment
  headers: {'content-type': 'application/json'}
  body: {
    amount: {subtotalIva: 0, subtotalIva0: 20, ice: 0, iva: 0, currency: 'USD'},
    periods: 2
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = "{\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":20,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"periods\":2}"

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Replace this with your Private Key
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"amount":{"subtotalIva":0,"subtotalIva0":20,"ice":0,"iva":0,"currency":"USD"},"periods":20}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('PUT');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

According to the response you get, redirect the user to a success or fail screen to inform the customer if the discount was applied correctly or if an error occurred.

Cancel Recurring Charges

If your customer decides to cancel their subscription, make sure it is also canceled in Kushki, so that scheduled charges are no longer executed. This action is immediate; once you run it, the subscription will be automatically canceled.

First, you must find ID of the subscription that you want to cancel. Then, make a call to our subscription cancellation endpoint from your back end; don’t forget to include the subscription ID as a path parameter.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'DELETE',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Test environment 
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = {}

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Replace this with your Private Key
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('DELETE');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

According to the response you get, redirect the user to a success or fail screen to inform the customer if the subscription was canceled correctly or if an error occurred.