Create a recurring charge

This functionality is available for the following models:
☑ Acquirer
☑ Aggregator

Create a recurring charge with a token provided by Kushki which represents the customer's credit card.

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.

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.

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 a charge on demand only for one time. Kushki will continue executing automatic charges over the following periods.

Customize retry logic

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

retryType:"schedule". If you choose 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":"schedule",
      "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]
  }
}

Send the retryType as fixed if you do not want to retry 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 them 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.

Important!
When customizing retries it should be noted that once the first collection is initiated, if it fails and retries are initiated, any updates to retries will be applied until the next subscription period (weekly, monthly, yearly).

Periodicity

You can choose the frequency of recurring charges by submitting any of these values in the required periodicity field:

daily: every 1 day.

weekly: every 7 days.

biweekly: every 15 days.

monthly: every 30 days.

threefortnights: every six weeks or 42 days.

bimonthly: every 60 days.

quarterly: every 90 days.

fourmonths: every 120 days.

halfyearly: every 180 days

yearly: every 360 days.

custom: for one click payments.

Using fullResponse: v3

Sending "fullResponse": "v3" returns an expanded response where the details object includes additional fields compared to v2. One of these fields is validationTicketNumber, which contains the ticket number of the validation charge executed when the subscription was created.

V3 response stability
The v3 response may include new or deprecated fields without prior notice. Do not build logic that depends on the exact set of fields returned in details. Always handle unexpected or missing fields gracefully.

Got a suggestion on this documentation? Contact Us.

Do you have your own 3DS authentication engine?

Make sure you include the threeDomainSecure object in your request.

curl --location 'https://api-uat.kushkipagos.com/subscriptions/v1/card' \ --header 'Private-Merchant-Id;' \ --header 'Content-Type: application/json' \ --data-raw '{ "token": "gV3ox6100000sAxClU033646vnnJsT83", "planName": "Premium", "periodicity": "monthly", "contactDetails": { "documentType": "CE", "documentNumber": "1009283738", "email": "user@example.com", "firstName": "John", "lastName": "Doe", "phoneNumber": "+51912345678" }, "amount": { "subtotalIva": 1, "subtotalIva0": 0, "ice": 0, "iva": 0.14, "currency": "PEN" }, "startDate": "2022-05-25", "metadata": { "plan": { "fitness": { "cardio": "include", "rumba": "include", "pool": "include" } } } }'

This functionality is available for the following models:

Payment Execution

Retries

Customize retry logic

Important!

Periodicity

Using fullResponse: v3

V3 response stability

Do you have your own 3DS authentication engine?

Request

Responses

Create a recurring charge

This functionality is available for the following models:#

Payment Execution#

Retries#

Customize retry logic#

Important!#

Periodicity#

Using fullResponse: v3#

V3 response stability#

Do you have your own 3DS authentication engine?#

Request

Responses

This functionality is available for the following models:

Payment Execution

Retries

Customize retry logic

Important!

Periodicity

Using fullResponse: v3

V3 response stability

Do you have your own 3DS authentication engine?