Card Payments

The Card API lets you tokenize card data and process payments securely in Mexico. All sensitive card information is handled by Kushki — your server only sends the token. All amounts are in Mexican Pesos (MXN).

Keep in mind!

Two credentials are involved and they are not interchangeable:

Public Key (Public-Merchant-Id) — tokenization and card lookups: POST /card/v1/tokens, POST /rules/v1/secureValidation, GET /card/v1/deferred/{bin}, GET /card/v1/bin/{bin} and GET /deferred/v2/bin/{bin}.

Private Key (Private-Merchant-Id) — every operation that moves money: charges, pre-authorizations, re-authorizations, captures, voids and refunds.

Never expose the Private Key in client-side or frontend code — always call those endpoints 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": "Juan Pérez",
    "number": "4242424242424242",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 116,
  "currency": "MXN"
}

Create the charge

Send POST /card/v1/charges with the token and the amount breakdown. IVA in Mexico is typically 16%.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 100,
    "subtotalIva0": 0,
    "iva": 16,
    "currency": "MXN"
  }
}

Integration models

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

Capability	Availability
Network tokens (`isNetworkToken`, `networkToken`, `cryptogram`)	Acquirer only — BETA in Mexico
`isoErrorCode` in declined charges	Acquirer only, and only when `fullResponse` is `v2`
`messageFields` (additional brand response codes)	Acquirer only

Document types

Type	Description
`CC`	Identity document.
`CURP`	Clave Única de Registro de Población (unique population registry code).
`RFC`	Registro Federal de Contribuyentes (tax ID number).

Deferred payments — Meses Sin Intereses (MSI)

Mexico supports installment payments through Meses Sin Intereses (MSI).

Check available plans

Call GET /card/v1/deferred/{bin} with the card BIN to retrieve the MSI plans the issuer allows. This is the recommended endpoint for MSI. It accepts the first six or eight digits of the card number.

Submit the deferred charge

Send POST /card/v1/charges including the deferred object:

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": { "subtotalIva": 100, "subtotalIva0": 0, "iva": 16, "currency": "MXN" },
  "deferred": {
    "creditType": "03",
    "graceMonths": "0",
    "months": 6
  }
}

creditType: "03" corresponds to Meses Sin Intereses. Available months values depend on the issuing bank.

Two-step payments (pre-authorization & capture)

Reserve funds now and capture them later — useful for orders confirmed after checkout.

Pre-authorize

POST /card/v1/preAuthorization reserves the amount on the cardholder's account.

Capture

POST /card/v1/capture charges the reserved amount (full or partial).

Re-authorize (optional)

POST /card/v1/reauthorization adjusts a pre-authorized amount before capture.

Tokenless payments

If your integration is PCI-compliant, you can send card data directly without a separate token step:

POST /card/v2/charges — tokenless charge.

POST /card/v2/preAuthorization — tokenless pre-authorization.

3D Secure

You can either let Kushki run the 3DS challenge or send the result of your own authentication engine.

Kushki-managed 3DS

Send require3DS: true when requesting the token (POST /card/v1/tokens). Kushki runs the challenge and returns the authentication result.

Own 3DS engine

If you run your own engine, send the threeDomainSecure object in the charge. The required fields depend on the card brand:

Field	Visa	Mastercard
`cavv`	Required	—
`ucaf`	—	Required
`eci`	Required	Required
`specificationVersion`	Required	Required
`collectionIndicator`	—	Required
`directoryServerTransactionID`	—	Required

specificationVersion accepts 2.0.0 and 2.2.0. Support for 3D Secure 1.0.2 ended in October 2022, so version 2 of the protocol is required.

Electronic Commerce Indicator (eci) — the value returned by the directory server with the result of the attempted authentication:

Brand	Value	Meaning
Visa	`05`, `06`	Secure transaction.
Visa	`07`	Risky transaction. Set `acceptRisk` to `true` to process it.
Mastercard	`01`, `02`	Secure transaction.
Mastercard	`00`	Risky transaction. Set `acceptRisk` to `true` to process it.

collectionIndicator (Mastercard only):

Value	For ECI	Meaning
`0`	`00`	3DS authentication failed or could not be attempted.
`1`	`01`	The issuer is not ready, but liability shifts because the merchant requested 3DS.
`2`	`02`	Transaction authenticated by the issuer, with liability shift.

Liability

By sending acceptRisk as true you assume responsibility in case of chargebacks.

Network Tokens

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

A network token replaces the card PAN with a token provisioned by the card network (Visa, Mastercard) or a digital wallet. BETA — available under the Acquirer model only.

Set isNetworkToken to true and send the networkToken object. If the field is omitted or set to false, the card number is treated as a traditional PAN.

Available on:

POST /card/v1/tokens — also accepts cryptogram.

POST /card/v2/charges — tokenless charge.

Field	Description
`walletId`	`01` for Apple Pay, `04` for other wallets.
`requestorId`	Token requestor identifier assigned by the network.
`source`	Origin of the token.
`deviceType`	Type of device the token originates from.
`authenticationLevel`	Level of authentication performed.
`mvv`	Merchant Verification Value.

Voids & refunds

Action	Endpoint	When
Void	`DELETE /v1/charges/{ticketNumber}`	Same-day reversal, before settlement.
Refund	`DELETE /v1/refund/{ticketNumber}`	After settlement — returns funds to the cardholder.

Idempotency

Send the Idempotency-Key header to retry an operation safely without duplicating it. Keys are valid for 24 hours.

Endpoint	`Idempotency-Key`
`DELETE /v1/charges/{ticketNumber}` (void)	Required
`DELETE /v1/refund/{ticketNumber}` (refund)	Optional

OTP validation & card information

POST /rules/v1/secureValidation — validate the OTP challenge when authentication is required. Send secureServiceId and otpValue; both are mandatory.

GET /card/v1/bin/{bin} — retrieve card BIN information (brand, type, issuer). Accepts the first six digits only.

GET /deferred/v2/bin/{bin} — same information, accepting the first eight to ten digits.

The three endpoints are not interchangeable: each accepts a different BIN length, and only GET /card/v1/deferred/{bin} returns MSI plans.

Payment flow#

Integration models#

Document types#

Deferred payments — Meses Sin Intereses (MSI)#

Two-step payments (pre-authorization & capture)#

Tokenless payments#

3D Secure#

Kushki-managed 3DS#

Own 3DS engine#

Network Tokens#

Voids & refunds#

Idempotency#

OTP validation & card information#

Payment flow

Integration models

Document types

Deferred payments — Meses Sin Intereses (MSI)

Two-step payments (pre-authorization & capture)

Tokenless payments

3D Secure

Kushki-managed 3DS

Own 3DS engine

Network Tokens

Voids & refunds

Idempotency

OTP validation & card information