1. API Raw Card Present Payments
Español
  • English
  • Español
  • Docs de API 🇨🇴
  • Online Payments
    • Errores del API de Kushki
    • Errores ISO
    • Notas de versión
    • Card Payments
      • Solicitar un token de tarjeta
      • Hacer un cargo o cargo diferido
      • Crear pago (sin token)
      • Anular una transacción
      • Reembolsar una transacción
      • Solicitar opciones de diferido
      • Autorizar pagos
      • Preautorización (sin token)
      • Reautorizar pagos
      • Capturar un pago autorizado
      • Verificar cuenta
      • Validar OTP
      • Información de BIN
      • Información de BIN V2
    • One-Click & Scheduled Payments
      • Solicitar un token de cargo recurrente
      • Crear un cargo recurrente
      • Hacer un pago One-click
      • Actualizar los datos de la tarjeta del cargo recurrente
      • Cancelar un cargo recurrente
      • Actualizar un cargo recurrente
      • Agregar un cargo o descuento temporal
      • Autorizar pagos
      • Capturar un pago autorizado
      • Consultar información del cargo recurrente
    • Chargebacks
      • Consultar chargebacks
      • Solicitar exportación de chargebacks
    • Transfer in
      • Consultar lista de bancos
      • Solicitar un token de Transfer In
      • Iniciar transacción
      • Consultar estado
      • Cancelar transacción
    • Transfer out
      • Consultar lista de bancos
      • Consultar lista de bancos V2
      • Solicitar un token de Transfer Out
      • Iniciar transacción
      • Consultar estado
      • Saldo para payouts
    • Cash in
      • Solicitar un token de Cash In
      • Iniciar transacción
      • Estado de la transacción
      • Eliminar una transacción de Cash In
      • Actualizar una transacción de Cash In
    • Cash-out
      • Solicitar un token de Cash Out
      • Iniciar transacción
      • Estado de la transacción
      • Actualizar una transacción de Cash Out
      • Eliminar una transacción de Cash Out
    • Smartlinks-v2
      • Crear un Smartlink
      • Consultar un Smartlink
      • Actualizar un Smartlink
      • Eliminar un Smartlink
    • Analytics
      • Consultar listado de transacciones v2
    • Gateway-status
      • Consultar estado del gateway
      • Consultar estado de la plataforma
    • Payment Credentials
      • Crear una credencial
      • Buscar credenciales
      • Búsqueda avanzada
      • Eliminar credencial
      • Regenerar una credencial
      • Activar o desactivar
      • Actualizar credencial
    • Payment Button
      • Crear un Payment Button
    • Settlement
      • Consultar liquidación
    • Subscription Transactions
      • Consultar transacciones de suscripción
    • Fraud Report
      • Consultar alertas de fraude
  • Kushki One
    • Error Catalog
    • Release notes
    • Transaction Examples
    • Webhooks
    • Cloud Services
      • Payment
        • Sync
          • Charge
          • Authorization (Pre-auth)
          • Capture
          • Re-authorization
          • Post-tip
          • Void
          • Refund
          • Abort
        • Async
          • Charge (Async)
          • Authorization — Pre-auth (Async)
          • Capture (Async)
          • Re-authorization (Async)
          • Post-tip (Async)
          • Void (Async)
        • Search
          • Transaction Search
      • Print
        • Create Print Job
        • Get Print Job Status
    • Local Services
      • Payment
        • Sync
          • Charge
          • Authorization (Pre-auth)
          • Capture
          • Re-authorization
          • Post-tip
          • Void
          • Refund
          • Abort
        • Async
          • Charge (Async)
          • Authorization — Pre-auth (Async)
          • Capture (Async)
          • Re-authorization (Async)
          • Post-tip (Async)
          • Void (Async)
          • Abort (Async)
        • Search
          • Transaction Search — Online
          • Transaction Search — Local
      • Print
        • Create Print Job
        • Get Print Job Status
        • Print Job Webhook (inbound — implemented by your POS)
  • API Raw Card Present Payments
    • Notas de versión
    • Catálogo de errores
    • El objeto Amount
    • Proceso de intercambio de llaves
    • Datos de prueba
    • One-time Payments
      • Pago único
    • Two-step Payments
      • Autorización y captura
    • Card Information
      • Consultar información de BIN
      • Información de BIN V2
      • Solicitar opciones de diferido
    • Voids & Refunds
      • Anular y reversar
      • Reembolsar una transacción
    • Query Transactions
      • Búsqueda de transacciones
    • Webhooks
      • Introducción
      • Buenas prácticas
      • Webhooks-Pagos con tarjeta
      • Webhooks-Reembolsos
      • Revisa tus webhooks
    • Chargebacks
      • Consultar chargebacks
      • Solicitar exportación de chargebacks
    • Fraud Report
      • Consultar alertas de fraude
  • Appian - Submerchant Register
    • Release Notes
    • Submerchant Validation in Batch
    • Query submerchant status by requestId/submerchantId
    • Get submerchantIds
    • Get credentials for submerchants
  • Schemas
    • RequestBodies
      • one-and-two-step-payment
    • Card
    • Channel
    • ChargebackListResponse
    • TransactionResponse
    • PrintJobRequest
    • card
    • one-and-two-step-payment-3
    • Card Present (CP)
    • one-and-two-step-payment-3
    • SubscriptionTransactionsResponse
    • Amount-cash-in
    • SettlementDateRangeRequest
    • amount
    • FraudAlertRequest
    • SubscriptionTransaction
    • ChargebackItem
    • SettlementRecord
    • RawResponse
    • CommandText
    • Card Not Present (CNP)
    • networkToken
    • FraudAlertResponse
    • ErrorResponse400
    • CardData
    • CommandColumns
    • extra_taxes
    • FraudAlertRecord
    • ErrorResponse
    • currency
    • Deferred
    • webhooksItem
    • SettlementResponse
    • ErrorResponse401
    • LinkFailure
    • ColumnItem
    • Amount
    • ValidationError
    • pos_details
    • ErrorResponse403
    • CommandDivider
    • enc_tlv
    • TransactionEvent
    • extraTaxes
    • card_details
    • Country
    • payment_method
    • ErrorResponse500
    • CommandFeed
    • TransactionStatus
    • deferred
    • CommandSpace
    • ReadingType
    • contact_details
    • ContactDetails
    • CommandCut
    • sub_merchant
    • FailureReason
    • CommandImage
    • metadata
    • EventTerminal
    • documentType
    • Subscription
    • orderDetails
    • Language
    • TransactionSearchRequest
    • CommandQR
    • EventOperation
    • Shipping Address
    • payment_submethod
    • CommandBarcode
    • EventAmount
    • Billing-Address
    • EventExtraTaxes
    • PrintJobAccepted
    • PrinterError
    • EventMetadata
    • SubscriptionUpdate
    • AmountWithTaxes
    • PrintJobStatus
    • PrintJobStatusRequest
    • threeDomainSecure
    • SubscriptionAdjustmentRequest
    • AmountCore
    • product
    • webhooks
    • headers
    • ExtraTaxes
    • PrintWebhookPayload
    • Metadata
    • webhooksChargeback
    • AmountWithTip
    • citMit
    • TransactionSearchBody
    • TransactionSearchOnlineBody
    • network
    • binInfo
    • AmountWithOptionalTip
    • TransactionSearchLocalBody
    • TransactionEvent_2
    • messageFields
    • UnexpectedErrorResponse
    • FailureReason_2
    • transactionType
    • ExternalReferenceId
    • EventTerminal_2
    • ExternalSubscriptionId
    • EventOperation_2
    • EventAmount_2
    • EventExtraTaxes_2
    • EventMetadata_2
    • SettlementTicketRequest
    • ErrorResponse
    • TransactionEvent_23
    • TransactionStatus4
    • ReadingType5
    • FailureReason_26
    • EventTerminal_27
    • EventOperation_28
    • EventAmount_29
    • EventMetadata_210
    • EventExtraTaxes_211
    • PrintWebhookPayload12
    • TransactionEvent13
    • FailureReason14
    • EventTerminal15
    • EventOperation16
    • EventAmount17
    • EventMetadata18
    • EventExtraTaxes19
