Consulta de operaciones

La consulta de operaciones, disponible en las integraciones REST y XML, permite el acceso a las operaciones de los productos contratados con la plataforma de pago PAYCOMET sin intervención directa del usuario, ampliando la operativa para la relación de “marcas blancas” o integraciones con software de otros clientes. Las peticiones parten del servidor del comercio y son procesadas por la pasarela de pago.

De esta forma el comercio tiene un acceso directo con PAYCOMET para recoger las operaciones realizadas en todos sus productos, sin necesidad de acceder al panel de control, sólo llamando al servicio: search_operations.

  1. Introducción
  2. Llamada al servicio
  3. Anexo I - Tipos de operación
  4. Anexo II - Tipos de ordenación

Introducción

Las tecnologías escogidas para la realización de las operaciones son SOAP, basada en XML y REST, basada en comunicaciones JSON. Ambas permiten la consulta mediante protocolo seguro por firewalls y a través de la red.

De esta forma el comercio tiene un acceso directo con PAYCOMET para recoger las operaciones realizadas en todos sus productos, sin necesidad de acceder al panel de control, sólo llamando al servicio: search_operations.

Llámada al servicio search_operations

A continuación, selecciona el tipo de integración:

REST XML
Elemento Contenido Descripción
PAYTPV_OPERATIONS_MERCHANTCODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
PAYTPV_OPERATIONS_SORTYPE [0-9]{1,4} Obligatorio. Ver TIPO DE ÓRDEN
PAYTPV_OPERATIONS_SORTORDER [ASC][DESC] Obligatorio. Orden de los resultados ASC = Ascendente, DESC = Descendente.
PAYTPV_OPERATIONS_LIMIT [0-9]{4} Opcional. Límite de resultados.
PAYTPV_OPERATIONS_TERMINAL Array [0-9] {1,10} Obligatorio. Array de los identificadores de los productos a consultar.
PAYTPV_OPERATIONS_OPERATIONS Array [0-9]{2} Obligatorio. Ver OPERATIONS.
PAYTPV_OPERATIONS_MINAMOUNT [0-9]{1,8} Obligatorio. Mínimo importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
PAYTPV_OPERATIONS_MAXAMOUNT [0-9]{1,8} Obligatorio. Máximo importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
PAYTPV_OPERATIONS_STATE [0-1-2]{1} Obligatorio. Resultado de la operación. 0 es operación fallida, 1 operación correcta y 2 serán todas.
PAYTPV_OPERATIONS_FROMDATE [YYYYMMDDHH MMSS] Obligatorio. Fecha de inicio de la consulta. AÑO – MES – DIA – HORA – MINUTOS – SEGUNDOS
PAYTPV_OPERATIONS_TODATE [YYYYMMDDHH MMSS] Obligatorio. Fecha final de la consulta. AÑO – MES – DIA – HORA – MINUTOS – SEGUNDOS
PAYTPV_OPERATIONS_CURRENCY [EUR][USD][GBP][JPY]... Obligatorio. Moneda de la transacción. Ver más información en MONEDAS
PAYTPV_OPERATIONS_SIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
PAYTPV_OPERATIONS_REFERENCE [A-Za-z0-9]{70} Opcional. Referencia de la operación.
PAYTPV_OPERATIONS_SEARCHTYPE 0: Like, 1: Equal Opcional. Tipo de comparación. 0 comparación LIKE (%xxx%), 1 comparación exacta (=)
PAYTPV_OPERATIONS_VERSION [1.00-1.10] Opcional. Si no se envía o el parámetro no es ninguna de las versiones actuales, se tomará como base la versión 1.00

La respuesta del servicio a la petición se realiza mediante la devolución de un array del objeto Operation, donde PAYTPV_ERROR_ID contendrá el error (en caso de que hubiera) de integración del WEBSERVICE o con valor 0 en caso de éxito.

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo PAYTPV_ERROR_ID que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá un array con el objeto Operation con las líneas de las operaciones. El formato es el siguiente:

