1. Card Present Payment Services
Español
  • English
  • Español
  • Docs de API 🇲🇽
  • Online Payments
    • Errores ISO
    • Errores del API de Kushki
    • Notas de versión
    • Card Payments
      • Solicitar un token de tarjeta
      • Hacer un cargo o cargo diferido
      • Crear pago (sin token)
      • Solicitar opciones de diferido
      • Reembolsar una transacción
      • Autorizar pagos
      • Preautorización (sin token)
      • Anular una transacción
      • Reautorizar pagos
      • Capturar un pago autorizado
      • Información de BIN V2
      • Información de BIN
      • Validar OTP
    • One-Click and 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
    • Transfer in
      • Consultar lista de bancos
      • Solicitar un token de Transfer In
      • Iniciar transacción
      • Consultar estado
    • 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
    • Smartlinks
      • Crear un Smartlink
      • Consultar un Smartlink
      • Eliminar un Smartlink
      • Actualizar un Smartlink
    • Payment Button
      • Crear un Payment Button
    • Analytics
      • Consultar listado de transacciones v2
    • Chargebacks
      • Consultar chargebacks
      • Solicitar exportación de chargebacks
    • Commissions
      • Consultar configuración de comisiones
    • Payment Credentials
      • Crear una credencial
      • Activar o desactivar
      • Eliminar credencial
      • Regenerar una credencial
      • Actualizar credencial
      • Búsqueda avanzada
      • Buscar credenciales
    • Platform Status
      • Consultar estado de la plataforma
      • Consultar estado del gateway
    • Settlement
      • Consultar liquidación
    • Subscription Transactions
      • Consultar transacciones de suscripción
    • Fraud Report
      • Consultar alertas de fraude
  • Card Present Billpocket
    • Notas de versión
    • Notas de versión del SDK de Android
    • Notas de versión de la app de Android
    • Notas de versión de la app de iOS
    • Get Started
      • Crear una cuenta
      • User Token
      • API Keys
    • Webhooks
      • Webhooks — Transferencia de fondos a tu cuenta bancaria
      • Errores de transferencia de fondos
    • Terminals
      • App Review
      • Splash Screen
    • Card not Present Billpocket Services
      • 3DS Checkout
        • Crear checkout
        • Consultar detalles del checkout
      • E-commerce Flex
        • Obtener token
        • Validar token
        • Cobrar pagos
        • Reembolso
        • Capturar un pago autorizado
        • Consultar estado
    • Catalogs
      • Estados
      • Municipios
      • Empresas de impuestos
      • Actividades comerciales
    • Accounts
      • Clabe Account Setup
        • Agregar cuenta CLABE
      • Deposit Accounts
        • Agregar o actualizar cuenta CLABE
    • User Settings
      • Crear usuario
    • Card Present Payment Services
      • Cloud Terminal API
        • Cobrar pagos con tarjeta
        • Imprimir ticket
        • Cancelar notificación push
        • Consultar estado de la transacción
        • Cobrar pagos con tarjeta v2
      • App-to-App
        • Android intents
        • App to App — iOS
        • App to App — Mobile Web
      • Terminal SDK
        • Terminal SDK Android
        • Errores del SDK de Android
    • Transactions
      • Transaction List
        • Obtener token
        • Consultar listado de transacciones
        • Consultar listado de transacciones v2
        • Consultar listado de transacciones v3
        • Consultar listado de transacciones v4
      • Cancel Payments
        • Códigos de error de cancelación
        • Cancelar pagos
  • API Raw Card Present
    • El objeto Amount
    • Catálogo de errores
    • Proceso de intercambio de llaves
    • Notas de versión
    • Datos de prueba
    • One-time payments
      • Pago único
    • Two-step-payments
      • Autorización y captura
    • Voids & Refunds
      • Reembolsar una transacción
      • Anular y reversar
    • Card information
      • Consultar información de BIN
      • Información de BIN V2
      • Solicitar opciones de diferido
    • Query Transactions
      • Búsqueda de transacciones
    • Webhooks
      • Webhooks — Pagos con tarjeta
      • Webhooks — Reembolsos
      • Webhooks — Introducción
      • Buenas prácticas
      • Revisa tus webhooks
    • Chargebacks
      • Consultar chargebacks
      • Solicitar exportación de chargebacks
    • 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)
  • Appian - Submerchant Register
    • Release Notes
    • Submerchant Validation in Batch
    • Query submerchant status by requestId/submerchantId
    • Submerchant Document Upload
    • Get submerchantIds
    • Get credentials for submerchants
  • Schemas
    • RequestBodies
      • one-and-two-step-payment
    • Card
    • Channel
    • Amount-cash-in
    • ChargebackListResponse
    • TransactionResponse
    • PrintJobRequest
    • one-and-two-step-payment-2
    • Card Present (CP)
    • one-and-two-step-payment-2
    • SubscriptionTransactionsResponse
    • FraudAlertRequest
    • StatusComponent
    • SettlementDateRangeRequest
    • amount
    • ChargebackItem
    • SubscriptionTransaction
    • extra_taxes
    • RawResponse
    • CommandText
    • Card Not Present (CNP)
    • Deferred
    • networkToken
    • FraudAlertResponse
    • ErrorResponse400
    • SettlementRecord
    • card
    • CardData
    • CommandColumns
    • FraudAlertRecord
    • SettlementResponse
    • currency
    • webhooksItem
    • ErrorResponse
    • Country
    • ErrorResponse401
    • LinkFailure
    • ColumnItem
    • ValidationError
    • Amount
    • card_details
    • ErrorResponse403
    • enc_tlv
    • CommandDivider
    • TransactionEvent
    • extraTaxes
    • payment_method
    • ErrorResponse500
    • CommandFeed
    • TransactionStatus
    • deferred
    • CommandSpace
    • ReadingType
    • pos_details
    • ContactDetails
    • sub_merchant
    • CommandCut
    • FailureReason
    • contact_details
    • Subscription
    • metadata
    • CommandImage
    • EventTerminal
    • documentType
    • orderDetails
    • Language
    • TransactionSearchRequest
    • CommandQR
    • EventOperation
    • Shipping Address
    • payment_submethod
    • CommandBarcode
    • EventAmount
    • Billing-Address
    • SubscriptionUpdate
    • EventExtraTaxes
    • PrintJobAccepted
    • PrinterError
    • EventMetadata
    • SubscriptionAdjustmentRequest
    • product
    • AmountWithTaxes
    • PrintJobStatus
    • PrintJobStatusRequest
    • threeDomainSecure
    • AmountCore
    • webhooks
    • headers
    • ExtraTaxes
    • PrintWebhookPayload
    • webhooksChargeback
    • Metadata
    • 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
