Funciones adicionales
Recuerda que estas llamadas API serán peticiones HTTP POST a un la dirección TCP/IP donde está instalado el DeviceHub. Normalmente esta dirección será:
POST http://localhost:17000
Existen llamadas especiales que ofrecen su funcionalidad a través del contenido del propio mensaje XML. Son conocidas como CallSpecificFunction. Tienen los mismos elemementos comunes que todas las llamadas: ClientIdValue, ... pero además todas las de este tipo tienen los siguientes parámetros comunes:
- Function
- Modifier
- Parameter 1
- Parameter 2
- Parameter 3
A continuación incluimos un ejemplo genérico a modo de prototipo:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
<soap:Header/>
<soap:Body>
<tem:CallSpecificFunctionRequest>
<tem:Header>
<tem:ClientId>ClientIdValue</tem:ClientId>
<tem:StoreId>StoreIdValue</tem:StoreId>
<tem:PosId>PosValue</tem:PosId>
<tem:Lang>Idioma</tem:Lang>
<tem:ExtraData1></tem:ExtraData1>
</tem:Header>
<tem:Function>FunctionCode</tem:Function>
<tem:Modifier>FunctionModifier</tem:Modifier>
<tem:Parameter1>Parameter1</tem:Parameter1>
<tem:Parameter2>Parameter1</tem:Parameter2>
<tem:Parameter3>Parameter3</tem:Parameter3>
</tem:CallSpecificFunctionRequest>
</soap:Body>
</soap:Envelope>
Devoluciones referenciadas [BeginDevolution]
En este caso, teniendo un importe y un número de ticket, se lanza la transacción de devolución, solicitando la autorización financiera. El código de respuesta refleja si la petición ha sido entregada al servicio device hub. Para obtener el resultado de la transacción, es necesario utilizar la función GetNextMessage.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
<soap:Header/>
<soap:Body>
<tem:BeginDevolutionRequest>
<tem:Header>
<tem:ClientId>ClientIdValue</tem:ClientId>
<tem:StoreId>StoreIdValue</tem:StoreId>
<tem:PosId>PosIdValue</tem:PosId>
<tem:Lang>Idioma</tem:Lang>
<tem:ExtraData1></tem:ExtraData1>
</tem:Header>
<tem:Amount>Importe</tem:Amount>
<tem:TicketNumber>TicketNumber</tem:TicketNumber>
</tem:BeginDevolutionRequest>
</soap:Body>
</soap:Envelope>
Petición: BeginDevolutionRequest
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Header | Header | Datos utilizados durante las siguientes consultas. |
String | Amount | Importe de la devolución. Importe de la operación con 10 dígitos numéricos, dónde los dos últimos dígitos representan los céntimos.Ej.: 1€ -> 0000000100; 2,25€-> 0000000225 |
String | TicketNumber | Número de recibo de la devolución. |
Header
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
String | Clientid | Identificador del comercio. |
String | Storeid | Identificador de la tienda. |
String | Posid | Identificador del Terminal Punto de Venta. |
String | Language | Identificador del idioma: 0 Español 1 English. |
String | ExtraData1 | No usado. |
Nota: El campo Posid no debe superar los 30 caracteres y se recomienda no usar los siguientes símbolos dentro del campo
{"/","\"}
Parámetros de Salida
Respuesta: BeginDevolutionResponse
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Result | Result | Retorna 0=OK o un código de error y su descripción. |
Result
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Int | Code | Código de error. |
String | Descripción | Descripción del error. |
Información sobre la impresión del ticket
El software de caja deberá incluir una serie de datos para la impresión del ticket. Los campos obligatorios y opcionales son los siguientes:
CAMPOS OBLIGATORIOS RECIBO DE DEVOLUCIÓN |
---|
Tipo de operación |
Nombre del establecimiento |
Ciudad del establecimiento |
Nº de tarjeta sustituyendo los 12 primeros dígitos por '*' |
Etiqueta de la aplicación con la siguiente prioridad 'ApplicationLabel(T50),'Etiqueta del terminal'(Solo si la operación se realizó con tarjeta EMV) |
Fecha y hora de la operación (DDMMAA hhmm) |
Nº de autorización |
Importe de la operación con indicación de moneda |
Recibo para el comercio: Indicar que se trata de una copia y que es para el establecimiento |
Recibo para el cliente: Recuadro de firma del establecimiento indicando que el recibo es para el cliente |
Resto de copias: Indicar que se trata de una copia |
CAMPOS OPCIONALES |
---|
Titular (hay empresas que lo incluyen y otras no) |
Centro autorizador |
Pasarela de pagos |
La impresión del ticket dependerá del modelo de Pin Pad utilizado:
- PIN Pad fijos (integrados): La impresión y los campos del ticket dependen del TPV.
- PIN Pad inalámbricos (stand-alone): La impresión y los campos del ticket depende de la pasarela de Sipay.
IMPORTANTE: Hay que tener en cuenta que la impresión del ticket representa la finalización de la transacción. En caso de que no se produzca la impresión del ticket (en el TPV o en el mismo PIN Pad), la operación no se habrá terminado, siendo necesario el envío de una cancelación de la operación en curso, por parte del TPV.
- Para aquellos comercios que deseen trabajar con devolución con comprobación (devolución asociada a una venta cuyo importe nunca podrá superar el de la venta original), deberán solicitar la configuración a Sipay. El número de ticket deberá ser igual al de la venta original. La devolución con comprobación tiene un plazo máximo de devolución de 3 meses.
Carga de fichero 3000 [CallSpecificFunction 20]
Esta operativa permite la carga de un fichero 3000 de configuración a los PIN Pads (fichero facilitado por Sipay Plus). Durante el proceso no se pueden realizar operaciones financieras.
El fabricante, recomienda el borrado de los parámetros actuales antes de realizar una carga de fichero 3000. Este borrado debe ser realizado por el teclado del dispositivo, por lo que en caso de necesitar más información, debes ponerte en contacto con el equipo de soporte de Sipay.
Parámetros:
Los datos de Header deben ser iguales que en todas las transacciones.
- Function: 20
- Modifier: 0
- Parameter1: Path y nombre del fichero 3000 a cargar.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
<soap:Header/>
<soap:Body>
<tem:CallSpecificFunctionRequest>
<tem:Header>
<tem:ClientId>ClientIdValue</tem:ClientId>
<tem:StoreId>StoreIdValue</tem:StoreId>
<tem:PosId>PosIdValue</tem:PosId>
<tem:Lang>Idioma</tem:Lang>
<tem:ExtraData1></tem:ExtraData1>
</tem:Header>
<tem:Function>20</tem:Function>
<tem:Modifier>0</tem:Modifier>
<tem:Parameter1>C:\path\to\file.txt</tem:Parameter1>
<tem:Parameter2></tem:Parameter2>
<tem:Parameter3></tem:Parameter3>
</tem:CallSpecificFunctionRequest>
</soap:Body>
</soap:Envelope>
Carga de claves PINOnline [CallSpecificFunction 4]
Parámetros:
Los datos de Header deben ser iguales que en todas las transacciones.
- Function: 4
- Modifier: 0
- Parameter1: Numero del cajón a actualizar (1.9).
- Parameter2: No utilizado.
- Parameter3: No utilizado.
Esta funcionalidad solamente se utiliza en los dispositivos que trabajan con PINOnline, y provoca la petición de la actualización de las claves con la entidad procesadora.
Se debe utilizar cuando lo solicite la entidad autorizadora o cuando se vaya a realizar una carga inicial de PINOnline en un dispositivo compatible. Para llevar a cabo esta acción debes ponerte en contacto con el equipo de soporte de Sipay, pues el dispositivo podría quedar inutilizado en caso de una mala operativa.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
<soap:Header/>
<soap:Body>
<tem:CallSpecificFunctionRequest>
<tem:Header>
<tem:ClientId>ClientIdValue</tem:ClientId>
<tem:StoreId>StoreIdValue</tem:StoreId>
<tem:PosId>PosIdValue</tem:PosId>
<tem:Lang>Idioma</tem:Lang>
<tem:ExtraData1></tem:ExtraData1>
</tem:Header>
<tem:Function>4</tem:Function>
<tem:Modifier>0</tem:Modifier>
<tem:Parameter1>2</tem:Parameter1>
<tem:Parameter2></tem:Parameter2>
<tem:Parameter3></tem:Parameter3>
</tem:CallSpecificFunctionRequest>
</soap:Body>
</soap:Envelope>
Cancelación desde TPV [CallSpecificFunction 0]
En el momento en el que se excediera el tiempo de espera o hubiese algún error durante la transacción, es muy importante llamar a la función de Cancelación con el número de ticket.
Tras lanzar la llamada de Cancelación se debe seguir el circuito para comprobar con la función GetNextMessage. El obtener un 1000, representa que el device hub ha recibido correctamente la petición de cancelación, pero no indica que la misma haya sido procesada en ese momento. El proceso de cancelación es asíncrono y se realizará cuando el DeviceHub tiene conexión con la entidad.
Para comprobar que dicha operación ha sido cancelada, se debe revisar la web de operaciones de Sipay, teniendo en cuenta que dicho proceso puede tardar hasta 24 horas.
Parámetros:
Los datos de Header deben ser iguales que en todas las transacciones.
- Function: 0
- Modifier: 0
- Parameter1: Tipo string el importe de la transacción original que se va a anular. (Véase Nota 1)
- Parameter2: Numero de ticket de la operación que se desea cancelar o el número de secuencia.
- Parameter3: No utilizado.
Nota 1: Importe en el mismo formato que la transacción con 10 dígitos donde los 2 últimos son céntimos. EJ.: 1.25€ -> 000000012.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
<soap:Header/>
<soap:Body>
<tem:CallSpecificFunctionRequest>
<tem:Header>
<tem:ClientId>ClientIdValue</tem:ClientId>
<tem:StoreId>StoreIdValue</tem:StoreId>
<tem:PosId>PosIdValue</tem:PosId>
<tem:Lang>Idioma</tem:Lang>
<tem:ExtraData1></tem:ExtraData1>
</tem:Header>
<tem:Function>0</tem:Function>
<tem:Modifier>0</tem:Modifier>
<tem:Parameter1>0000000001</tem:Parameter1>
<tem:Parameter2>ticketnumber</tem:Parameter2>
<tem:Parameter3></tem:Parameter3>
</tem:CallSpecificFunctionRequest>
</soap:Body>
</soap:Envelope>
Preautorización [BeginPreAuthorization]
Llamada que se lanza para realizar la preautorización por el importe deseado. Una vez realizada la solicitud ese importe se congelará en la cuenta del cliente y hasta que se sustituya o cancele no quedará liberado y el cliente no podrá utilizar ese dinero para otras compras o pagos.
Debes tener las siguientes consideraciones:
-
Si una preautorización no es confirmada, sustituida o cancelada y se vence el plazo límite que la entidad bancaria ha determinado, la preautorización se liberará automáticamente y se deberá hacer una nueva solicitud de preautorización. Nunca se podrá confirmar o sustitución de una preautorización en la que se haya pasado el tiempo límite.
-
Siempre se podrá confirmar una preautorización por el importe total o por uno inferior, pero en ningún caso se podrá hacer “n” confirmaciones hasta completar el importe total. Una vez que se ha hecho una confirmación sobre una preautorización si es de una parte del total el resto se libera automáticamente.
-
No se pueden hacer cancelaciones de una cancelación. Si una preautorización se ha cancelado la única forma de volver a preautorizar el importe es lanzando una nueva solicitud de preautorización.
-
El tiempo límite de duración de una preautorización lo marca la entidad bancaria. El máximo normalmente son 30 días, pero lo estándar es entre 7 y 15 días. Cada cliente debe negociar con su banco los días que se deben configurar. Recomendación: si se trabaja con varias entidades en diferentes establecimientos, se recomienda que el límite sea el más bajo de todas las entidades.
-
Si se ha hecho una solicitud de preautorización por un importe y después se hace una sustitución de esa preautorización por un importe mayor y el cliente no tiene saldo en la cuenta, no se podrá hacer efectiva la sustitución. Se quedará activa la preautorización original con el importe inicial de la solicitud.
A continuación, se detalla el método que dado un importe lanza la transacción para solicitar una reserva.
Petición: BeginPreAuthorizationRequest
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Header | Header | Datos utilizados durante las consultas. |
String | Amount | Importe y Ticket de la Operación. El ticket no es obligatorio, pero se recomienda su uso. El formato del campo puede ser: |
String | Sin Ticket | Importe de la operación con 10 dígitos numéricos, donde los dos últimos dígitos representan los céntimos.Ej.:1€ > 0000000100 2,25€ > 0000000225 |
String | Con Ticket: | Importe de la operación del mismo formato que sin ticket, más el número de ticket, separados por una @.Ej.: Importe de 1,15€ y ticket número 453AF01 > 0000000115@453AF01 |
A partir de la versión 4.0.1.0 del device hub, está disponible este campo. La longitud máxima del ticket no debe superar los 40 caracteres. |
Header
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
String | Clientid | Identificador del comercio. |
String | Storeid | Identificador de la tienda. |
String | Posid | Identificador del Terminal Punto de Venta. |
String | Language | Identificador del idioma: 0 Español 1 English |
String | ExtraData1 | No usado. |
Nota: El campo Posid no debe superar los 30 caracteres y se recomienda no usar los siguientes símbolos dentro del campo
{"/","\"}
Respuesta: BeginPreAuthorizationResponse
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Result | Result | Retorna 0=OK o un código de error y su descripción. |
Result
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Int | Code | Código de error. |
String | Descripción | Descripción del error. |
Confirmación de Preautorización [ProcessPreAuthorization]
La confirmación implica el cobro de la preautorización. Se puede hacer por el importe total preautorizado o por importes inferiores. Si se hace sobre un importe inferior al preautorizado el resto del importe queda liberado. Una vez confirmada una preautorización si se quisiera seguir preautorizando la diferencia habría que hacer una nueva solicitud de preautorización por el importe deseado.
Teniendo el importe y el código de autorización o número de ticket, se hace efectiva la reserva asociada a dicho código, donde el importe puede ser hasta un 15% más o menos del importe preautorizado solicitado, según las condiciones negociadas con la entidad financiera.
También será importante establecer las condiciones de disponibilidad del plazo para confirmar este tipo de operación. En caso de no haber confirmado esta operación en el plazo estipulado por la entidad, la preautorización inicial quedará liberada.
Petición: ProcessPreAuthorizationRequest
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Header | Header | Datos utilizados durante las siguientes consultas. |
String | Amount | Importe autorizado para la reserva del pago con un margen, según la entidad bancaria que lo procesa. Importe de la operación con 10 dígitos numéricos, donde los dos últimos dígitos representan los céntimos. Ej.:1€ > 0000000100; 2,25€ > 0000000225 |
String | AuthorizationCode | Código de autorización o número de ticket de la transacción original.(En el caso del ticket debe ser un valor único). |
String | Ticket | A partir de la versión 4.0.1.0 del device hub, está disponible este campo. La longitud máxima del ticket no debe superar los 40 caracteres. Es el ticket original enviado en la preautorización inicial. |
Si se informa, no es obligatorio el campo AuthorizationCode. |
Header
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
String | Clientid | Identificador del comercio. |
String | Storeid | Identificador de la tienda. |
String | Posid | Identificador del Terminal Punto de Venta. |
String | Language | Identificador del idioma: 0 Español 1 English |
String | ExtraData1 | No usado. |
Nota: El campo Posid no debe superar los 30 caracteres y se recomienda no usar los siguientes símbolos dentro del campo
{"/","\"}
Respuesta: ProcessPreAuthorizationResponse
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Result | Result | Retorna 0=OK o un código de error y su descripción. |
Result
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Int | Code | Código de error. |
String | Descripción | Descripción del error. |
Cancelación de Preautorización [CancelPreAuthorization]
Liberar el importe preautorizado sin efectuar ningún cobro al cliente. Si se quiere liberar una preautorización y no se quiere cobrar al cliente se debe hacer una cancelación de la preautorización. Las cancelaciones siempre deben ser por el importe total de la preautorización, nunca se podrá hacer una cancelación por un importe menor.
A través de este método se anula la reserva solicitada con el número de autorización o el número de ticket original.
Petición: CancelPreAuthorizationRequest
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Header | Header | Datos utilizados durante las siguientes consultas. |
String | Amount | Importe autorizado para la reserva de pago.Importe de la operación con 10 dígitos numéricos, donde los dos últimos dígitos representan los céntimos.Ej.: 1€ > 0000000100; 2,25€ > 0000000225 |
String | AuthorizationCode | Código de autorización o el número de ticket original (en el caso del ticket, debe ser un valor único). |
String | Ticket | A partir de la versión 4.0.1.0 del device hub, está disponible este campo.La longitud máxima del ticket no debe superar los 40 caracteres. Es el ticket original enviado en la preautorización inicial. |
Si se informa, no es obligatorio el campo AuthorizationCode. |
Header
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
String | Clientid | Identificador del comercio. |
String | Storeid | Identificador de la tienda. |
String | Posid | Identificador del Terminal Punto de Venta. |
String | Language | Identificador del idioma: 0 Español 1 English |
String | ExtraData1 | No usado. |
Nota: El campo Posid no debe superar los 30 caracteres y se recomienda no usar los siguientes símbolos dentro del campo
{"/","\"}
Respuesta: CancelPreAuthorizationResponse
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Result | Result | Retorna 0=OK o un código de error y su descripción. |
Result
TIPO | NOMBRE | COMENTARIOS |
---|---|---|
Int | Code | Código de error. |
String | Descripción | Descripción del error. |
Nota: No existe la posibilidad de hacer una cancelación de una cancelación de preautorización.
Sustitución de Preautorización [ReplacementPreAuthorization]
Mensaje utilizado para sustituir una preautorización no confirmada. La nueva preautorización puede tener un valor igual o distinto a la original. En ambos casos el plazo de retención de la preautorización se modifica, teniendo en cuenta como base, la fecha de esta operación.
Se suele utilizar la sustitución en los siguientes casos:
- Antes del vencimiento de los días límites que marca la entidad bancaria para prolongar la preautorización.
- Modificar el importe preautorizado ya sea por un importe inferior o superior.
Disponible a partir de la versión 4.0.1.0 del device hub.