Respuesta servicio: search_operations
Elemento Contenido Descripción
PAYTPV_OPERATION_METHODID [0-9]{1,2} Identificador de método en PAYCOMET. Ver listado.
PAYTPV_OPERATION_METHODNAME [a-zA-Z0-9]{40} Nombre de método en PAYCOMET
PAYTPV_OPERATION_ID [A-Za-z0-9]{1,8} Identificador de la operación
PAYTPV_OPERATION_TIMESTAMP [YYYYMMDDHH MMSS] Fecha de la operación (YYYYMMDDHHMMSS)
PAYTPV_OPERATION_REFERENCE [A-Za-z0-9]{1,20} Referencia de la operación.
PAYTPV_OPERATION_OPERATION [0-9]{1,2} Identificador del tipo de operación. Ver OPERATIONS.
PAYTPV_OPERATION_OPERATIONNAME [a-zA-Z0-9]{40} Literal del tipo de operación.
PAYTPV_OPERATION_STATE [0-1]{1} Identificador del estado de la operación. 0 es operación fallida, 1 operación correcta, 2 Sin finalizar (para la operaciones pendientes de un SCA o 3DS).
PAYTPV_OPERATION_STATENAME [a-zA-Z0-9]{40} Literal del estado de la operación
PAYTPV_OPERATION_TERMINAL [0-9]{1,5} Identificador del producto del cliente.
PAYTPV_OPERATION_TERMINALNAME [a-zA-Z0-9]{40} Nombre del producto del cliente
PAYTPV_OPERATION_PAN 123456******1234 Tarjeta de crédito/débito enmascarada
PAYTPV_OPERATION_USER [a-zA-Z0-9]{40} Nombre del usuario que ejecutó la operación
PAYTPV_OPERATION_AMOUNT [0-9]{1,9} Importe de la operación en entero: 1 euro = 100
PAYTPV_OPERATION_CURRENCY [EUR][USD][GBP][JPY]... Moneda de la transacción. Ver más información en MONEDAS
PAYTPV_OPERATION_AMOUNTDISPLAY [a-zA-Z0-9]{40} Literal del importe de la operación (con símbolo de la moneda)
PAYTPV_OPERATION_ERRORID [0-9]{1,5} Identificador del error de la operación.
PAYTPV_OPERATION_ERRORDESC [a-zA-Z0-9]{40} Descripción literal del error de la operación
PAYTPV_OPERATION_FEEEURO FLOAT [0-9]{1,4} Tarifa PAYCOMET por la transacción en fijo por operación (en la moneda del producto)
PAYTPV_OPERATION_FEEPERCENT FLOAT [0-9]{1,4} Tarifa PAYCOMET por la transacción en variable por operación (en la moneda del producto)
PAYTPV_OPERATION_IP A.B.C.D IP del cliente de la operación
PAYTPV_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error vendrá con valor 0. Los códigos de error vienen especificados en CÓDIGOS DE ERROR
PAYTPV_OPERATION_SCORING [0-100]{1,3} Valor de scoring calculado. Si no se ha calculado scoring, se devolverá vacío.
PAYTPV_OPERATION_CARDBRAND [a-zA-Z0-9]{40} A partir de la versión 1.10 si puede obtenerse, se devolverá la marca de la tarjeta de la operación. Para versiones anteriores o solicitudes sin versión, se devolverá en blanco.
PAYTPV_OPERATION_BICCODE [a-zA-Z0-9]{11} A partir de la versión 1.10 si puede obtenerse, se devolverá el biccode de la entidad por la que se procesó la operación. Para versiones anteriores o solicitudes sin versión, se devolverá en blanco.
PAYTPV_OPERATION_AUTHCODE [.*] Código de autorización devuelto por el banco.

La comisión de PAYCOMET es la suma de los campos: PAYTPV_OPERATION_FEEEURO + PAYTPV_OPERATION_FEEPERCENT que vendrá expresado en FLOAT y en la moneda del producto asociado a la transacción.

Si la operación no es errónea el campo PAYTPV_OPERATION_ERRORID será 0.

Cálculo de firma del comercio

La firma deberá ser calculada en el servidor del comercio y englobará los principales parámetros de la llamada para verificar la integridad de los datos a través de Internet.