HomePerú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴
Chile 🇨🇱
HomePerú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴
Chile 🇨🇱
  1. API Raw Card Present Payments

Proceso de intercambio de llaves

Producto en versión beta 🔐#

Estamos trabajando en nuestra versión beta. ¡Mantente al tanto de su lanzamiento oficial! También puedes contactar a tu ejecutivo de cuenta para más información.
Para obtener las llaves criptográficas de trabajo que se usarán en el proceso de derived unique key per transaction (DUKPT), Kushki y el cliente realizarán las actividades que se detallan a continuación:

Acuerdos y condiciones iniciales#

Existe una sesión entre Kushki y el comercio donde se revisan las condiciones para intercambiar llaves con terceros. Este proceso requiere que el proveedor de HSM del comercio acepte los términos de la ceremonia de intercambio de llaves. Si se acepta, establecen los mecanismos de trabajo y los canales seguros para intercambiar información sensible entre Kushki y el comercio, además de definir al menos dos security officers (SOs) por parte del comercio.
NOTA: El comercio debe contar con un hardware security module (HSM) debido al proceso de intercambio de llaves criptográficas.

Condiciones con terceros:#

El comercio debe estar preparado para intercambiar componentes con el proveedor de HSM en nombre de Kushki. A continuación, los pasos a seguir:
Firmar el NDA del proveedor de HSM de Kushki y tener acceso al portal;
Crear y mantener SOs con datos de contacto correctos y grupos de SOs en el portal;
Estar preparado para seguir el proceso de intercambio de llaves tal como se define en esta documentación.

