Pago remoto a partir del 28/04/2025*
¿Te interesa integrar pago remoto a tus servicios? Sé parte de nuestros clientes y adquiere un dispositivo POS con nosotros para comenzar 🙌.
🤔 ¿Qué es pago remoto?
El concepto de pago remoto implica que, a través de un webservice, se envía una solicitud de pago a dispositivos POS (Point of Sale), lo que activa de manera remota un flujo en el que el POS se inicia con un conjunto de datos específicos para realizar una transacción con el tarjetahabiente. El POS procesa el pago, y una vez completado el flujo (ya sea exitoso o fallido), se retorna el resultado al sitio web o sistema que realizó la solicitud.
A continuación, se presenta un diagrama de alto nivel que ilustra el flujo del proceso de pago remoto:
Por favor, tener en consideración los sgtes. puntos:
- Confirmar la carga y activación de su POS en Espacio de Trabajo.
- Obtener su API Key desde Espacio de Trabajo para hacer uso de los endpoints de Pago Remoto.
- Generada la solicitud de pago, confirme su recepción en el "Modo Integración" del POS.
🔐 Autenticación y Modo de Integración
Clave API
Toda interacción con los endpoints requiere que el comercio posea una API Key válida. Esta API Key se obtiene directamente desde el Espacio de Trabajo del comercio y es única por comercio.
¿Cómo obtener la API Key?
Dirígete al panel de administración de tu cuenta en el Espacio de Trabajo (Workspace), sección Pagos>Configuración>API.
Modo Integración
Antes de poder interactuar con los endpoints de la API, el terminal debe estar configurado en modo integración. Este modo permite que el terminal quede a la espera de solicitudes de pago externas. Para habilitar este modo, sigue estos pasos:
- Ingrese a la aplicación Pago, realice los pasos que le solicita y posteriormente, se activará una vista de "Activa tu dispositivo".
- Diríjase a tu Espacio de trabajo, selecciona la sección Pagos e ingresa a la opción Pagos Haulmer (barra lateral izquierda).
- Ingresa el código que aparece en tu POS y ¡Activa tu dispositivo!
- Finalmente, seleccione el menú tipo "hamburguesa" y haga clic en la opción "Modo Integración".
Con estos pasos su dispositivo esta listo para recibir solicitudes de pago de forma remota.
📖 Diccionario de datos
Estados de las Solicitudes de Pago
Cada solicitud de pago pasa por varios estados durante su ciclo de vida. A continuación, se describen los posibles estados que puede tener una solicitud de pago:
- Pending: La solicitud ha sido recibida, pero aún no ha sido enviada al Punto de Venta.
- Sent: El intento de pago ha sido enviado al Punto de Venta.
- Canceled: El intento de pago fue cancelado en el Punto de Venta.
- Processing: El sistema está validando el pago con los adquirentes y emisores correspondientes.
- Failed: El sistema rechazó o falló la transacción debido a un error o validación negativa.
- Completed: La transacción fue validada exitosamente, y el pago ha sido completado.
Tabla de conversión de solicitud
| Status | Valor |
|---|---|
| Pending | 0 |
| Sent | 1 |
| Canceled | 2 |
| Processing | 3 |
| Failed | 4 |
| Completed | 5 |
Tabla de conversión DTE
| DTE | Valor |
|---|---|
| 0 | Comprobante afecto. Por defecto |
| 33 | Factura afecta |
| 34 | Factura exenta |
| 48 | Comprobante afecto |
| 99 | Comprobante exento |
API's
Creación de pago (SIN idempotencia):
POST <https://integrations.payment.haulmer.com/RemotePayment/v2/Create>
Header: X-API-Key: XXXConsulta solicitud de pago (SIN idempotencia):
GET <https://integrations.payment.haulmer.com/PaymentRequest/:id>
Header: X-API-Key: XXXCreación de pago (CON idempotencia):
POST <https://integrations.payment.haulmer.com/PaymentRequest/Create>
Header: X-API-Key: XXXConsulta solicitud de pago (CON idempotencia):
GET <https://integrations.payment.haulmer.com/RemotePayment/v2/GetPaymentReques/:idempotency-key>
Header: X-API-Key: XXXCampos de entrada
A continuación se presenta una tabla que describe los principales campos de entrada requeridos para la solicitud de pago en el flujo de integración con el sistema de pago remoto. Estos campos son esenciales para procesar la transacción y deben incluirse en la solicitud.
Campo con * corresponde al flujo con idempotencia (v2)
| Nombre | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| idempotencyKey* | string | Identificador único de la solicitud de pago. | KEY-01 |
| amount | int | Monto total de la transacción. | 1000 |
| device | string | Número de serie del dispositivo POS. | TJ44245N20440 |
| cashbackAmount* | int | Vuelto. | 500 |
| tipAmount* | int | Propina. | 10 |
| paymentMethod* | int | Tipo de método de pago, sea crédito (1) o débito (2) | 1 |
| description | string | Breve descripción de la transacción. | "Pago de servicios" |
| dteType | int | Tipo de documento tributario electrónico. | 99 |
| extradata | object | Información adicional relevante para la transacción, incluyendo montos exentos y campos personalizados. |
Campos del extra data
| Nombre | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| exempAmount | int | Monto exento de impuestos que aplica a la transacción. | 1000 |
| customFields | array | Lista de campos personalizados que contiene información adicional relevante. | |
| sourceName | string | Nombre de origen de la transacción. | "Plataforma de pagos" |
| sourceVersión | string | Versión del origen de la solicitud. | "v1.0.0" |
Campos del CustomFields
| Nombre | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| name | string | Nombre del campo personalizado. | "Contacto" |
| value | string | Valor del campo personalizado | "9 2321 4244" |
| boolean | Indica si el campo debe imprimirse en el comprobante | true |
Tabla de errores
La siguiente tabla describe los errores que pueden generarse durante el proceso de pago. Cada error incluye una descripción y un código que permite identificar el problema y tomar las acciones correctivas necesarias para su resolución por parte del equipo técnico.
Campo con * corresponde al flujo con idempotencia (v2)
| Código | Tipo | Mensaje | Descripción |
|---|---|---|---|
| MR-100 | Dispositivo | Device for API-Key doesn't exist | El dispositivo asociado a la API-Key no existe. |
| MR-110 | Campo de entrada | Transaction Amount is less than allowed minimum | El monto de la transacción es inferior al mínimo permitido. |
| MR-120 | Campo de entrada | Transaction Amount is more than allowed | El monto de la transacción supera el máximo permitido. |
| MR-130 | Campo de entrada | DTE type not recognized | El tipo de DTE proporcionado no es reconocido por el sistema. |
| MR-140 | Campo de entrada | No exempt amount found for DTE Type 99 | No se ha proporcionado un monto exento para el tipo de DTE 99. |
| MR-141 | Campo de entrada | Exempt amount not equal to transaction amount | El monto exento no coincide con el monto total de la transacción. |
| MR-150 | Campo de entrada | Exempt Amount is not less than transaction amount | El monto exento es mayor o igual al monto total de la transacción. |
| MR-151 | Campo de entrada | Exempt Amount is invalid | El monto exento proporcionado no es válido. |
| MR-000 | Autorización | Not Authorized | El usuario no está autorizado para realizar esta operación. |
| MR-160 | Solicitud de pago | Payment Request doesn't exist | No se encontró una solicitud de pago con el ID proporcionado. |
| MR-161 | Dispositivo | Device by SN not found | No se encontró un dispositivo con el número de serie proporcionado. |
| MR-170 | Servicio | Error with Database | Ocurrió un error al intentar acceder a la base de datos. |
| MR-180 | Cola de Solicitudes | Payment Request Queue for the device is full | La cola de solicitudes de pago para el dispositivo está llena. |
| I-04 | Campos Personalizados | ExtraData String has invalid characters | El campo ExtraData contiene caracteres no válidos. |
| INT-MIDDLEWARE-429 | Límite de Solicitudes | API Quota Exceeded! Quota: 0 per 1, Try Again in 2 seconds | Se ha excedido la cuota de solicitudes de la API. |
| I-02 | Campos Personalizados | Custom field length invalid | La longitud de un campo personalizado es inválida. |
| I-03 | Campos Personalizados | Custom field length invalid | La longitud de un campo personalizado es inválida. |
| KEY-002 * | Autenticación | API Key is missing in the request header | Falta la clave API en la cabecera de la solicitud. |
| KEY-003 * | Autenticación | Invalid API Key | La clave API proporcionada no es válida. |
| RP-000 * | Idempotencia | Invalid Idempotency Key | La clave de idempotencia proporcionada es inválida o está mal formada. |
| RP-001 * | Campo de entrada | Idempotency Key length must be between 1 and 36 characters | La longitud de la clave de idempotencia debe estar entre 1 y 36 caracteres. |
| RP-003 * | Campo de entrada | The characters entered are invalid | Los caracteres ingresados en el nombre de origen son inválidos. |
| RP-004 * | Campo de entrada | Invalid characters in source version | Los caracteres ingresados en la versión de origen son inválidos. |
| RP-005 * | Campo de entrada | No exempt amount for specific DTE types | El monto exento no esta permitido para el tipo de DTE ingresado. |
| RP-006 * | Campo de entrada | Exempt amount does not match total | El monto exento no coincide con el total. |
| RP-007 * | Campos Personalizados | Reserved custom field name | El campo personalizado tiene un nombre reservado. |
| RP-008 * | Campo de entrada | Missing payment method | Falta el método de pago. |
| RP-010 * | Campos Personalizados | Maximum custom fields exceeded | La cantidad de campos personalizados supera el máximo permitido. |
| RP-011 * | Campo de entrada | Exempt amount must be less than the total amount | El monto exento debe ser menor que el monto total. |
| RP-012 * | Campo de entrada | Exempt amount exceeds transaction amount | El monto exento excede el monto total. Máximo permitido 99999999. |
| RP-015 * | Campo de entrada | Invalid length | Longitud inválida. La longitud debe ser entre 1 y 28. |
| RP-017 * | Campo de entrada | Amount exceeds maximum allowed | El monto excede el máximo permitido |
| RP-018 * | Campo de entrada | Tip amount must be less than the total amount | La propina debe ser menor que el monto |
| RP-019 * | Campo de entrada | Tip amount exceeds maximum allowed | La propina excede el máximo permitido. Máximo 99999999. |
| RP-020 * | Campo de entrada | Method not permitte | Método de pago no permitido. |
| RP-021 * | Campo de entrada. | Cashback amount must be less than the total amount | El vuelto debe ser menor que el monto total. |
| RP-022 * | Campo de entrada | Cashback amount exceeds maximum allowed | El vuelto excede el máximo permitido. |
| RP-025 * | Campo de entrada | Invalid payment method | Método de pago no válido. |
| RP-026 * | Campos personalizados | Duplicate custom field names | Se encontraron campos personalizados con nombres duplicados. |
| RP-027 * | Campo de entrada | All amounts exceed the maximum allowed | La suma de los montos supera el máximo permitido. |
| RP-028 * | Campo de entrada | Invalid amount, must be equal to or greater than 100 | El monto debe ser mayor o igual a 100. |
| RP-029 * | Pos | Device configuration not found | Configuración del dispositivo no encontrada |
| RP-030 * | Pos | Device settings do not allow tip entry | La configuración del dispositivo no permite la opción de propina. |
| RP-031 * | Pos | The device configuration does not allow the deposit of cashback | La configuración del dispositivo no permite la opción de vuelto. |
| RP-032 * | Pos | Device settings do not support the payment method entered | La configuración del dispositivo no permite la opción del método de pago ingresado. |
| RP-100 * | Autenticación | Unauthorized access. Authentication required. | Acceso no autorizado. Se requiere autenticación. |
| RP-101 * | Autenticación | Invalid or missing Payment Account ID | Cuenta no encontrada. |
| RP-102 * | Autenticación | JWT validation failed | JWT inválido. |
| RP-200 * | Idempotencia | Payment request not found for the provided idempotency key | La solicitud de pago no existe para la clave de idempotencia proporcionada |
| MR-191 * | Idempotencia | The identifier provided is already in use. | La clave de idempotencia ya está en uso para otra solicitud. |
| MR-203 * | Solicitud de pago | Payment request is in process | La solicitud de pago está actualmente en proceso. |
| RP-005 * | Campo de entrada | No exempt amount for specific DTE types | No se especificó un monto exento para los tipos de DTE específicos. |
| RP-006 * | Campo de entrada | Exempt amount does not match total | El monto exento no coincide con el total de la transacción. |
☝️ Consideraciones adicionales
Idempotencia para flujo PaaS
En el sistema de pagos, la idempotencia asegura que múltiples solicitudes con el mismo propósito no creen transacciones duplicadas. 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 utiliza para rastrear el estado de la transacción.
Prevención de 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.
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.
Validaciones de campos
- Amount: El monto de la solicitud de pago debe estar entre 100 y 99999999.
- Device: El número de serie del dispositivo asociado debe ser una cadena válida y registrada.
- Montos Exentos:
- Si el
dteTypees no afecta, se requiere unexemptAmountigual alAmount. - Si el
dteTypees afecta, se requiere unexemptAmountmenor aAmount
- Si el
- Campos Personalizados (Custom Fields):
- Máximo 5 campos personalizados.
- Longitud combinada de name y value no debe exceder los 28 caracteres.
- Caracteres especiales no permitidos "&", "/".
- No utilice caracteres no ASCII.
- DTE Type: Debe ser uno de los valores permitidos: 0, 33, 48 o 99.
🚀 ¿Listo para integrar?
Diríjase a la sección API Reference, específicamente Integración Pago Remoto.
☎️ Contacto y Soporte
Si necesitas soporte adicional o tienes dudas sobre el proceso, nuestro equipo está disponible para ayudarte.
Updated about 16 hours ago