El algoritmo de cifrado utilizado al efecto será SHA512, el cual nos permite cifrar una cadena de texto. Este tipo de algoritmos de un solo sentido impide obtener el parámetro inicial a partir del resultado.

Para facilitar la generación de la firma en lenguajes sin las herramientas necesarias para el cálculo de algoritmos SHA512 se han incluido una serie de librerías. Puedes descargar los archivos desde el apartado Scripts de este site.

Algunas de estas librerías han sido realizadas por personas o entidades ajenas a PAYCOMET. Consulta el contenido de cada archivo para más información.

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

SHA512(PAYTPV_OPERATIONS_MERCHANTCODE + ((TERMINAL_ID1 + TERMINAL_PASSWORD1) + (TERMINAL_ID2 + TERMINAL_PASSWORD2) + (TERMINAL_ID3 + TERMINAL_PASSWORD3)... + OPERATION_ID1 + OPERATION_ID2 + OPERATION_ID3... + PAYTPV_OPERATIONS_FROMDATE + PAYTPV_OPERATIONS_TODATE)

La firma se compone de la suma de las siguientes variables:

  • PAYTPV_OPERATIONS_MERCHANTCODE: El código del comercio.
  • TERMINAL_ID1 + TERMINAL_PASSWORD1: Concatenación del número de terminal + su contraseña (se concatenarán tantos como influya la solicitud de search_operations en el Array).
  • OPERATION_ID1: Concatenación de los identificadores de operaciones solicitados en search_operations en el Array.
  • PAYTPV_OPERATIONS_FROMDATE: Fecha de inicio de la petición.
  • PAYTPV_OPERATIONS_TODATE: Fecha final de la petición.

Ejemplos de uso

A continuación se mostrará un ejemplo de llamada y respuesta:


        <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<search_operations>
        <PAYTPV_OPERATIONS_MERCHANTCODE xsi:type="xsd:string">*******</PAYTPV_OPERATIONS_MERCHANTCODE>
        <PAYTPV_OPERATIONS_SORTYPE xsi:type="xsd:int">1</PAYTPV_OPERATIONS_SORTYPE>
        <PAYTPV_OPERATIONS_SORTORDER xsi:type="xsd:string">ASC</PAYTPV_OPERATIONS_SORTORDER>
        <PAYTPV_OPERATIONS_LIMIT xsi:type="xsd:int">100</PAYTPV_OPERATIONS_LIMIT>
        <PAYTPV_OPERATIONS_TERMINAL xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:int[1]">
        <item xsi:type="xsd:int">****</item>
        </PAYTPV_OPERATIONS_TERMINAL>
        <PAYTPV_OPERATIONS_OPERATIONS xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:int[2]">
        <item xsi:type="xsd:int">1</item>
        <item xsi:type="xsd:int">2</item>
        </PAYTPV_OPERATIONS_OPERATIONS>
        <PAYTPV_OPERATIONS_MINAMOUNT xsi:type="xsd:int">0</PAYTPV_OPERATIONS_MINAMOUNT>
        <PAYTPV_OPERATIONS_MAXAMOUNT xsi:type="xsd:int">999999999</PAYTPV_OPERATIONS_MAXAMOUNT>
        <PAYTPV_OPERATIONS_STATE xsi:type="xsd:int">1</PAYTPV_OPERATIONS_STATE>
        <PAYTPV_OPERATIONS_FROMDATE xsi:type="xsd:string">20140101000000</PAYTPV_OPERATIONS_FROMDATE>
        <PAYTPV_OPERATIONS_TODATE xsi:type="xsd:string">20140131000000</PAYTPV_OPERATIONS_TODATE>
        <PAYTPV_OPERATIONS_CURRENCY xsi:type="xsd:string">EUR</PAYTPV_OPERATIONS_CURRENCY>
        <PAYTPV_OPERATIONS_SIGNATURE xsi:type="xsd:string">**********************************</PAYTPV_OPERATIONS_SIGNATURE>

</search_operations>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Respuesta (versión 1.10):

<search_operationsResponse>
        <return>
                <item>
                        <PAYTPV_ERROR_ID>0</PAYTPV_ERROR_ID>
                        <PAYTPV_OPERATION_ID>******</PAYTPV_OPERATION_ID>
                        <PAYTPV_OPERATION_TIMESTAMP>20140101000130</PAYTPV_OPERATION_TIMESTAMP>
                        <PAYTPV_OPERATION_REFERENCE>**********</PAYTPV_OPERATION_REFERENCE>
                        <PAYTPV_OPERATION_OPERATION>1</PAYTPV_OPERATION_OPERATION>
                        <PAYTPV_OPERATION_OPERATIONNAME>Autorización</PAYTPV_OPERATION_OPERATIONNAME>
                        <PAYTPV_OPERATION_STATE>1</PAYTPV_OPERATION_STATE>
                        <PAYTPV_OPERATION_STATENAME>Completado</PAYTPV_OPERATION_STATENAME>
                        <PAYTPV_OPERATION_TERMINAL>****</PAYTPV_OPERATION_TERMINAL>
                        <PAYTPV_OPERATION_TERMINALNAME>BANKSTORE</PAYTPV_OPERATION_TERMINALNAME>
                        <PAYTPV_OPERATION_PAN>XXX...9015</PAYTPV_OPERATION_PAN>
                        <PAYTPV_OPERATION_USER>***************</PAYTPV_OPERATION_USER>
                        <PAYTPV_OPERATION_AMOUNT>999</PAYTPV_OPERATION_AMOUNT>
                        <PAYTPV_OPERATION_CURRENCY>EUR</PAYTPV_OPERATION_CURRENCY>
                        <PAYTPV_OPERATION_AMOUNTDISPLAY>9,99 €</PAYTPV_OPERATION_AMOUNTDISPLAY>
                        <PAYTPV_OPERATION_ERRORID>0</PAYTPV_OPERATION_ERRORID>
                        <PAYTPV_OPERATION_ERRORDESC>Sin error</PAYTPV_OPERATION_ERRORDESC>
                        <PAYTPV_OPERATION_FEEEURO>0.00</PAYTPV_OPERATION_FEEEURO>
                        <PAYTPV_OPERATION_FEEPERCENT>0</PAYTPV_OPERATION_FEEPERCENT>
                        <PAYTPV_OPERATION_IP>**.**.**.**</PAYTPV_OPERATION_IP>
                        <PAYTPV_OPERATION_CARDBRAND>VISA</PAYTPV_OPERATION_CARDBRAND>
                        <PAYTPV_OPERATION_BICCODE>BMARES2MXXX</PAYTPV_OPERATION_BICCODE>
                        <PAYTPV_OPERATION_CONCEPT>Concept / description / remarks</PAYTPV_OPERATION_CONCEPT>
                        <PAYTPV_OPERATION_PANCOUNTRY>GB</PAYTPV_OPERATION_PANCOUNTRY>
                        <PAYTPV_OPERATION_COUNTRY>GB</PAYTPV_OPERATION_COUNTRY>
                        <PAYTPV_OPERATION_ISSUERBANK>NATIXIS</PAYTPV_OPERATION_ISSUERBANK>
                        <PAYTPV_OPERATION_AUTHCODE>99999/99999999</PAYTPV_OPERATION_AUTHCODE>
                        <PAYTPV_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYTPV_OPERATION_SPLITID>
                </item>
                <item>
                        <PAYTPV_ERROR_ID>0</PAYTPV_ERROR_ID>
                        <PAYTPV_OPERATION_ID>*******</PAYTPV_OPERATION_ID>
                        <PAYTPV_OPERATION_TIMESTAMP>20140101000219</PAYTPV_OPERATION_TIMESTAMP>
                        <PAYTPV_OPERATION_REFERENCE>**********</PAYTPV_OPERATION_REFERENCE>
                        <PAYTPV_OPERATION_OPERATION>1</PAYTPV_OPERATION_OPERATION>
                        <PAYTPV_OPERATION_OPERATIONNAME>Autorización</PAYTPV_OPERATION_OPERATIONNAME>
                        <PAYTPV_OPERATION_STATE>1</PAYTPV_OPERATION_STATE>
                        <PAYTPV_OPERATION_STATENAME>Completado</PAYTPV_OPERATION_STATENAME>
                        <PAYTPV_OPERATION_TERMINAL>****</PAYTPV_OPERATION_TERMINAL>
                        <PAYTPV_OPERATION_TERMINALNAME>BANKSTORE</PAYTPV_OPERATION_TERMINALNAME>
                        <PAYTPV_OPERATION_PAN>XXX...8011</PAYTPV_OPERATION_PAN>
                        <PAYTPV_OPERATION_USER>***************</PAYTPV_OPERATION_USER>
                        <PAYTPV_OPERATION_AMOUNT>995</PAYTPV_OPERATION_AMOUNT>
                        <PAYTPV_OPERATION_CURRENCY>EUR</PAYTPV_OPERATION_CURRENCY>
                        <PAYTPV_OPERATION_AMOUNTDISPLAY>9,95 €</PAYTPV_OPERATION_AMOUNTDISPLAY>
                        <PAYTPV_OPERATION_ERRORID>0</PAYTPV_OPERATION_ERRORID>
                        <PAYTPV_OPERATION_ERRORDESC>Sin error</PAYTPV_OPERATION_ERRORDESC>
                        <PAYTPV_OPERATION_FEEEURO>0.00</PAYTPV_OPERATION_FEEEURO>
                        <PAYTPV_OPERATION_FEEPERCENT>0</PAYTPV_OPERATION_FEEPERCENT>
                        <PAYTPV_OPERATION_IP>**.**.**.**</PAYTPV_OPERATION_IP>
                        <PAYTPV_OPERATION_CARDBRAND>VISA</PAYTPV_OPERATION_CARDBRAND>
                        <PAYTPV_OPERATION_BICCODE>BMARES2MXXX</PAYTPV_OPERATION_BICCODE>
                        <PAYTPV_OPERATION_CONCEPT>Description / concept / remarks</PAYTPV_OPERATION_CONCEPT>
                        <PAYTPV_OPERATION_PANCOUNTRY>FR</PAYTPV_OPERATION_PANCOUNTRY>
                        <PAYTPV_OPERATION_COUNTRY>FR</PAYTPV_OPERATION_COUNTRY>
                        <PAYTPV_OPERATION_ISSUERBANK>ALLIED BANK, LTD.</PAYTPV_OPERATION_ISSUERBANK>
                        <PAYTPV_OPERATION_AUTHCODE>99999/99999999</PAYTPV_OPERATION_AUTHCODE>
                        <PAYTPV_OPERATION_SPLITID>aaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666gggg7777hhhh8888ii</PAYTPV_OPERATION_SPLITID>

                </item>
        </return>
</search_operationsResponse>

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

Anexo I - Tipos de operaciones

Las operaciones se diferencian mediante identificadores numéricos. Esta tabla refleja los diferentes valores asignados a los números enteros enviados bajo el Webservice.

ID Valor Operación
1Autorización
2Devolución
3Preautorización
5Modificación de Preautorización
4Cancelación de Preautorización
6Confirmación de Preautorización
101Retirada de fondos
7Autorización presencial
103Liquidación de fondos por eliminación
104Ajuste de saldo
105Denegación de solicitud de retirada
106Retroceso
8Cargo por notificación SMS
9Pago suscripción
10Cargo por mantenimiento
20Transferencia SEPA
30Denegación de Transferencia SEPA
22Split Transfer
23Split Transfer Reversal
24Transferencia
25Revocación de transferencia

Anexo II - Tipos de ordenación

Se puede solicitar al Webservice que los resultados los devuelva ordenados por alguna de las siguientes columnas. Esta tabla refleja los diferentes valores asignados a los números enteros enviados bajo el Webservice.

ID Valor Ordenado por:
0No asigna orden
1Fecha
2Referencia
3Tipo de operación
4Estado de la operación
5Terminal (Producto)
6Importe de la operación
7Usuario que ejecutó la Operación (Literal)