Card Payments

Accept credit and debit card payments in Chile 🇨🇱 — single charges, Cuotas Comercio, Cuotas Emisor, pre-authorization flows, and network tokens.

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

Private Key required

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 total amount. Returns a one-time token valid for a single charge.

{
  "card": {
    "name": "Catalina Fuentes",
    "number": "5451951574925480",
    "expiryMonth": "05",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 10000,
  "currency": "CLP"
}

⚠️ 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": 10000,
    "ice": 0,
    "iva": 0,
    "currency": "CLP"
  },
  "contactDetails": {
    "documentType": "RUT",
    "documentNumber": "12345678-9",
    "firstName": "Catalina",
    "lastName": "Fuentes",
    "email": "user@example.com",
    "phoneNumber": "+56912345678"
  }
}

A successful charge returns a ticketNumber and transactionReference.

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 the charge request.

Currency

Chile supports two currencies:

Currency	Code	Notes
Chilean Peso	`CLP`	Integer amounts only — no decimal places
Unidad de Fomento	`UF`	Indexed currency unit

No decimals for CLP

Always send CLP amounts as whole integers (e.g., 10000).

Document types

Value	Description
`RUT`	Rol Único Tributario 🇨🇱
`CC`	Cédula de Identidad 🇨🇱
`PP`	Pasaporte 🇨🇱

Integration models

Some operations are only available under the Acquirer model. Confirm your model with your Kushki account manager before integrating.

Operation	Acquirer	Aggregator
Request a card token	✅	✅
Make a charge or deferred charge	✅	✅
Create payment (tokenless)	✅	—
Void a transaction	✅	✅
Refund a transaction	✅	✅
Request deferred options	✅	✅
Authorize payments	✅	✅
Preauthorization (tokenless)	✅	—
Reauthorize payments	✅	—
Capture an authorized payment	✅	✅
Verify Account	✅	—
Validate OTP	✅	✅
BIN Info / BIN Info v2	✅	✅
Recurring charges (`transactionMode`)	✅	—
Own 3DS engine	✅	—
Own subscriptions engine	✅	—

Deferred charges (Installments)

Chile supports two installment types. Always call the deferred options endpoint first to verify the card BIN supports installments and to retrieve the valid month options.

Step 1 — Check available plans

GET /card/v1/deferred/{bin}

Example response:

[
  {
    "months": ["2", "3", "6", "12"],
    "monthsOfGrace": [],
    "type": "03"
  }
]

The type field tells you which installment types the BIN supports:

`type`	Meaning
`all`	All available types — includes both Cuotas Comercio and Cuotas Emisor
`03`	Cuotas Comercio only (merchant installments, no interest)

Step 2 — Submit the charge

Cuotas Comercio (Merchant Installments) — Beta

Cuotas Emisor (Issuer Installments)

⚠️ Beta: Cuotas Comercio (creditType 03) is currently in Beta phase for Chile. The data structure and logic may change without prior notice. Contact the Kushki team to enable this feature.

The merchant absorbs the installment cost. Send the deferred object with creditType: "03". Available from 2 to 12 months. All three fields — graceMonths, creditType and months — are required.

{
  "token": "24e5cc0d47fc4b2ab098bdb7d0b94569",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 30000,
    "ice": 0,
    "iva": 0,
    "currency": "CLP"
  },
  "deferred": {
    "graceMonths": "00",
    "creditType": "03",
    "months": 6
  },
  "contactDetails": {
    "documentType": "RUT",
    "documentNumber": "12345678-9",
    "firstName": "Catalina",
    "lastName": "Fuentes",
    "email": "user@example.com",
    "phoneNumber": "+56912345678"
  }
}

Pre-authorization flow

Use pre-authorization to reserve funds without capturing them immediately — ideal for hotel, car rental, or marketplace flows.

Authorize

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

In Chile the authorization expires after:

28 days for credit cards

7 days for debit cards

Reauthorize (optional)

POST /card/v1/reauthorization — Extends the amount or effect of the original authorization. Pass the original ticketNumber. The currency must match the original authorization.

If the payment is not captured within 7 days (debit) or 28 days (credit), the issuing bank may return the withheld funds to the cardholder.

Capture

POST /card/v1/capture — Captures the reserved funds (full or partial amount). Use the ticketNumber of the authorization, not of a reauthorization.

The maximum amount to capture may be up to 10% higher than the initial authorization plus any reauthorizations that have not been cancelled.

Void (if not capturing)

DELETE /v1/charges/{ticketNumber} — Cancels the authorization and releases the reserved funds. Once cancelled, no reauthorizations can be made on that transaction.

Void and Refund

Operation	Endpoint	Notes
Void	`DELETE /v1/charges/{ticketNumber}`	Cancel a transaction before settlement.
Refund	`DELETE /v1/refund/{ticketNumber}`	Return funds to the cardholder after settlement.

Both void and refund support total and partial amounts in Chile. For a partial operation, include the amount object in the request body.

Recurring charges and card validation (`transactionMode`)

Include transactionMode in the token request for recurring flows or zero-amount card validation. Available under the Acquirer model only.

Value	Description
`initialRecurrence`	First transaction in a recurring series. Send complete card data (number, expiry, CVV) to register it.
`subsequentRecurrence`	Subsequent recurring charges — CVV can be omitted once an `initialRecurrence` has been processed.
`accountValidation`	Zero-amount card validation. Set `totalAmount` to `0` and then call `POST /card/v1/validation`.

