One-Click & Scheduled Payments

One-Click & Scheduled Payments let you register a customer's card as a subscription and charge it later — either automatically on a schedule or manually on demand. The card data is tokenized once and never stored on your servers.

Keep in mind!

Token generation requires your Private Key (Private-Merchant-Id). Never expose it in client-side or frontend code — always call the token endpoint from your backend.

Two charge modes

Mode	How it works
Scheduled	Kushki charges the card automatically based on the `periodicity` you configure (daily, monthly, yearly, etc.)
One-click (on-demand)	You trigger each charge manually via `POST /subscriptions/v1/card/{subscriptionId}`. Use `periodicity: "custom"` when creating the subscription.

Flow

Request a subscription token

Call POST /subscriptions/v1/card/tokens from your backend with the customer's card data. Returns a one-time token.

{
  "card": {
    "name": "Luis García",
    "number": "4242424242424242",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "123"
  },
  "currency": "PEN"
}

⚠️ Token expiry: Use the token immediately to create the subscription. Do not store it.

Create the subscription

Call POST /subscriptions/v1/card with the token, plan details, and the recurring amount. The response returns a subscriptionId you store on your side.

{
  "token": "gV3ox6100000sAxClU033646vnnJsT83",
  "planName": "Premium",
  "periodicity": "monthly",
  "startDate": "2026-06-01",
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 99.90,
    "ice": 0,
    "iva": 0,
    "currency": "PEN"
  }
}

Charge the subscription

Scheduled: Kushki charges automatically — no action needed from you.

One-click: Call POST /subscriptions/v1/card/{subscriptionId} whenever you want to charge the customer.

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 99.90,
    "ice": 0,
    "iva": 0,
    "currency": "PEN"
  },
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  }
}

A successful charge returns a ticketNumber and transactionReference. Use "fullResponse": "v2" to get the full approval details.

💡 Sandbox OTP: If OTP validation is triggered in sandbox, use 555 for both PEN and USD.

Periodicities

Value	Frequency
`daily`	Every day
`weekly`	Every week
`biweekly`	Every two weeks
`monthly`	Once a month
`threefortnights`	Every three fortnights
`bimonthly`	Every two months
`quarterly`	Every three months
`fourmonths`	Every four months
`halfYearly`	Every six months
`yearly`	Once a year
`custom`	On-demand — you trigger each charge manually

Document types

Value	Description
`DNI`	Documento Nacional de Identidad 🇵🇪
`CE`	Carné de Extranjería 🇵🇪
`PAS`	Pasaporte 🇵🇪
`RUC`	Registro Único de Contribuyentes 🇵🇪

Deferred charges on subscriptions

Peru supports deferred installments on subscription charges. Include the deferred object in the charge request:

Aggregator model

Acquiring model

Send months as a top-level field (not inside deferred):

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 300.00,
    "iva": 0,
    "ice": 0,
    "currency": "PEN"
  },
  "months": 3,
  "contactDetails": {
    "documentType": "DNI",
    "documentNumber": "12345678",
    "firstName": "Luis",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+51912345678"
  }
}

Managing subscriptions

Operation	Endpoint	Description
Get info	`GET /subscriptions/v1/card/search/{subscriptionId}`	Retrieve subscription details, card info, and plan configuration
Update card	`PUT /subscriptions/v1/card/{subscriptionId}/card`	Replace the registered card with a new token
Update plan	`PATCH /subscriptions/v1/card/{subscriptionId}`	Modify amount, periodicity, or plan name
Add temp charge	`PUT /subscriptions/v1/card/{subscriptionId}`	Apply a one-time extra charge or discount on the next billing cycle
Cancel	`DELETE /subscriptions/v1/card/{subscriptionId}`	Cancel the subscription permanently

Pre-authorization flow

For subscriptions that require fund reservation before capture:

Authorize

POST /subscriptions/v1/card/{subscriptionId}/authorize — Reserves funds without charging. Returns a ticketNumber.

Capture

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

Example response (full)

{
  "details": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 99.90,
      "ice": 0,
      "iva": 0,
      "currency": "PEN"
    },
    "approvalCode": "000000",
    "approvedTransactionAmount": 99.90,
    "binInfo": {
      "bindCard": "445652",
      "cardCountry": "Peru",
      "lastFourDigits": "9860",
      "type": "credit"
    },
    "merchantName": "Mi Comercio Perú",
    "paymentBrand": "Visa",
    "responseCode": "000",
    "responseText": "Transacción aprobada",
    "transactionStatus": "APPROVAL",
    "transactionType": "SALE",
    "maskedCreditCard": "445652XXXXXX9860"
  },
  "ticketNumber": "028590538321035813"
}

Network Tokens (BETA)

Peru supports tokenizing subscription cards using network-tokenized cards (tokens provisioned by Visa or Mastercard through digital wallets like Apple Pay).

When requesting a subscription token (POST /subscriptions/v1/card/tokens), set isNetworkToken: true and include the networkToken object:

Field	Description
`deviceType`	Type of device originating the tokenized transaction
`requestorId`	Unique ID assigned to the token requestor by the card network
`source`	Source of the token
`walletId`	Digital wallet identifier — `"01"` for Apple Pay, `"04"` for other wallets
`authenticationLevel`	Authentication level performed during token provisioning
`mvv`	10-digit Merchant Verification Value (Visa transactions only)

⚠️ BETA: This feature is available in Peru and Chile only. Contact your Kushki account manager before enabling it.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Request a Subscription Token

Tokenize a card for recurring use. Returns a one-time token to create the subscription.

Create a Subscription

Charge a Subscription

Trigger an on-demand charge against a subscription. Also used for deferred installment charges.

Get Subscription Info

Retrieve the full configuration and card details of an existing subscription.

Update Card

Replace the registered card with a new token — e.g. after card expiry or a failed charge.

Update Subscription

Modify the plan amount, periodicity, or name of an existing subscription.

Add Temporary Charge

Apply a one-time extra charge or discount on the next billing cycle without modifying the base plan.

Cancel Subscription

Permanently cancel a subscription. The customer will not be charged again.

Authorize (Pre-auth)

Reserve funds on the subscription card without capturing immediately.

Capture

Capture a previously authorized amount on a subscription.

Got a suggestion on this documentation? Contact us.

Two charge modes#

Flow#

Periodicities#

Document types#

Deferred charges on subscriptions#

Managing subscriptions#

Pre-authorization flow#

Example response (full)#

Network Tokens (BETA)#

Authentication#

Using the API#

Available Endpoints#

Two charge modes

Flow

Periodicities

Document types

Deferred charges on subscriptions

Managing subscriptions

Pre-authorization flow

Example response (full)

Network Tokens (BETA)

Authentication

Using the API

Available Endpoints