HomePerú 🇵🇪México 🇲🇽
Ecuador 🇪🇨Colombia 🇨🇴Chile 🇨🇱
HomePerú 🇵🇪México 🇲🇽
Ecuador 🇪🇨Colombia 🇨🇴Chile 🇨🇱
  1. Card Present Payment Services

Cloud Terminal API

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.
Crea nuevas experiencias de pago con tarjeta en tu negocio. Cloud Terminal API te permite integrar una terminal a tu sistema de punto de venta (POS) de forma sencilla y segura mediante una API REST, y te da control directo desde tu sistema al momento de hacer un pago con tarjeta. No necesitas ninguna conexión física: tu POS se comunica con la terminal a través de internet, y la terminal se encarga de la lectura de la tarjeta, del procesamiento EMV y de la impresión del comprobante.
Esta guía cubre todo lo que necesitas para procesar pagos con tarjeta en la terminal.
INFO
Servicio disponible solo en México 🇲🇽.
cloud-terminal-api.png

Características principales#

Fácil de integrar: integra una terminal en cualquier plataforma y en cualquier dispositivo que permita hacer peticiones HTTP.
Escalable: la arquitectura de la API te permite escalar y agregar terminales según tus necesidades, sin mayor dificultad.
Control: gestiona toda tu operación desde tu POS. Delega en nuestras terminales las operaciones de pago de tu POS.
Seguridad: la comunicación con nuestras terminales está cifrada en todo momento para proteger la información sensible, conforme a los estándares más estrictos de la industria.

Requisitos#

Antes de hacer la integración, debes cumplir los siguientes requisitos:
Un lector Ultra, Ultra P o Ultra SE
Una cuenta válida
La app POS instalada en la terminal, versión 4.3.26 o superior
Una conexión a internet estable
Firewalls y servicios similares configurados para permitir la comunicación con los dominios que se describen abajo

