Integración OperationsGateway XML

La integración XML SOAP mediante el servicio OperationsGateway permite el acceso a las operaciones de los productos contratados con la plataforma de pago PAYTPV 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 PAYTPV para recoger las operaciones realizadas en todos sus productos, sin necesidad de acceder al panel de control, sólo llamando al servicio SOAP: search_operations.

  1. Introducción
  2. Configuración del producto
  3. Llamada al servicio
  4. Tipos de operación
  5. Cálculo de firma del comercio
  6. Tipos de ordenación
  7. Ejemplos de uso

Introducción

La tecnología escogida para la realización de las operaciones es SOAP, basada en XML y que permite la consulta mediante protocolo seguro por firewalls y a través de la red.

La publicación del WSDL que facilita el esquema para el uso de la función search_operations es:

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

Configuración del producto

Para poder utilizar el servicio de consulta de operaciones en su comercio deberá estar en posesión de los parámetros de configuración necesarios. Éstos pueden obtenerse a través de la plataforma de gestión de cliente.

Una vez dentro de la plataforma, puedes revisar la configuración del producto contratado mediante el menu Mis productos -> Configurar producto

Tras pulsar en el botón “Editar” del producto elegido, aparecerá un panel con la información básica del producto bajo el apartado “Configuración técnica del producto”. En concreto los datos necesarios durante el proceso de integración son:

  • Contraseña
  • Número de terminal
  • Código de cliente

Llámada al servicio search_operations

Debido a que todo el proceso de consulta se realiza en segundo plano (de servidor a servidor) las modificaciones a realizar en el comercio son totalmente ajenas a la experiencia de usuario.

La tecnología empleada para la operativa con la pasarela de pagos PAYTPV es SOAP, basada en HTTPS para evitar problemas de transporte a través de firewalls y otros dispositivos y a la vez garantizar la seguridad de las operaciones. Existe un soporte muy amplio para la realización de llamadas SOAP para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debes asegurarte que tu sistema es capaz de realizar las peticiones correctamente y gestionar los certificados de seguridad devueltos por la plataforma para una correcta utilización.

search_operations

Las variables que se requieren para consultar las operaciones de los productos contratados por el comercio son:

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]{40} 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_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.
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 XXX...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 PAYTPV por la transacción en fijo por operación (en la moneda del producto)
PAYTPV_OPERATION_FEEPERCENT FLOAT [0-9]{1,4} Tarifa PAYTPV 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 PAYTPV 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.

Tipos de operaciones (OPERATIONS)

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

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á SHA1, 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 SHA1 se han incluido una serie de librerías.Puede descargar los archivos desde el apartado Scripts de este site.

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

Cálculo de la firma

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

SHA1(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.

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)

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>
                <Operation>
                        <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>
                </Operation>
                <Operation>
                        <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>
                </Operation>
        </return>
</search_operationsResponse>