1. Card Payments
Español
  • English
  • Español
  • Docs para desarrolladores 🇪🇨
  • Online Payments
    • Notas de versión
    • Errores del API de Kushki
    • Card Payments
      • Solicitar un token de tarjeta
        POST
      • Hacer un cargo o cargo diferido
        POST
      • Reembolsar una transacción
        DELETE
      • Anular una transacción
        DELETE
      • Solicitar opciones de diferido
        GET
      • Validar OTP
        POST
      • Información de BIN V2
        GET
      • Información de BIN
        GET
    • One Click and Scheduled Payments
      • Solicitar un token de cargo recurrente
      • Crear un cargo recurrente
      • Actualizar los datos de la tarjeta del cargo recurrente
      • Hacer un pago One-click
      • Cancelar un cargo recurrente
      • Actualizar un cargo recurrente
      • Agregar un cargo o descuento temporal
      • Consultar información del cargo recurrente
    • Chargebacks
      • Consultar chargebacks
      • Solicitar exportación de chargebacks
    • Subscription Transactions
      • Consultar transacciones de suscripción
    • Cash in
      • Solicitar un token de Cash In
      • Iniciar transacción
      • Actualizar una transacción de Cash In
      • Estado de la transacción
      • Eliminar una transacción de Cash In
    • Transfer in
      • Solicitar un token de Transfer In
      • Iniciar transacción
      • Consultar estado
    • Analytics
      • Consultar listado de transacciones v2
    • Smartlinks
      • Crear un Smartlink
      • Actualizar un Smartlink
      • Consultar un Smartlink
      • Eliminar un Smartlink
    • Status
      • Consultar estado del gateway
      • Consultar estado de la plataforma
    • Commissions
      • Consultar configuración de comisiones
    • Payment Credentials
      • Crear una credencial
      • Buscar credenciales
      • Activar o desactivar
      • Eliminar credencial
      • Actualizar credencial
      • Regenerar una credencial
      • Búsqueda avanzada
    • Payment Button
      • Crear un Payment Button
    • Settlement
      • Consultar liquidación
  • Appian - Submerchant Register
    • Release Notes
    • Submerchant Validation in Batch
    • Query submerchant status by requestId/submerchantId
    • Get submerchantIds
    • Get credentials for submerchants
  • Schemas
    • threeDomainSecure
    • Card-old
    • Channel
    • SubscriptionTransactionsResponse
    • Card Present (CP)
    • Amount-cash-in
    • webhooks
    • ChargebackListResponse
    • StatusComponent
    • SettlementDateRangeRequest
    • Card
    • networkToken
    • ChargebackItem
    • SettlementRecord
    • Card Not Present (CNP)
    • currency
    • ErrorResponse
    • SubscriptionTransaction
    • Subscription
    • Amount
    • ErrorResponse400
    • SettlementResponse
    • Country
    • Deferred
    • extraTaxes
    • ErrorResponse401
    • Language
    • ErrorResponse403
    • Metadata
    • payment_method
    • ErrorResponse500
    • ContactDetails
    • orderDetails
    • Shipping Address
    • Billing-Address
    • payment_submethod
    • SubscriptionUpdate
    • documentType
    • SubscriptionAdjustmentRequest
    • threeDomainSecure
    • webhooks
    • headers
    • webhooksChargeback
    • citMit
    • network
    • binInfo
    • messageFields
    • UnexpectedErrorResponse
    • ExternalReferenceId
    • product
    • transactionType
    • SettlementTicketRequest
HomePerú 🇵🇪México 🇲🇽Ecuador 🇪🇨
Colombia 🇨🇴Chile 🇨🇱
HomePerú 🇵🇪México 🇲🇽Ecuador 🇪🇨
Colombia 🇨🇴Chile 🇨🇱
  1. Card Payments

Solicitar un token de tarjeta

https://api-uat.kushkipagos.com
https://api-uat.kushkipagos.com
POST
/card/v1/tokens
Solicita un token de tarjeta que luego puedes usar para cobrarle a un cliente mediante el endpoint
charge.
Importante: Si usas esta opción para solicitar el token, asegúrate de cumplir con todos los requisitos PCI para manejar datos de tarjeta en tus servidores.

Expiración del token#

