One-Click and Scheduled Payments

One-Click & Scheduled Payments let you register a customer's card once and charge it repeatedly — on demand or automatically on a schedule — without asking for card data again.

Supports both one-click (on-demand) charges and scheduled recurring charges with configurable billing cycles and retry logic.

Payment process

A subscription payment works in 2 main stages: card registration and recurring charge execution.

Stage 1 — Card registration

User selects payment method

In your website or app, the user selects the payment method. Make it clear that their card will be registered for recurring charges.

Request a recurring charge token

Call POST /subscriptions/v1/card/tokens with the card data and currency. Returns a one-time token used to create the subscription.

{
  "card": {
    "name": "Juan García",
    "number": "5451951574925480",
    "expiryMonth": "05",
    "expiryYear": "28",
    "cvv": "123"
  },
  "currency": "MXN"
}

Create the subscription

Call POST /subscriptions/v1/card with the token, plan details, and contact information. Kushki runs a small validation charge and automatically reverses it — this confirms the card can be charged.

{
  "token": "gV3ox6100000sAxClU033646vnnJsT83",
  "planName": "Plan Mensual",
  "periodicity": "monthly",
  "startDate": "2026-06-01",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "contactDetails": {
    "documentType": "CURP",
    "documentNumber": "GACJ800101HDFRRN09",
    "firstName": "Juan",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+525512345678"
  }
}

A successful response returns a subscriptionId — store it to manage future charges.

Stage 2 — Recurring charges

Automatic billing

Kushki processes recurring charges to the registered card automatically according to the amount and period defined in the subscription.

Billing runs every day from 6 AM GMT-5. Set startDate before this time if you want the first charge on the same day.

Retry logic

If a charge is rejected, Kushki retries automatically. By default, 3 retries over 3 consecutive days from the original startDate.

Customize retry logic with retryConfiguration:

`retryType`	Behavior
`scheduled`	Retries every N days for the entire period
`fixed`	Retries only on specific days of the month

{
  "retryConfiguration": {
    "retryType": "fixed",
    "value": [5, 15, 25]
  }
}

Transaction notifications

You receive webhook notifications for each charge attempt — successful or declined. Also available in the Kushki Console.

On-demand (one-click) charge

To charge a registered card immediately without waiting for the scheduled billing cycle:

POST /subscriptions/v1/card/{subscriptionId}

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  }
}

Currency

Currency	Code	Notes
Mexican Peso	`MXN`	Two decimal places — amounts use cents (e.g., `500.00`)

Document types

Value	Description
`CURP`	Clave Única de Registro de Población 🇲🇽
`RFC`	Registro Federal de Contribuyentes 🇲🇽
`PP`	Pasaporte 🇲🇽
`CC`	Identity Document 🇲🇽

MSI installments in subscriptions

Mexico supports Meses Sin Intereses (MSI) in one-click charges. Send the deferred object with creditType: "03", graceMonths: "00", and the number of months in the charge request.

Always call Request Deferred Options first to verify available plans for the card BIN.

Minimum amounts required for MSI

Months	Minimum amount
3	$300 MXN
6	$600 MXN
9	$900 MXN
12	$1,200 MXN
18	$1,800 MXN

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 900,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "deferred": {
    "creditType": "03",
    "graceMonths": "00",
    "months": 9
  }
}

Subscription pre-authorization flow

Use pre-authorization to reserve funds on a registered card before committing to the charge — useful for hotel and rental flows.

Pre-authorize

POST /subscriptions/v1/card/{subscriptionId}/authorize — Reserves funds on the registered card. Returns a ticketNumber.

Authorization holds expire after 28 days (credit) or 7 days (debit).

Capture

POST /subscriptions/v1/card/{subscriptionId}/capture — Captures the reserved amount. Pass the ticketNumber from the pre-authorization.

Manage subscriptions

Operation	Endpoint	Description
Get info	`GET /subscriptions/v1/card/search/{subscriptionId}`	Retrieve current status and configuration
Update card	`PUT /subscriptions/v1/card/{subscriptionId}/card`	Replace the card without canceling the subscription
Update plan	`PATCH /subscriptions/v1/card/{subscriptionId}`	Modify amount, frequency, or dates
Add temporary charge	`PUT /subscriptions/v1/card/{subscriptionId}`	Apply a one-time extra charge or discount to the next cycle
Cancel	`DELETE /subscriptions/v1/card/{subscriptionId}`	Cancel and deactivate the subscription

Periodicity options

Value	Description
`daily`	Charged every day
`weekly`	Charged every week
`biweekly`	Charged every two weeks
`monthly`	Charged every month
`bimonthly`	Charged every two months
`quarterly`	Charged every three months
`biannual`	Charged every six months
`annual`	Charged every year
`custom`	Custom interval — specify `periodDays`

Idempotency

Include the Idempotency-Key header to safely retry operations:

Rule	Detail
Validity window	24 hours
Maximum length	56 characters
Format	UUIDv4 recommended

Supported on: subscription pre-authorizations, voids, and refunds.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Sandbox OTP

When a card requires OTP validation in the sandbox environment, use 555 for MXN transactions.

Available Endpoints

Request a Recurring Charge Token

Tokenize card data to register it for recurring charges.

Create a Recurring Charge

Create a new subscription with the registered card token.

Make a One-Click Payment

Execute an on-demand charge against a registered card. Supports MSI installments.

Get Recurring Charge Info

Retrieve the details and current status of a subscription.

Update Recurring Charge Card

Replace the card associated with an active subscription.

Update a Recurring Charge

Modify the amount, frequency, or dates of an existing subscription.

Add a Temporary Charge or Discount

Apply a one-time extra charge or discount to the next billing cycle.

Cancel a Recurring Charge

Cancel and deactivate an active subscription.

Subscription Pre-Authorization

Reserve funds on a registered card without capturing immediately.

Subscription Capture

Capture a previously authorized amount on a registered card.

Got a suggestion on this documentation? Contact us.

Payment process#

Stage 1 — Card registration#

Stage 2 — Recurring charges#

On-demand (one-click) charge#

Currency#

Document types#

MSI installments in subscriptions#

Subscription pre-authorization flow#

Manage subscriptions#

Periodicity options#

Idempotency#

Authentication#

Using the API#

Available Endpoints#

Payment process

Stage 1 — Card registration

Stage 2 — Recurring charges

On-demand (one-click) charge

Currency

Document types

MSI installments in subscriptions

Subscription pre-authorization flow

Manage subscriptions

Periodicity options

Idempotency

Authentication

Using the API

Available Endpoints