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": "Camila Rodríguez",
    "number": "5451951574925480",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121"
  },
  "totalAmount": 150000,
  "currency": "COP"
}

⚠️ 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": 150000,
    "ice": 0,
    "iva": 0,
    "currency": "COP"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "firstName": "Camila",
    "lastName": "Rodríguez",
    "email": "user@example.com",
    "phoneNumber": "+573001234567"
  }
}

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

Currencies

Colombia supports one currency:

Currency	Code
Colombian Peso	`COP`

Document types

Value	Description
`CC`	Cédula de Ciudadanía 🇨🇴
`NIT`	Número de Identificación Tributaria 🇨🇴
`CE`	Cédula de Extranjería 🇨🇴
`TI`	Tarjeta de Identidad 🇨🇴
`PP`	Passport 🇨🇴

Deferred charges (Installments)

Colombia 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 the deferred type:

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

Step 2 — Submit the charge

Aggregator model

Acquirer model

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

{
  "token": "24e5cc0d47fc4b2ab098bdb7d0b94569",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 300000,
    "ice": 0,
    "iva": 0,
    "currency": "COP"
  },
  "months": 3,
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "firstName": "Camila",
    "lastName": "Rodríguez",
    "email": "user@example.com",
    "phoneNumber": "+573001234567"
  }
}

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

Colombia supports two 3DS modes:

Mode	Description
Insecure 3DS	Kushki handles the 3DS flow through kushki.js. Include the `jwt` obtained from the library when requesting the token.
Own 3DS engine	You run your own 3DS server. Include the authentication result fields in `threeDomainSecure` — `cavv`, `eci`, and `specificationVersion` for Visa; `directoryServerTransactionID`, `eci`, `ucaf`, `specificationVersion`, and `collectionIndicator` for Mastercard.

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)

For a complete explanation of both ways to use network tokens (bring your own token, or let Kushki create one), see Network Tokens.

Colombia 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 Colombia. 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