Los tokens expiran en 30 minutos y solo se pueden usar para una única transacción (incluso si la transacción falló). Deberás solicitar un token nuevo cuando expire.
Nota: El token que entrega Kushki solo cifra y envía información. Si quieres almacenar los datos de la tarjeta para compras futuras, revisa la sección One-Click & Scheduled Payments

Autenticación 3D Secure (3DS)*#

Producto en versión beta en Ecuador 🇪🇨 🔐👨‍💻#

Estamos trabajando en la versión beta. ¡Mantente atento a su lanzamiento oficial! También puedes contactar a tu ejecutivo de cuenta para más información.
Para autenticar una tarjeta con 3D Secure, además de la información requerida para generar un token, debes enviar los campos que se listan a continuación
PROPIEDADVALORES POSIBLESDESCRIPCIÓN
authValidationurl iframeDefine el tipo de integración que quieres para la autenticación 3DS. Usa url para redirección o iframe para incrustarla.
callbackUrlstringCallback where the 3D Secure authentication response will be sent.
Si la transacción activa una regla de autenticación 3D Secure en el comercio, además del token se devolverán los campos que se listan a continuación
PROPIEDADVALORES POSIBLESDESCRIPCIÓN
urlstringURL que se debe usar para la autenticación 3D Secure.
secureService3dsecureIndica el servicio de autenticación de la transacción.
secureIdstringID de seguridad de la transacción.
Ejemplo
{
    "token": "sBkQ7F110000tI1HVq116862fd5Ah3mG",
    "url": "https://uat-auth.kushkipagos.com?token=sBkQ7F110000tI1HVq116862fd5Ah3mG&merchantId=306cb10581bb4acb9a2bfc77e163c482&bin=NDM0OTAwMzA=&callbackUrl=https://www.kushkipagos.com/callback/&isSandbox=false",
    "secureService": "3dsecure",
    "secureId": "1f5584db-0c5b-c729-a19c-6eb0283ca448"
}
En el campo url vendrá la url que se debe mostrar al tarjetahabiente para la autenticación 3D Secure, si es necesaria. Para información más detallada, visita la guía 3D Secure API authentication
Para más información sobre 3D Secure, consulta Accept payments with 3DS.
NOTA: Para habilitar 3DS en modo de pruebas en tu comercio, se requiere una configuración adicional que realiza Kushki.

callbackUrl#

La función de callback te indicará si la autenticación 3D Secure fue exitosa o si hubo algún problema durante el proceso. Esta url se llamará automáticamente después de autenticar, mediante una redirección 301 que hace una petición GET a la url enviada en el campo callbackUrl, con los parámetros de la respuesta en la url (path parameters).
Nota: El parámetro booleano success indica si la transacción se autenticó correctamente (true) o si hubo un problema con la autenticación 3D Secure (false). Si es true, puedes proceder con el cargo. Si es false, el tarjetahabiente tendrá hasta 3 intentos para reintentar la autenticación antes de que la transacción se rechace.
PROPIEDADTIPODESCRIPCIÓN
successbooleanIndica si la autenticación 3D Secure fue exitosa o no.
tokenstringToken que devuelve Kushki para usarlo al hacer un cargo, en caso de que la autenticación 3D Secure haya sido exitosa.
messagestringSi hay un problema durante la autenticación, aquí se devolverá el motivo.
Ejemplo de callback de autenticación exitosa#
https://www.tutienda.com/?success=true&token=cfa0bfec88324bd7a5c6c1ad9135a846
Ejemplo de callback con problema de autenticación#
https://www.tutienda.com/?success=false&message=Error%20en%20la%20validación%20de%203DS&token=cfa0bfec88324bd7a5c6c1ad9135a846

Request

Header Params

Body Params application/json

Examples

Responses

🟢201Created
application/json
TokenCreated
Bodyapplication/json

🟠400Bad Request
🟠402
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/card/v1/tokens' \
--header 'Public-Merchant-Id;' \
--header 'Content-Type: application/json' \
--data '{
    "card": {
        "name": "John Doe",
        "number": "5451951574925480",
        "expiryMonth": "08",
        "expiryYear": "28",
        "cvv": "121"
    },
    "totalAmount": 16.98,
    "currency": "USD"
}'
Response Response Example
201 - Successful request
{
    "token": "3c1518cf6f844e248880aad6187cf8d7"
}
Modified at 2026-09-11 15:01:40
Previous
Card Payments
Next
Hacer un cargo o cargo diferido
Built with