Consulta de operaciones REST ¿Qué es una consulta REST?La funcionalidad de consultas REST del TPV Virtual permite a los comercios recuperar información detallada de las operaciones que han iniciado, sin importar si estas finalizaron correctamente o no. Es una herramienta útil para hacer seguimiento de transacciones, validar su estado o complementar procesos internos del comercio (logística, soporte, conciliación, etc.).Este servicio está diseñado para ser consumido a través de una integración REST y utiliza el formato JSON (RFC 7159) tanto en la petición como en la respuesta.Dado que la consulta implica el envío de datos confidenciales, es necesario validar las comunicaciones. Por este motivo, hay que implementar una firma HMAC512 (también disponible HMAC256) para autenticar la veracidad de los datos. Características clave de Consulta RESTEn las consultas REST tienes que tener estos puntos en cuenta: Por seguridad, las consultas se tienen que validar con una firma HMAC512 O 256. Permite consultar información de las transacciones finalizadas o sin finalizar que haya lanzado el comercio. Estas consultas se realizan sobre las base de una integración REST. En este documento detallaremos todos estos puntos. Tipos de consulta RESTLos tipos de consulta REST disponibles son:1. Detail – Consulta de detalle por número de pedido: Consulta diseñada para obtener el estado final de una operación concreta.Limitaciones:Es obligatorio indicar el campo order (número de pedido).Solo se pueden consultar operaciones realizadas en los últimos 90 días.Solo se devuelven las operaciones que cumplan los filtros aplicados.2. Massive – Consulta masiva de operaciones por fechas: Pensada para obtener un listado informativo de operaciones dentro de un rango de fechas.Limitaciones:Es obligatorio informar initialDate y finalDate.El rango de fechas entre la inicial y la final no puede superar los 15 días.Se devuelve un máximo de 1.000 operaciones por consulta.Si se incluye un filtro por order, pueden devolverse varias operaciones con ese mismo número, por ejemplo:Un pago y su devolución.Un pago y varias devoluciones parciales.Una preautorización y su confirmación.Otras consideracionesExiste una limitación de frecuencia por IP. Si se realizan demasiadas peticiones en un segundo, se devolverá el código de error HTTP 429 (Too Many Requests). Esto aplica a ambos tipos de consulta. URLs de envío y cabecerasEstas son las URLs a las que tienes que enviar la consulta REST correspondiente: Tipo de consultaEntornoURL DetailPruebas https://apis-i.redsys.es:20443/acquirement/commerces -channel/no-presencial/v1/operation/search Producciónhttps://apis.redsys.es/acquirement/commerces-channel/no-presencial/v1/operation/search MassivePruebashttps://apis-i.redsys.es:20443/acquirement/commerces-channel /no-presencial/v1/operations/search Producciónhttps://apis.redsys.es/acquirement/commerces-channel/no-presencial/v1/operations/search Estas son las cabeceras que tienes que enviar para generar una petición válida: CabeceraValor Content-Typeapplication/json RedsysClientId{Id de suscripción que tienes que solicitar a Soporte} RedsysClientSecret{Clave/Secret de suscripción que tienes que solicitar a Soporte} Petición de Consulta de Operaciones RESTEste es un ejemplo de petición de Consulta de Operaciones «Detail». Recuerda que este body le tienes que añadir las cabeceras de la sección anterior: El JSON de la petición se envía todo junto y sin espacios, tal como ves en el ejemplo siguiente: {"info":{"data":{"fuc":"999008881","idTransaction":"00002730z328","initialDate":"2025-01-01-10.00.00","order":"00002730z328","terminal":"1"}},"signatureData":{"signatureType":"HMAC_SHA512_V1","signature":"8uRiPwqqZ8UDhsj0XUzhWjC9hG9eEX6XVuGfpp8YtoxJOfu3jUqtqEj3CPuKqLx3gmnE1dS8CiHZcFQ52IZiOA=="}} Parámetros de la petición de Consulta de OperacionesEstos son los parámetros que se pueden enviar en la petición de la Consulta REST: Par. PadreParámetroFormato Requerido / OpcionalDescripción info – datafinalDateAAAA-MM-DD-hh.mm.ssRequerido*Indica la fecha final del rango de fechas sobre el que se busca la operación. *Requerido si la consulta es de tipo «massive» info – datainitialDateAAAA-MM-DD-hh.mm.ssRequerido*Indica la fecha inicial del rango de fechas sobre el que se busca la operación. *Requerido si la consulta es de tipo «massive» info – datafuc9 caracteres NuméricoRequeridoCódigo FUC del comercio. info – dataidTransaction12 caracteres AlfanuméricoRequeridoNúmero/Identificador de la petición. info – dataorder12 caracteres AlfanuméricoRequerido*Número de pedido de la operación que se quiere consultar. *Requerido si la consulta es de tipo «detail» info – dataterminal3 caracteres NuméricoRequeridoNúmero de terminal del comercio. info – dataauthenticated– S – NOpcionalIndicador de si la operación se ha autenticado. S (Sí) / N (No) info – dataauthorized– S – NOpcionalIndicador de si la operación se ha autorizado. S (Sí) / N (No) info – datacodResponse4 caracteres NuméricoOpcionalIndica el codigo de respuesta de la operación. info – datacsb4 caracteres NuméricoOpcionalIndica el CSB adquiriente de la operación. info – datadcc– S – NOpcionalIndicador de si la operación se ha hecho con DCC. S (Sí) / N (No) info – datatransactionTypeNuméricoOpcionalIndica el tipo de operación que se quiere consultar. signatureDatasignatureTypeValores aceptados: – HMAC_SHA512_V1 – HMAC_SHA256_V1RequeridoTipo de firma utilizada. signatureDatasignatureAlfanuméricoRequeridoValor de la firma de la petición. Respuesta de Consulta de Operaciones RESTEste es un ejemplo de la respuesta que recibes a una petición de Consulta REST: { "signatureData": { "signatureType": "HMAC_SHA512_V1", "signature": "AC2fXHqjoyauWwSuHBCdH4GSU_xRMzLkRSlh5KZ-BJGeqgalPYgsxFBwyRrlkX7JBfjnnPGKsAb0mtRwYDf-pA==" }, "info": { "data": { "operations": [ { "fuc": "999008881", "terminal": "1", "csb": "2100", "order": "00002730z328", "transactionType": "0", "date": "2025-03-25 11:25:35.187", "state": "F", "authorized": "S", "authorizationNumber": "868043", "amount": "30.20", "currency": "978", "codResponse": "0", "cardNumber": "454881******0003", "cardBrand": "1", "cardCountry": "724", "cardExpiryDate": "4912", "cardToken": "991d0fc404eb5ce9e8aa0cb4101da113840db0f5", "cardType": "C", "paymethod": "78", "ipClient": "115.241.28.98", "ipCountry": "356", "eci": "05", "cofUse": "S", "cofType": "C", "grouperCode": "33333337", "productDescription": "1x Subscription test product,", "connectionType": "2", "merchantData": "eyJtb2R1bGVDb21lbnQiOiJQYXNhcmVsYSBVbmlmaWNhZGEgZGUgUmVkc3lzIHBhcmEgUHJlc3Rhc2hvcCIsImlkQ2FydCI6MjczMCwib3JpZ2luYWxNZXRob2QiOiJUYXJqZXRhIn0" } ], "numRecords": 1 }, "result": { "code": 2000, "description": "Operacion realizada Correctamente" }, "idTransaction": "00002730z328" } } Parámetros de la respuesta de Consulta de OperacionesEstos son los parámetros que puedes recibir en la respuesta de una consulta de operaciones: Par. PadreParámetroFormatoRequerido / OpcionalDescripción info – data — operationsfuc9 caracteres NuméricoRequeridoCódigo FUC asignado al comercio. info – data — operationsterminal3 caracteres NuméricoRequeridoNúmero de terminal del comercio. info – data — operationscsb4 caracteres NuméricoRequeridoIndica el CSB adquirente de la operación. info – data — operationsorder12 caracteres AlfanuméricoRequeridoNúmero de pedido de la operación consultada. info – data — operationstransactionTypeNuméricoRequeridoTipo de transacción que se quieren consultar. info – data — operationsdateAAAA-MM-DD hh:mm:ss.SSSRequeridoIndica la fecha exacta en la que se inició la operación. info – data — operationsstateValores disponibles: – S: Solicitada – P: En proceso de autorizar – A: Autenticando – F: Finalizada – T: Sin respuesta / Error Técnico – E: Transferencia, domiciliación o Paypal en proceso – D: Domiciliación descargada. – L: Transferencia Línea Abierta – W: Redirigida a un WalletRequeridoEstado de la transacción. info – data — operationsauthorized– S – NRequeridoIndicador de si la operación se ha autorizado. S (Sí) / N (No) info – data — operationsamount12 caracteres NuméricoRequeridoImporte de la operación. info – data — operationscurrency3 caracteres NuméricoRequeridoDivisa de la operación. info – data — operationscodResponse4 caracteres NuméricoRequeridoCódigo de respuesta de la operación. info – data — operationsauthorizationNumber6 caracteres AlfanuméricoOpcionalCódigo alfanumérico de autorización asignado a la aprobación de la transacción por la institución autorizadora. info – data — operationscardNumber14 a 16 caracteres AlfanuméricoOpcionalTarjeta de la operación. info – data — operationscardBrandValores disponibles: – 1: Visa – 2: Master – 6: Diners – 8: Amex – 9: JCB – 22: CUPOpcionalMarca de la tarjeta. info – data — operationscardCountry3 caracteres NuméricoOpcionalCódigo ISO del país de la tarjeta. info – data — operationscardExpiryDateAAMMOpcionalCaducidad de la tarjeta. info – data — operationscardToken40 caracteres AlfanuméricoOpcionalToken de la tarjeta. info – data — operationspaymethod3 caracteres Estos son los valores aceptados.OpcionalMétodo de pago de la operación. info – data — operationsipClient15 caracteres AlfanuméricoOpcionalIP del cliente. info – data — operationsipCountry3 caracteres NuméricoOpcionalCódigo ISO del país de la IP. info – data — operationsdccAmount12 caracteres NuméricoOpcionalImporte DCC aplicado en la operación. info – data — operationsdccCurrency3 caracteres NuméricoOpcionalDivisa DCC aplicada en la operación. info – data — operationsdccExchange12 caracteres AlfanuméricoOpcionalCambio aplicado en la operación DCC info – data — operationseciValores posibles: – 00: Comercio No Seguro/ Titular No Seguro (Marca Master) – 01: Comercio Seguro/ Titular No Seguro (Marca Master). – 02: Comercio Seguro/ Titular Seguro (Marca Master). – 05: Comercio Seguro/ Titular Seguro (Resto de marcas). – 06: Comercio Seguro/ Titular No Seguro (Resto de marcas). – 07: Comercio No Seguro/ Titular No Seguro (Resto de marcas).OpcionalCódigo que identifica el nivel de seguridad de la operación. info – data — operationscofUseValores posibles: – S: COF Inicial – N: COF SucesivaOpcionalIndicador del uso de COF (operaciones donde el comercio tokeniza o guarda la tarjeta del cliente) aplicado en la operación. info – data — operationscofTypeValores posibles: – I: Installments – R: Recurring – H: Reauthorization – E: Resubmission – D: Delayed – M: Incremental – N: No Show – C: OthersOpcional Tipo de operación COF que se ha aplicado en la operación. info – data — operationsmpiIndicator1 caracter NuméricoOpcional Indicador de MPI Externo. info – data — operationsopMarketplace1 caracter NuméricoOpcional Indicador de Marketplace. info – data — operationsgrouperCodeNuméricoOpcional Código agrupador. info – data — operationsproductDescriptionAlfanuméricoOpcional Descripción del producto. info – datanumRecords12 caracteres NuméricoRequeridoNúmero de operaciones retornadas. info – resultcodeValores posibles – 2000: Operación realizada correctamente. – 4001: Error Validación campos de Entrada. – 5000: Error Interno del Sistema.RequeridoCódigo de resultado de la operación. info – resultdescriptionAlfanuméricoRequeridoDescripción del resultado de la operación. Depende del «code» recibido en el campo anterior, si se recibe un «4001», se especificará el causante del error. infoidTransaction12 caracteres Alfanumérico RequeridoNúmero/Identificador de la petición. infotimeStampAAAA-MM-DD hh:mm:ss.SSSRequeridoFecha y hora de la petición. signatureDatasignatureTypeValores aceptados: – HMAC_SHA512_V1 – HMAC_SHA256_V1RequeridoTipo de firma utilizada. signatureDatasignatureAlfanuméricoRequeridoValor de firma de la respuesta. Firma de los mensajes SHA-512Todas las peticiones y respuestas del servicio de consulta REST incluyen una firma digital que garantiza la autenticidad e integridad de los mensajes intercambiados entre el comercio y el TPV Virtual.El sistema de firma se basa en HMAC SHA-512, aunque también está disponible HMAC SHA-256 si la integración no es nueva. Consulta el anexo para ver la firma SHA-256. A continuación te explicamos el proceso de firma, también tienes en las librerías de Redsys un código que puedes adaptar para la firma de las Consultas REST: Librerías Redsys Firma en la petición (comercio)Para enviar una consulta firmada correctamente, el comercio debe generar la firma utilizando su clave secreta compartida, la misma que usa para firmar operaciones en el TPV Virtual.¿Qué necesito para calcular la firma?Firma de la petición. Para calcular la firma, debes tener estos valores:El objeto data con los datos de la operación que quieres consultar.El número de pedido. Es el valor de idTransaction.La clave específica de tu terminal. Esta clave cambia del entorno de pruebas y el de producción. Tipado: Texto plano.La clave del terminal para producción se obtiene desde Canales, y la de pruebas se envía en el Welcome Pack. Consulta la documentación para más detalles.Guarda la clave de producción en un lugar seguro para evitar su uso fraudulento.¿Cómo se obtiene?Pre-procesa la clave de tu terminal: La clave tiene que tener exactamente 16 caracteres.Si tiene MÁS de 16 caracteres: Utiliza únicamente los 16 primeros caracteres de la clave.Si tiene MENOS de 16 caracteres: Rellena por la derecha con ceros (0) hasta llegar a 16 caracteres.Genera la clave diversificada: Esto se hace mediante un cifrado AES CBC, usando como vector de inicialización IV un vector de ceros. Este cifrado AES CBC se hace entre:La clave de tu terminal pre-procesada en el paso anterior.El número de pedido de la operación idTransaction (sin codificar en BASE64).Realiza un cifrado AES CBC entre estos 2 valores.Codifica en BASE64: Codifica en BASE64 el resultado obtenido en el paso anterior. Este valor se llama clave diversificada, y lo utilizarás más adelante.Calcula el HMAC-SHA512: Aplica el algoritmo HMAC-SHA512 sobre el data, utilizando la clave diversificada obtenida en el paso anterior.Codifica en BASE64URL: Se codifica el resultado del HMAC-SHA512 en BASE64URL.Este es el valor que tienes que enviar en Ds_Signature. Firma para PSPs:En el caso de los PSPs el proceso es igual, pero se sustituye la clave secreta de comercio por la clave de PSP. Verificar firma en la respuesta Cuando recibes una respuesta del TPV Virtual tras realizar una consulta, esta viene firmada. Es responsabilidad del comercio verificar la firma para asegurarse de que el mensaje no ha sido alterado y proviene realmente de tu TPV Virtual. ¿Qué necesito para calcular la firma? Firma de la petición. Para calcular la firma, debes tener estos valores: El objeto data con los datos de la operación recibida que quieres verificar. El número de pedido recibido. Es el valor de idTransaction. La clave específica de tu terminal. Esta clave cambia del entorno de pruebas y el de producción. Tipado: Texto plano. La clave del terminal para producción se obtiene desde Canales, y la de pruebas se envía en el Welcome Pack. Consulta la documentación para más detalles. Guarda la clave de producción en un lugar seguro para evitar su uso fraudulento. ¿Cómo se obtiene? Pre-procesa la clave de tu terminal: La clave tiene que tener exactamente 16 caracteres. Si tiene MÁS de 16 caracteres: Utiliza únicamente los 16 primeros caracteres de la clave. Si tiene MENOS de 16 caracteres: Rellena por la derecha con ceros (0) hasta llegar a 16 caracteres. Genera la clave diversificada: Esto se hace mediante un cifrado AES CBC, usando como vector de inicialización IV un vector de ceros. Este cifrado AES CBC se hace entre: La clave de tu terminal pre-procesada en el paso anterior. El número de pedido de la operación idTransaction (sin codificar en BASE64). Realiza un cifrado AES CBC entre estos 2 valores. Codifica en BASE64: Codifica en BASE64 el resultado obtenido en el paso anterior. Este valor se llama clave diversificada, y lo utilizarás más adelante. Calcula el HMAC-SHA512: Aplica el algoritmo HMAC-SHA512 sobre el data, utilizando la clave diversificada obtenida en el paso anterior. Codifica en BASE64URL: Se codifica el resultado del HMAC-SHA512 en BASE64URL. Este es el valor que tienes que comparar con el en Ds_Signature recibido. Firma para PSPs:En el caso de los PSPs el proceso es igual, pero se sustituye la clave secreta de comercio por la clave de PSP. Anexo: Métodos de pagoEn la siguiente tabla tienes los valores que puedes recibir en el campo paymethod. Indica el método de pago que se utiliza en la operación: CódigoDescripción 1Verified By Visa 3Tradicional Mundial 5Finanet 11Capacidad Finanet 13Capacidad Verified By Visa 14Tradicional Europeo 22MasterCard SecureCode 23Capacidad MasterCard SecureCode 24Pago Amex 25Pago Moto 28Pago JCB 31Pago Diners 39JCB Secure 40Capacidad JCB Secure 42Transferencia 54Paypal 57Amex Safekey 58Capacidad Amex Safekey 68Bizum 70UPI ExpressPay 71GooglePay 72ApplePay 73UPI SecurePlus 74Capacidad Discover 75Discover Protect Buy 76Pago Discover 77Amazon Pay 78Challenge Visa 79Challenge Master 80Frictionless Visa 81Frictionless Master 82Attempt Visa 83Attempt Master 85Challenge Amex 86Challenge Discover 87Frictionless Amex 88Frictionless Discover 89Attempt Amex 90Attempt Discover 93Challenge Diners 94Frictionless Diners 95Attempt Diners 96Challenge JCB Secure 97Frictionless JCB Secure 98Attempt JCB Secure 100Challenge ELO 101Frictionless ELO 102Attempt ELO 103Challenge UPI Secure 104Frictionless UPI Secure 105Attempt UPI Secure Anexo 2: Firma de los mensajes SHA-256Todas las peticiones y respuestas del servicio de consulta REST incluyen una firma digital que garantiza la autenticidad e integridad de los mensajes intercambiados entre el comercio y el TPV Virtual.El sistema de firma se basa en HMAC SHA-512, aunque también está disponible HMAC SHA-256 si la integración no es nueva.A continuación te explicamos el proceso de firma, también tienes en las librerías de Redsys un código que puedes adaptar para la firma de las Consultas REST: Librerías Redsys Firma en la petición (comercio)Para enviar una consulta firmada correctamente, el comercio debe generar la firma utilizando su clave secreta compartida, la misma que usa para firmar operaciones en el TPV Virtual.La clave para producción se obtiene desde Canales, y la de pruebas se envía en el Welcome Pack. Consulta la documentación para más detalles. Proceso para calcular la firma:Genera el objeto «data» con los datos de la operación que deseas consultar.Decodifica la clave SHA-256 de tu terminal en BASE64. Tipado: Binario.Realiza un cifrado 3DES entre:La clave SHA-256 que has decodificado en el paso anterior.El número de pedido idTransaction.Importante: El cifrado utilizado es 3DES (DESede) en modo CBC sin padding automático. Además, se deben añadir los 0s (ceros) necesarios en bytes hasta que sea múltiplo de 8.El resultado es la clave de firma diversificada. Tipado: Binario.Calcula el HMAC-256 de:El valor que se envía en data.La clave de firma diversificada (la clave obtenida en el paso 2).Tipado: Binario.Codifica el HMAC-256 obtenido en el paso anterior en BASE64. El valor resultante es el que se debe enviar en Ds_Signature. Tipado: Texto plano.Ejemplo:Para una petición con los siguientes datos:Valor del elemento «data»: {"fuc":"999008881","idTransaction":"00002730z328","initialDate":"2025-01-01-10.00.00","order":"00002730z328","terminal":"1"}Clave de comercio: sq7HjrUOBfKmC576ILgskD5srU870gJ7El valor de signature es:8uRiPwqqZ8UDhsj0XUzhWjC9hG9eEX6XVuGfpp8YtoxJOfu3jUqtqEj3CPuKqLx3gmnE1dS8CiHZcFQ52IZiOA== Firma para PSPs:En el caso de los PSPs el proceso es igual, pero se sustituye la clave secreta de comercio por la clave de PSP. Verificar firma en la respuestaCuando recibes una respuesta del TPV Virtual tras realizar una consulta, esta viene firmada. Es responsabilidad del comercio verificar la firma para asegurarse de que el mensaje no ha sido alterado y proviene realmente de tu TPV Virtual.Para verificar una consulta correctamente, el comercio utiliza su clave secreta compartida, la misma que usa para firmar operaciones en el TPV Virtual.La clave para producción se obtiene desde Canales, y la de pruebas se envía en el Welcome Pack. Consulta la documentación para más detalles.Proceso para verificar la firma:Genera el objeto «data» con los datos de la operación que deseas consultar.Decodifica la clave SHA-256 de tu terminal en BASE64. Tipado: Binario.Realiza un cifrado 3DES entre:La clave SHA-256 que has decodificado en el paso anterior.El número de pedido idTransaction.Importante: El cifrado utilizado es 3DES (DESede) en modo CBC sin padding automático. Además, se deben añadir los 0s (ceros) necesarios en bytes hasta que sea múltiplo de 8.El resultado es la clave de firma diversificada. Tipado: Binario.Calcula el HMAC-256 de:El valor que se envía en data.La clave de firma diversificada (la clave obtenida en el paso 2).Tipado: Binario.Codifica el HMAC-256 obtenido en el paso anterior en BASE64. El valor resultante es el que se debe enviar en Ds_Signature. Tipado: Texto plano.Ejemplo:Para una petición con los siguientes datos: Valor del elemento «data»: {"operations":[{"fuc":"999008881","terminal":"1","csb":"2100","order":"00002730z328","transactionType":"0","date":"2025-03-25 11:25:35.187","state":"F","authorized":"S","authorizationNumber":"868043","amount":"30.20","currency":"978","codResponse":"0","cardNumber":"454881******0003","cardBrand":"1","cardCountry":"724","cardExpiryDate":"4912","cardToken":"991d0fc404eb5ce9e8aa0cb4101da113840db0f5","cardType":"C","paymethod":"78","ipClient":"115.241.28.98","ipCountry":"356","eci":"05","cofUse":"S","cofType":"C","grouperCode":"33333337","productDescription":"1x Subscription test product,","connectionType":"2","merchantData":"eyJtb2R1bGVDb21lbnQiOiJQYXNhcmVsYSBVbmlmaWNhZGEgZGUgUmVkc3lzIHBhcmEgUHJlc3Rhc2hvcCIsImlkQ2FydCI6MjczMCwib3JpZ2luYWxNZXRob2QiOiJUYXJqZXRhIn0"}],"numRecords":1}{"fuc":"999008881","idTransaction":"00002730z328","initialDate":"2025-01-01-10.00.00","order":"00002730z328","terminal":"1"}Clave de comercio: sq7HjrUOBfKmC576ILgskD5srU870gJ7El valor de signature es:AC2fXHqjoyauWwSuHBCdH4GSU_xRMzLkRSlh5KZ-BJGeqgalPYgsxFBwyRrlkX7JBfjnnPGKsAb0mtRwYDf-pA==8uRiPwqqZ8UDhsj0XUzhWjC9hG9eEX6XVuGfpp8YtoxJOfu3jUqtqEj3CPuKqLx3gmnE1dS8CiHZcFQ52IZiOA== Firma para PSPs:En el caso de los PSPs el proceso es igual, pero se sustituye la clave secreta de comercio por la clave de PSP.