Acepta pagos

05 diciembre 2024

Acepta pagos con una terminal POS desde tu punto de venta a través de Cloud terminal API. Cloud terminal API te permite enviar solicitudes a una terminal Ultra P desde cualquier aplicación compatible para procesar un pago.

Con Cloud Terminal API lleva el control de tu operación desde tu sistema y utiliza una terminal como un periférico (pinpad) para leer la información de la tarjeta para procesar un pago.

Modelo de datos de la solicitud

Estos son todos los parámetros que puedes configurar al momento de realizar una solicitud.

Idempotencia

La idempotencia asegura no creen transacciones duplicadas al enviar múltiples solicitudes a la vez. El proceso de idempotencia se maneja automáticamente por el sistema y no requiere ninguna acción por parte del cliente.

Generación de la idempotencia

Para crear una nueva solicitud de pago el cliente debe enviar la clave idempotencia (obligatorio). El idempotencyKey debe ser único para cada solicitud y se puede utilizar para rastrear el estado de la transacción.

A continuación, los datos requeridos para una petición de cobro con idempotencia:

¿Cómo se previenen las solicitudes duplicadas?

• Si se envía la misma solicitud de pago varias veces (por ejemplo, debido a un problema de red o un timeout), el sistema verifica si existe un idempotencyKey asociado a una solicitud anterior dentro de los últimos 10 minutos.
• Si el idempotencyKey ya existe y la solicitud anterior está en estado completed o sent, el sistema no volverá a procesar la transacción.
• Si la solicitud está en estado processing, el sistema indicará que la transacción aún está en proceso, evitando múltiples intentos de pago.
• Timeout de Idempotencia: el sistema mantiene la idempotencia durante un período de 10 minutos desde la creación de la solicitud. Si se detecta una solicitud duplicada dentro de ese período, se ignoran los intentos adicionales para evitar duplicados.

Límite de Solicitudes

Para evitar la saturación del sistema y del terminal, existe un control de flujo sobre las solicitudes de pago.

Cada terminal tiene las siguientes restricciones:

• Máximo de solicitudes pendientes: Un terminal puede tener un máximo de 5 solicitudes pendientes en cola.
• Límite de solicitudes por minuto: Se puede enviar 1 solicitud por minuto. Si se excede este límite, el sistema devolverá un error 429 Too Many Requests.

Operaciones

Descubre todas las operaciones disponibles a través de integraciones por Cloud Terminal API.

Venta

El proceso de venta se inicia cuando un cliente quiere comprar un producto o servicio en tu establecimiento a través de algún medio de pago físico o digital. Durante el proceso, tu sistema punto de venta envía una solicitud de cobro con la configuración necesaria a la aplicación de pagos, la cuál se comunica con la terminal de forma segura para leer, cifrar y enviar la información de la tarjeta de crédito o débito de tu cliente a Kushki para ser procesada. Recibirás la respuesta de la solicitud en la aplicación de pagos. En caso de que la transacción haya sido autorizada de forma exitosa, se descontará el monto autorizado de la cuenta de tu cliente de forma inmediata y posteriormente será liquidado a tu cuenta bancaria de acuerdo al proceso de liquidación. En caso de error, obtendrás más información en la aplicación de pagos y se podrá reintentar nuevamente la solicitud con un método de pago válido.

Envía una solicitud con la configuración de pago desde tu sistema punto de venta hacia el endpoint Collect card payments para realizar una operación de venta.

curl --request POST \
  --url https://integrations.payment.haulmer.com/RemotePayment/v2/Create \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: apiKey' \
  --data '{
  {
  "idempotencyKey": "string",
  "amount": 0,
  "device": "string",
  "description": "string",
  "dteType": 0,
  "extraData": {
    "exemptAmount": 0,
    "customFields": [
      {
        "name": "string",
        "value": "string",
        "print": true
      }
    ],
    "sourceName": "string",
    "sourceVersion": "string"
  }
}
}'

Propina

Añade un monto adicional para propina durante una operación de venta en la aplicación de pagos durante el proceso de pago. Elige entre un monto predefinido o ingresa un monto personalizado. En caso de no requerir agregar propina, da clic fuera del diálogo para continuar.

Pagos diferidos

Incrementa el monto promedio de compra de tus clientes en tu establecimiento ofreciendo la opción de diferir un pago en un número de cuotas establecido. La transacción deberá cumplir con ciertos requisitos para poder ser diferida. Revisa los requisitos con tu gerente de cuenta.

Para diferir un pago, habilita la opción dentro de los ajustes de la aplicación de pagos y selecciona la opción deseada durante el proceso de pago.

Revisa la referencia de Cloud terminal API para información más detallada.

Respuesta

Si la información enviada es correcta, obtendrás un código de estado HTTP 201 indicando que la solicitud se envió correctamente a la terminal.

{
  "idempotencyKey": "ef59617f-7633-4aca-965e-e9993f66bdbc",
  "status": "pending",
  "amount": 1600,
  "deviceId": 690,
  "description": "Servicio de afiliación",
  "extraData": {
    "exemptAmount": 1600,
    "customFields": [
      {
        "name": "Contacto",
        "value": "9 51221345",
        "print": true
      }
    ]
  }
}

Flujo aplicación de pagos

Para poder recibir una solicitud e iniciar el proceso de pago, la terminal deberá estar configurada en Modo integración dentro de los ajustes de la aplicación de pagos.

Al recibir una solicitud, se desplegará la pantalla de pago con el monto configurado. Da clic en el botón Aceptar para continuar con el proceso de pago o da clic en el botón Rechazar para cancelar la solicitud.

En caso de que la opción de Propina esté habilitado dentro de los ajustes de la aplicación de pagos, se desplegará la pantalla de propinas. Elige una opción en pantalla para continuar.

Elige el tipo de tarjeta en pantalla.

En caso de que la opción de Cashback esté habilitada dentro de los ajustes de la aplicación de pagos, se desplegará la pantalla de cashback. Elige una opción en pantalla para continuar.

Posteriormente, se desplegará la pantalla de Opera tu tarjeta indicando el momento en que se debe ingresar el método de pago.

La pantalla para ingresar el PIN aparecerá de acuerdo a las siguientes reglas de seguridad:

• Tarjetas de débito: se solicitará la entrada del PIN para todas las transacciones con tarjetas de débito.
• Tarjeta de crédito:
  • Sin contacto (contactless): se solicitará la entrada de PIN en montos mayores a $20.000.
  • Chip: se solicitará la entrada del PIN independientemente del monto de la transacción.

Después de la autenticación por parte del tarjetahabiente, aparecerá una animación indicando que la información enviada está siendo procesada.

Finalmente, obtendrás el resultado de la solicitud en la pantalla de respuesta.

Al finalizar la operación en la terminal, recibirás un webhook con información útil del resultado de la transacción.