Solicitud y validación de la documentación requerida#

Kushki solicita la documentación requerida para registrar al comercio en el servicio de HSM en nombre de Kushki y para registrarlo en la Kushki Console. Una vez obtenida la documentación solicitada, el proceso continúa.
Kushki recibe y valida la documentación solicitada.

Generación y envío de los componentes de una Key Encryption Key (KEK)#

Kushki genera y envía tres componentes de llave para la key encryption key (KEK), así como su respectivo Key Checksum Value (KCV) para el checksum de cada llave criptográfica, por los medios seguros establecidos arriba a los security officers definidos previamente. Al solicitar el envío de los componentes, los SOs que reciben los componentes recibirán un correo con lo siguiente:
Información de referencia de la llave
Datos de contacto (sin incluir la dirección) del SO remitente correspondiente
Los detalles del envío y el número de serie de la bolsa con evidencia de manipulación
Un link a la página del Portal donde se debe completar el checklist tras la recepción
NOTA: Según el entorno de trabajo, Kushki puede enviar las KEK de forma electrónica o física.
Para que Kushki realice el intercambio de llaves, los custodios de seguridad (SOs) deben:
Estar registrados en el portal del servicio de HSM de Kushki.
Cada uno de los SOs que participa en el intercambio debe tener una cuenta activa en el portal del servicio de HSM de Kushki.
Deben estar ubicados en los grupos de SO correctos (1, 2 o 3).
Deben mantener actualizada la dirección de envío de los componentes físicos.
Al momento de registrar al SO en el portal, recibirá información sobre su cuenta en el portal del proveedor de HSM de Kushki, que será útil más adelante.

Pruebas#

Kushki puede enviar los componentes de la KEK por medios electrónicos seguros (correo, bóveda de seguridad, SFTP). Un ejemplo puede ser por correo cifrado. El comercio recibirá la información en una tabla como la siguiente:
ID DE LLAVEDESCRIPCIÓNALGORITMOLONGITUDLLAVE/COMPONENTE EN TEXTO CLAROKCV
ZMKComponente 13DESdobleA2F2 9E20 4515 D531 6B2C 32BC 3E58 612FEF0F99
Double-lenComponente 23DESdobleBA1F 23CD 8529 2C7A 51EC 07A2 EA8A C11FF23EFF
Componente 33DESdobleF70D 38D6 E557 A176 BC4F 1002 3D4C 01E9C41DBB

Producción#

Kushki enviará tres sobres de seguridad, cada uno con un componente de llave impreso en papel, a al menos dos custodios de seguridad que no reporten a la misma persona.
NOTA: El envío de los componentes suele tomar aproximadamente dos semanas, según la ubicación de los SOs.
El comercio recibe los componentes y los checksums de cada llave para poder cargarlos y validarlos en su HSM. Si la verificación fue exitosa, el comercio debe:
Informar a Kushki que la carga fue exitosa enviando un correo a la dirección seguridad@kushkipagos.com con “KEK component check successful - [MERCHANT_NAME]” en el asunto y “Check successful” en el mensaje.
Se pedirá a los SOs completar el checklist de confirmación de recepción a través del Portal del Proveedor del Servicio de HSM de Kushki que llegará por correo, siguiendo las instrucciones allí indicadas.
En caso de cualquier problema con la validación, debes informar a Kushki a la misma dirección de correo.
NOTA: Una vez que el componente ha sido activado en el portal del servicio de HSM de Kushki, es necesario que los SOs lo destruyan.

Generación y envío de la Base Derivation Key (BDK)#

Kushki registra al comercio en la Kushki Console, donde el comercio puede obtener su merchant_id, su llave privada de seguridad para transar (Private-Credential-Id), entre otra información relevante. Una vez registrado el comercio, Kushki generará dos base derivation keys (BDK), una para data y otra para pin (pin_block), que se intercambiarán de forma cifrada con la KEK en TR-31. El intercambio será por medios electrónicos seguros.
Ejemplo de una BDK cifrada con una KEK en formato TR-31:
RD0112B0TX00N00004FD842D565C0BDD9741A3EAB5106A78087A4D0729A56319F32AF9FBFC6FAE0A184DA40D08FA279FBB50E7598936AD18F
NOTA: Las BDK del entorno de producción se compartirán por medios electrónicos seguros (por ejemplo, 1password).
Una vez obtenidas las BDK, el comercio debe ejecutar sus procesos internos para la gestión de las terminales POS con el proceso DUKPT.
Modified at 2026-09-11 15:24:55
Previous
El objeto Amount
Next
Datos de prueba
Built with