Own subscriptions engine

If you run your own subscriptions engine (PCI-compliant merchants only), process recurring charges as follows:

Request a token with transactionMode: "initialRecurrence".

Make the initial charge

Charge with that token, and save the transactionReference from the response.

Tokenize for subsequent charges

Request a token with transactionMode: "subsequentRecurrence".

Charge subsequent transactions

Send the saved transactionReference in the initialRecurrenceReference field of the charge request.

For Mastercard, include citMit as an informative field when processing external subscriptions. Values are C101–C104 for customer-initiated transactions and M101–M104, M205–M208 for merchant-initiated ones.

Tokenless charge (v2)

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

On-demand service — PCI DSS required

Tokenless endpoints are available only to PCI DSS compliant companies, under the Acquirer model. Contact Kushki before enabling.

Limitations:

Only available for Visa and Mastercard.

Not compatible with Siftscience or TransUnion antifraud tools.

Not compatible with Kushki's 3DS authentication tool — use your own 3DS engine instead.

Not compatible with Kushki OTP authentication.

3D Secure

Chile supports two 3DS approaches:

Kushki-managed 3DS

Add these fields to the token request:

Field	Values	Description
`authValidation`	`url`, `iframe`	Integration type — `url` for redirection, `iframe` for embedding.
`callbackUrl`	string	Callback where the 3DS authentication response is sent.

If the transaction triggers a 3DS rule, the token response also returns:

{
  "token": "sBkQ7F110000tI1HVq116862fd5Ah3mG",
  "url": "https://uat-auth.kushkipagos.com?token=...",
  "secureService": "3dsecure",
  "secureId": "1f5584db-0c5b-c729-a19c-6eb0283ca448"
}

Display the url to the cardholder to complete authentication.

Own 3DS engine

Available under the Acquirer model. Include the threeDomainSecure object in the token, charge or pre-authorization request:

Brand	Required fields
Visa	`cavv`, `eci`, `specificationVersion`
Mastercard	`directoryServerTransactionID`, `eci`, `ucaf`, `specificationVersion`, `collectionIndicator`

ECI values:

Visa — 05 and 06 are secure; 07 is risky.

Mastercard — 01 and 02 are secure; 00 is risky.

To process a risky transaction, also send acceptRisk: true. By doing so the merchant assumes liability for chargebacks.

Network Tokens

BETA

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

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 only)

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

⚠️ Beta: Contact your Kushki account manager before enabling this feature.

Account verification

To verify that a card is active without charging it:

Request a token with transactionMode: "accountValidation" and totalAmount: 0.

Call POST /card/v1/validation with that token.

Available under the Acquirer model only.

Voucher

GET /webhook/v1/transaction/receipt/{transactionReference} returns a PDF of the purchase receipt, Base64-encoded, with the value of the sales and service ticket.

This endpoint is available in Chile only.

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.

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 — accepting the first 8 or 10 digits.

For Chilean merchants the response helps decide whether to continue with a card token request (when cardType is CREDIT) and which installment options to offer. Use it also to display the card brand logo at checkout.

Validate OTP

POST /rules/v1/secureValidation validates the OTP entered by the customer, using the secureId returned by the token request. The customer has 5 minutes and 3 attempts with the same secureId.

Sandbox

To simulate an approved OTP validation in sandbox, use 150 for CLP. Any other value results in a declined validation.

Idempotency

Include the Idempotency-Key header to safely retry operations without creating duplicates:

Rule	Detail
Validity window	24 hours — after that, the same key generates a new transaction
Maximum length	56 characters
Uniqueness	Must be unique per transaction type
Format	UUIDv4 or another generator with sufficient entropy

Supported on Void a transaction, Refund a transaction (both for one-time charges, pre-authorizations and subscription charges), and subscription pre-authorizations.

Kushki stores the status code and response body only if the original request succeeds. If the request failed with a 4XX or 5XX, no idempotency record is stored and you can safely retry with the same key.

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, Cuotas Comercio, Cuotas Emisor, 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 any deferred charge.

Pre-Authorization

Reserve funds without capturing immediately.

Tokenless Pre-Authorization (v2)

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

Reauthorize

Extend or adjust a pending authorization before it expires.

Capture

Capture a previously authorized amount.

Verify Account

Verify a card with a zero-amount token request — no charge.

Validate OTP

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

BIN Info v2

Extended BIN lookup including deferred eligibility and card metadata.

BIN Info

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

Voucher

Retrieve the purchase receipt as a Base64-encoded PDF.

Got a suggestion on this documentation? Contact us.

Payment flow#

Currency#

Document types#

Integration models#

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)#

Own subscriptions engine#

Tokenless charge (v2)#

3D Secure#

Kushki-managed 3DS#

Own 3DS engine#

Network Tokens#

Account verification#

Voucher#

Webhooks#

BIN info#

Validate OTP#

Idempotency#

Authentication#

Using the API#

Available Endpoints#

Payment flow

Currency

Document types

Integration models

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`)

Own subscriptions engine

Tokenless charge (v2)

3D Secure

Kushki-managed 3DS

Own 3DS engine

Network Tokens

Account verification

Voucher

Webhooks

BIN info

Validate OTP

Idempotency

Authentication

Using the API

Available Endpoints