Overview

Discover a bit more about the recurring payment process

Credit cards have global coverage and are one of the most popular ways to pay online. There are different types of cards and several steps in the process. Learn how it works, the parties involved, and the stages of a subscription payment.

WARNING

To keep in mind

Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.

NOTE

NOTE: This service is also known as Tokenization and recurrent charge execution.

Payment process

A credit card payment for a subscription is made in 2 main steps: Credit or debit card registration and execution of the recurring charge.

Credit or Debit Card Registration

1. Selecting a Payment Method

In your website or app, the user will select the payment method. Make sure that it is clear for the payer that their credit or debit card will be registered for paying a recurring value.

2. Providing Card Data

At this step, the user provides the data of the card that he/she will use to pay. Your website or app should be capable of verifying that the card information is correct (for example, that the expiration date is not outdated, or that the card number can be validated using Luhn's algorithm). In this step, it cannot be yet warranted that the card is valid.

3. Submitting Data to Kushki

Kushki will receive this data and will verify whether there are enough funds in the account associated with the credit or debit card by using a charge for subscription validation. This small fee is charged by Kushki and is automatically reversed if successful. This fee ensures that your client's credit card can be charged after registration.

4. Creating a Subscription Notification

At this step, we will inform you about the result of the card registration process, so that you can show it on screen to the user.

Recurring Payment

1. Payment Execution

Kushki processes recurring charges to the registered card automatically. Payments will be executed and repeated according to the amount and period indicated in the subscription.

The billing logic starts running every day from 6am GMT-5. Make sure that the subscription was created before this time if you want the first payment to be executed on the same day of registration. Alternatively, your customer can register his/her card some days in advance, before Kushki executes the first charge. When creating a subscription, you must indicate the start date startDate.

2. Transaction Status Notification

At this step, you will be notified of the status of each automatic charge. You may receive the Webhook notifications that you expose for Kushki to consume. You also use Kushki's console to verify transactions, as well as their details and their status.

Retries

If a payment is rejected, Kushki has a retry logic to try to recover the charge. By default, there are 3 retries for 3 days in a row from the payment day originally defined in startDate. For example, for a monthly subscription with start date: 10-01-2021, with a rejection on 10-02-2021, payment will be retried until 13-02-2021, 3 times each day, for a total of 9 payment attempts.

You can modify the retry days for a subscription and also define specific charging days.

Customized retry logic

You can customize the collection retry logic by submitting the retryConfiguration object as follows:

retryType:"schedule". If you choose a schedule, you can specify in the value field you can specify in value how often the collection will be reattempted.
In the next example, the collection will be reattempted 3 times per day every 2 days for the entire month.

{
   "retryConfiguration":{
      "retryType":"scheduled",
      "value":[2]
   }
}

retryType:"fixed". Send the specific days of the month to retry. Ex. 10th, 20th, 30th.
In the following example, the charge will only be reattempted 3 times a day, on the 10th, 20th and 30th of the corresponding month.

{
  "retryConfiguration":{
     "retryType":"fixed",
     "value":[10,20,30]
  }
}

NOTE

Send the retryType as fixed if you do not want to retry the collection for the entire month.
If the last charge attempt was declined, we may send you a notification via WebHook informing you about it. In these cases, we recommend you to contact the card owner and offer him/her a set of alternatives for paying the fee that could not be charged; for example, changing the registered credit card and generating an One-click payment only for one time. Kushki will continue executing automatic charges over the following periods.

Start your integration and accept recurring payments online safely.

Using the API

To use the API you must ask for your Kushki Sandbox, composed of a Public-Merchant-Id and a Private-Merchant-Id.

Environment	URL
Production	`https://api.kushkipagos.com/`
Testing (Sandbox)	`https://api-uat.kushkipagos.com/`

Idempotency

Kushki’s API supports idempotent requests to safely retry operations without the risk of executing the same transaction twice. This feature is especially useful when network issues, timeouts, or client retries might otherwise create duplicate records.

How it works

To perform an idempotent request, include the header Idempotency-Key with a unique value when calling one of the supported endpoints.

Kushki stores the resulting status code and response body only if the original request succeeds.

If the same key is sent again within the validity window, the same successful response is returned.

If the original request failed with a 4XX or 5XX error, no idempotency record is stored, and the client can safely retry the entire process with the same Idempotency-Key.

Header

Rules

Valid for: 24 hours. After this period, if the same Idempotency-Key is sent again, a new transaction will be generated.

Maximum length: 56 characters.

Uniqueness: must be unique per transaction type.

Scope: applies only to supported endpoints (see below).

Generation: clients are responsible for generating keys. We recommend UUIDv4 or another random string generator with sufficient entropy.

Supported endpoints

The Idempotency-Key header is currently supported in:

Void a transaction (one-time charges, preauthorizations, and subscription charges).

Refund a transaction (one-time charges, preauthorizations, and subscription charges).

Subscription preauthorizations.

Error scenarios

`5XX` errors (server-side issues)

No idempotency record is stored.

The client may retry with the same Idempotency-Key.

Retrying is at the integrator’s discretion.

`4XX` errors (client-side issues)

No idempotency record is stored.

The client may retry with the same Idempotency-Key after correcting the input.

Retrying is at the integrator’s discretion.

Best practices

Always generate a new Idempotency-Key for each unique transaction attempt.

Use a UUID or another strong random string generator to ensure uniqueness.

Endpoints

We dispose various endpoints to start your payment flows, find our products available:

Request a recurring charge token

Create a recurring charge

Make an One-click payment

Cancel a recurring charge

Add a temporary charge or discount

Get recurring charge Info

Update a recurring charge

Update recurring charge card data

Discover a bit more about the recurring payment process#

To keep in mind#

Payment process#

Credit or Debit Card Registration#

Recurring Payment#

Retries#

Customized retry logic#

Using the API#

Idempotency#

How it works#

Header#

Rules#

Supported endpoints#

Error scenarios#

5XX errors (server-side issues)#

4XX errors (client-side issues)#

Best practices#

Endpoints#

Discover a bit more about the recurring payment process

To keep in mind

Payment process

Credit or Debit Card Registration

Recurring Payment

Retries

Customized retry logic

Using the API

Idempotency

How it works

Header

Rules

Supported endpoints

Error scenarios

`5XX` errors (server-side issues)

`4XX` errors (client-side issues)

Best practices

Endpoints