Create a recurring charge

December 27, 2024

Register your customers' credit or debit card data to charge them with the frequency that you define for payments

Receiving recurring payments made with debit and credit cards in your iOS app means collecting your client’s card data, generating a token, and creating a subscription in Kushki. This allows charges to be automatically made with the periodicity you prefer.

The payment flow that you will integrate is shown below:

1. Set up your App

The App is responsible for collecting the user’s information safely, generating a token for that information through Kushki’s servers and sending that information to your back end to create a subscription.

Install Kushki’s SDK

We will use CocoaPods for the installation. If you don’t have CocoaPods yet, you can find the latest version here.

Embed the library in your project, by adding the following line to your Podfile:

pod 'Kushki', '~> 2.4.2'

Then run the following command:

pod install

For updating to the latest version execute this:

pod update Kushki

Set up your App

let publicMerchantId = "public-merchant-id"
let kushki = 
  Kushki(
    publicMerchantId: publicMerchantId,
    currency: "USD",
    environment: KushkiEnvironment.testing
  )

Request the Token and Send it to your Back End

For the moment when the user enters his/her card data in the form, use the example below to add a token request and take it to your back end:

import UIKit
import Kushki
class ViewController: UIViewController {
    // ...
  private func requestSubscriptionToken(card: { //Example of what is expected in the card object
    name: "Juan Guerra",
    number: "4544980425511225",
    cvc: "345",
    expiryMonth: "12",
    expiryYear: "28"
  }) {
        let publicMerchantId = "public-merchant-id"
        let kushki = Kushki(publicMerchantId: publicMerchantId,
                            currency: "USD",
                            environment: KushkiEnvironment.testing,
                            false)//optional parameter regional
        kushki.requestSubscriptionToken(card: card)
            {DispatchQueue.main.async(execute: {
                let alert = UIAlertController(title: "Kushki Token",
                                              message: message,
                                              preferredStyle: UIAlertControllerStyle.alert)
                alert.addAction(UIAlertAction(title: "Ok", style: .default))
                self.present(alert, animated: true)
            })
        }
    }
}

2. Set up your Back End

The back end is responsible for receiving the token obtained from your front end and creating a subscription with Kushki.

When the user submits the form, your front end sends a token to an endpoint that you specified previously. Using this token, you must make a call to our API endpoint to create the subscription.

var request = require("request");

var options = {
  method: 'POST',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Replace this with your Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card', // test environment
  headers: {'content-type': 'application/json'},
  body: {
    token: 'V0OzRB100000xhxQB8035251pHLBQsq5', // Replace this with the obtained token
    amount: {subtotalIva: 0, subtotalIva0: 14.99, ice: 0, iva: 0, currency: 'USD'},
    planName: 'Premium',
    periodicity: 'monthly',
    contactDetails: {firstName": 'Juan', lastName: 'Flores', email: 'pruebas@kushki.com', phoneNumber: '0984775632'},
    startDate: '2021-09-25', // Fecha del primer cobro
    metadata: {contractID: '157AB'}
  },
  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"

payload = "{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":14.99,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"planName\":\"Premium\",\"periodicity\":\"monthly\",\"contactDetails\":{\"firstName\":\"Juan\",\"lastName\":\"Flores\",\"email\":\"pruebas@kushki.com\",\"phoneNumber\":\"0984775632\"},\"startDate\":\"2021-09-25\",\"metadata\":{\"contractID\":\"157AB\"}}"

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

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

print(response.text)

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

$body = new http\Message\Body;
$body->append('{"token":"V0OzRB100000xhxQB8035251pHLBQsq5","amount":{"subtotalIva":0,"subtotalIva0":14.99,"ice":0,"iva":0,"currency":"USD"},"planName": "Premium","periodicity": "monthly","contactDetails": {"firstName":"Juan","lastName":"Flores","email":"pruebas@kushki.com","phoneNumber":"+593984775632"},"startDate":"2021-09-25","metadata":{"contractID":"157AB"}}');

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

$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 obtained, redirect the user to a success or fail screen to inform the customer whether the transaction was approved or declined.

3. Test your Integration

You can use some test cards in test mode to ensure that your integration is ready. Use them adding any CVV and a future expiration date.

• Approved transaction: 5451951574925480
• Transaction declined for token request (front end): 4574441215190335.

4. Prepare your Certification

Read the following guidelines for technical certification approval (required to obtain productive account credentials):

• Tax calculations must be correct.
• Sensitive card data are not stored in your database (full card number, CVV, etc.).
• Messages displayed on screen are in line with Kushki’s responses.
• All Kushki responses must be saved (required in case you need support).
• The first payment date (startDate) must be a future date.
• The subscription is also cancelled in Kushki when your customer decides to cancel his/her recurring charges.
• Make sure all the required data as specified in the API Reference are sent.
• The cardholder’s name must be required.
• The card number field must be required.
• The card number field must only accept numbers.
• The credit card field must allow a maximum of 16 digits (there may be less).
• The CVV field must be required.
• The CVV field must only accept numbers.
• The CVV field must allow no more than 4 digits and no less than 3 digits.
• The expiration date must be required.
• The payment button must be disabled after the first click.
• Kushki’s logo must be visible for the customer. You can find our logo in several formats here.