Entornos#

Puedes simular pruebas en el entorno Dev para hacer los ajustes necesarios en tu sistema. Recuerda que en este entorno no se procesan transacciones reales. Elige el entorno correcto para enviar notificaciones a la terminal desde tu POS.
EntornoURL base
Devhttps://kushkicollect.billpocket.dev
Livehttps://kushkicollect.billpocket.com

Autenticación#

Todas las peticiones requieren un token de usuario válido en la cabecera X-BP-AUTH:
Consulta nuestra guía para obtener tu token de usuario.
Nota
Recuerda usar el token de usuario correcto según el entorno.
Importante
Guarda tu token de usuario en un lugar seguro. Nunca lo compartas ni lo expongas a terceros.

Endpoints disponibles#

MétodoRutaOperación
POST/push-notificationsCollect card payments
POST/v2/push-notificationsCollect card payments v2
POST/print-ticketPrint ticket
POST/cancel-transactionCancel push notification
GET/get-status/?uniqueReferenceGet transaction status

Cómo funciona#

1.
Tu POS envía la solicitud de pago a la Cloud Terminal API con el número de serie de la terminal y el monto.
2.
La API procesa la solicitud y la reenvía a la terminal como una notificación push.
3.
El tarjetahabiente presenta su tarjeta; la terminal lee y cifra la información de la tarjeta y la envía a procesar.
4.
Kushki procesa la transacción y la aprueba o la declina.
5.
Kushki notifica la respuesta a tu POS mediante un webhook, para que puedas continuar el flujo de pago en tu comercio.

Procesa un pago#

Sigue estos pasos para procesar pagos con Cloud Terminal API.

Cobra un pago#

Para enviar una solicitud de pago a la terminal desde tu POS, consume el endpoint Collect card payments o Collect card payments v2, enviando:
El número de serie de la terminal seleccionada.
Un monto mayor a $1 MXN.
Un identificador de hasta 256 caracteres, generado de tu lado, que te da trazabilidad de la transacción. Este valor se te devuelve mediante el webhook.
v1:
{
   "serial_number": "TERM1TEST",
   "amount": 27,
   "identifier": "identificador 1"
}
v2:
{
   "serialNumber": "TERM1TEST",
   "amount": 27,
   "identifier": "identificador 1"
}

Cobra un pago con propina#

También puedes cobrar propinas si envías la propiedad tip al momento de la solicitud:
v1:
{
   "serial_number": "TERM1TEST",
   "amount": 27,
   "tip": 1.5,
   "identifier": "identificador 1"
}
v2:
{
   "serialNumber": "TERM1TEST",
   "amount": 27,
   "tip": 1.5,
   "identifier": "identificador 1"
}
Visita los endpoints Collect card payments y Collect card payments v2 para ver más detalles sobre las propiedades disponibles al momento de una solicitud y para probar la llamada desde tu navegador.

Respuesta#

Si la información enviada es correcta, recibes un código de estado HTTP 201 Created, que indica que la notificación se envió correctamente a la terminal.
Nota
Recuerda que la terminal debe estar conectada a internet para recibir notificaciones.

En la terminal#

Recibes una notificación con la información enviada. Desliza la barra de notificaciones y toca la notificación para abrir la aplicación POS.
pushNotification.png
En la aplicación POS aparece la pantalla de pago. Si la información que se muestra es correcta, toca el botón COBRAR para continuar con el pago.
VentanaCobro.png
Sigue los pasos en pantalla para leer y procesar la información de la tarjeta. Una vez procesada la transacción, se envía un webhook con su estado.

Siguientes pasos#

Descubre cómo configurar un webhook para recibir el estado de la transacción una vez procesada.
Webhooks
Recibe el resultado de la transacción una vez que la terminal procesa el pago.
Listado de transacciones
Consulta las transacciones procesadas para tu conciliación.
Anulación de pagos
Anula una transacción autorizada el mismo día hábil.

¿Tienes alguna sugerencia sobre esta documentación? Escríbenos.
Modified at 2026-09-10 16:05:48
Previous
Card Present Payment Services
Next
Cobrar pagos con tarjeta
Built with