Card Payments

The Card API lets you tokenize card data and process payments securely. All sensitive card information is handled by Kushki — your server only sends the token.

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.

Payment flow

Request a card token

Call POST /card/v1/tokens from your backend with the card data and transaction amount. The response returns a one-time token valid for a single charge.

{
  "card": {
    "name": "Luis García",
    "number": "5451951574925480",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121"
  },
  "totalAmount": 150.00,
  "currency": "PEN"
}

⚠️ Token expiry: Tokens expire after a short window. Use them immediately — do not store them for later use.

Make a charge

Call POST /card/v1/charges with the token and amount breakdown. Include contactDetails and, optionally, orderDetails and productDetails for fraud scoring.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 150.00,
    "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.

💡 Sandbox OTP: If the card requires OTP validation in sandbox, use 555 for both PEN and USD transactions.

Handle the response

Check transactionStatus — "APPROVAL" means the charge was authorized.

{
  "ticketNumber": "922513792073660814",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521"
}

For the full response (card details, bank name, amounts), include "fullResponse": "v2" in your charge request.

Currencies

Peru supports two currencies:

Currency	Code
Peruvian Sol	`PEN`
US Dollar	`USD`

Document types

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

Deferred charges (Installments)

Peru supports deferred payments (cuotas). First call the deferred options endpoint to check which installment plans are available for the customer's card BIN, then include the plan in the charge request.

Step 1 — Check available plans

GET /card/v1/deferred/{bin}

Response includes available months and monthsOfGrace:

[
  {
    "months": ["2", "3", "4", "5", "6", "7"],
    "monthsOfGrace": [],
    "type": "all"
  }
]

Step 2 — Submit the charge

Aggregator model

Acquiring model

Send months as a top-level field in the charge body (not inside a deferred object):

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

Pre-authorization flow

Use pre-authorization to reserve funds without capturing them immediately.

Authorize

POST /card/v1/preAuthorization — Reserves funds on the card. Returns a ticketNumber.

Reauthorize (optional)

POST /card/v1/reauthorization — Extends the authorization window or adjusts the reserved amount. Pass the original ticketNumber.

Capture

POST /card/v1/capture — Captures the reserved amount (or a partial amount). Pass the original ticketNumber.

Void (if not capturing)

DELETE /v1/charges/{ticketNumber} — Cancels the authorization and releases the reserved funds.

Void and Refund

Operation	Endpoint	Notes
Void	`DELETE /v1/charges/{ticketNumber}`	Cancel a transaction. Supported: total and partial void.
Refund	`DELETE /v1/refund/{ticketNumber}`	Return funds to the cardholder. Supported: total and partial refund.

For a partial void or refund, include the amount object in the request body with the partial amount.

Recurring charges and card validation (`transactionMode`)

Include transactionMode in the token request for recurring flows or zero-amount card validation:

Value	Description
`initialRecurrence`	Marks the first transaction in a recurring series.
`subsequentRecurrence`	Subsequent recurring charges — CVV is not required once an `initialRecurrence` has been processed.
`accountValidation`	Zero-amount card validation. Confirms the card is valid without charging it.

Tokenless charge (v2)

POST /card/v2/charges accepts card data directly in the request body — no prior token call required. Useful for server-to-server integrations where you already hold the card data.

Webhooks

Include a webhooks array in your charge or pre-auth request to receive real-time notifications:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Kushki sends a POST to each URL when the transaction status changes.

3D Secure

Peru supports two 3DS modes:

Mode	Description
Insecure 3DS	Kushki handles the 3DS flow. Include `threeDomainSecure` with the JWT from the authentication step.
Own 3DS engine	You run your own 3DS server. Include the authentication result fields in `threeDomainSecure`. Supported for Mastercard and Visa.

Network Tokens (BETA)

Peru supports processing transactions with network-tokenized cards (tokens provisioned by Visa or Mastercard through digital wallets like Apple Pay).

To use this feature, set isNetworkToken: true in your token or tokenless charge request and include the networkToken object with the additional metadata:

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)

Also include the cryptogram field on the card object when the network token carries a cryptogram from the digital wallet or issuer token service. The value must be between 20 and 28 alphanumeric characters.

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

BIN info

GET /card/v1/bin/{bin} and GET /deferred/v2/bin/{bin} return card metadata (bank, brand, card type, issuing country) for a given BIN. Use this to determine deferred eligibility and display the card brand logo at checkout.

Account verification

To verify a card without charging it, request a token with totalAmount: 0. The token flow runs a zero-amount validation against the card.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Request a Card Token

Tokenize card data. Returns a one-time token for a single charge.

Make a Charge

Charge a card using a token. Supports single charges, deferred installments, 3DS, webhooks, and fraud scoring.

Tokenless Charge (v2)

Submit card data and charge in a single call — no prior token required.

Void a Transaction

Cancel a transaction before settlement. Supports total and partial void.

Refund a Transaction

Return funds to the cardholder. Supports total and partial refund.

Request Deferred Options

Returns available installment plans for a card BIN. Call before submitting a deferred charge.

Pre-Authorization

Reserve funds without capturing immediately.

Tokenless Pre-Authorization (v2)

Pre-authorize with card data directly — no prior token step.

Reauthorize

Extend or adjust a pending authorization.

Capture

Capture a previously authorized amount.

Account Verification

Verify a card with a zero-amount token request.

Validate OTP

Validate a one-time password for OTP-based 3DS flows.

BIN Info

Get card metadata (bank, brand, type, country) by BIN.

BIN Info v2

Extended BIN lookup including deferred eligibility.

Got a suggestion on this documentation? Contact us.

Payment flow#

Currencies#

Document types#

Deferred charges (Installments)#

Step 1 — Check available plans#

Step 2 — Submit the charge#

Pre-authorization flow#

Void and Refund#

Recurring charges and card validation (transactionMode)#

Tokenless charge (v2)#

Webhooks#

3D Secure#

Network Tokens (BETA)#

BIN info#

Account verification#

Authentication#

Using the API#

Available Endpoints#

Payment flow

Currencies

Document types

Deferred charges (Installments)

Step 1 — Check available plans

Step 2 — Submit the charge

Pre-authorization flow

Void and Refund

Recurring charges and card validation (`transactionMode`)

Tokenless charge (v2)

Webhooks

3D Secure

Network Tokens (BETA)

BIN info

Account verification

Authentication

Using the API

Available Endpoints