PayGold ¿Qué es PayGold?PayGold permite solicitar pagos a clientes de forma rápida y segura mediante un enlace que se envía directamente al cliente. No es necesario disponer de una tienda online, aunque también puede utilizarse sin problema en comercios que ya cuentan con una.El enlace de pago puede enviarse por:SMSCorreo electrónicoWhatsAppCódigo QRAl acceder al enlace, el cliente es dirigido a la pasarela de pago del TPV Virtual, donde puede completar la transacción de forma sencilla y totalmente segura. Además, si la pasarela cuenta con una personalización, esta se aplica igualmente a las operaciones realizadas con PayGold.Esta solución es ideal para cobrar servicios personalizados, ajustes de precio o importes adicionales fuera del entorno habitual de venta online.Activación y uso de PayGoldPara activar PayGold tienes que solicitarlo a Oficina mediante tu correo autorizado. Una vez activo, PayGold se trata como un terminal aparte. Ten esto en cuenta en tu integración. Puedes generar un enlace de pago PayGold mediante petición REST (como verás en este documento) o mediante Canales. Tienes que solicitar a Oficina la activación de PayGold. Necesidad de PCI DSSCon PayGold, hagas la operativa que hagas, NO necesitas cumplir con PCI DSS:Al enviar al cliente un enlace de pago, la gestión de los datos de la tarjeta son gestionados por el TPV Virtual. Flujo de PayGoldEl flujo de pago en PayGold es el siguiente:Petición de pago: El comercio solicita el pago al TPV Virtual (vía REST o desde Canales), indicando el importe y los datos de contacto del cliente (email y/o móvil).Envío del enlace al cliente: El TPV Virtual envía automáticamente un enlace de pago por SMS y/o email al cliente.Acceso al formulario de pago: El cliente accede al enlace, que abre el TPV Virtual con el formulario para introducir los datos de su tarjeta. Por defecto el link no caduca, pero puedes configurar un tiempo de validez.Si el comercio tiene habilitado DCC y la tarjeta lo permite, se ofrecerá cambio de divisa.Autenticación 3DS: Si el comercio lo requiere, se inicia el proceso de autenticación del titular mediante 3D Secure.Autorización del pago: Una vez autenticado (si aplica), el TPV Virtual solicita la autorización a la entidad emisora.Notificación del resultado: El TPV notifica al comercio por email o vía HTTP (si se usó REST), con el resultado de la operación.Recibo para el cliente: El cliente visualiza un recibo en pantalla con el resultado del pago. PayGold REST: integración paso a pasoA continuación tienes los pasos para integrar PayGold por REST junto a algunos ejemplos de código. Recuerda: Adapta los ejemplos de código a tus necesidades. Los bloques de código son un ejemplo para entender más fácilmente el proceso. Adapta tu código a tus necesidades. Consulta las librerías de Redsys para ver más ejemplos. No hay librería específica de PayGold. Adáptala a los pasos que se indican a continuación. Librerías de Redsys Paso 1: Crea y envía un formulario con los datos del pagoEl primer paso de la integración REST es:Crear un formulario en formato JSON con los datos de la petición de pago.Enviar el formulario al TPV Virtual. El formulario se envía como una petición POST.El formulario se envía mediante una petición POST a la URL indicada según el entorno: Tipo de peticiónEntornoURL trataPeticionPruebashttps://sis-t.redsys.es:25443/sis/rest/trataPeticionREST Producciónhttps://sis.redsys.es/sis/rest/trataPeticionREST Los campos que se envían en el formulario son: CampoDescripción Ds_SignatureVersionVersión del algoritmo que se usa para la firma de la petición. Ds_MerchantParametersDatos de la petición de pago. Se recopilan los datos en un JSON y se codifican en BASE64. Sin retornos de carro. El resultado codificado en BASE64 es lo que se envía en este campo. Ds_SignatureFirma de la petición. Se obtiene a partir del valor codificado en BASE64 del Ds_MerchantParameters y la clave de tu terminal. Importante: Antes de integrar, ten en cuenta estas consideraciones: En las peticiones REST, tienes que enviar la siguiente cabecera con el siguiente valor: Content-Type: application/json. A continuación tienes la explicación de los valores que se envían en los campos del formulario de ejemplo: Ds_SignatureVersionEl campo Ds_SignatureVersion indica la versión del algoritmo que se utiliza para la firma. Se utiliza la misma versión para todas las peticiones.Campo: Ds_SignatureVersionValor a enviar: HMAC_SHA512_V2Nota: Si firmas con el algoritmo SHA 256, tendrás que enviar:HMAC_SHA256_V1 Ds_MerchantParameters¿Qué es?Datos de la petición de pago recopilados en un JSON y codificados en BASE64.Esta es la tabla con los parámetros que se tienen que mandar en el JSON al operar con PayGold. Los parámetros se pueden enviar en mayúsculas DS_MERCHANT_TERMINAL o como CamelCase Ds_Merchant_Terminal. NO se pueden combinar ambas formas, elige en mayúsculas O en CamelCase. ¿Cómo se obtiene?Recopila los parámetros para una operación. Este es un ejemplo para una autorización PayGold vía REST recopilados en un JSON: { "DS_MERCHANT_MERCHANTCODE": "999008881", "DS_MERCHANT_TERMINAL": "99", "DS_MERCHANT_TRANSACTIONTYPE": "15", "DS_MERCHANT_AMOUNT": "100", "DS_MERCHANT_CURRENCY": "978", "DS_MERCHANT_ORDER": "30345780", "DS_MERCHANT_MERCHANTURL": "https:\/\/webhook.site\/8f361c97-1d42-47fd-bdfc-1a6ef55b951c", "DS_MERCHANT_URLOK": "https:\/\/www.example.com\/ok", "DS_MERCHANT_URLKO": "https:\/\/www.example.com\/ok", "DS_MERCHANT_P2F_EXPIRYDATE": "2025-12-31-17.30.35.318", "DS_MERCHANT_CUSTOMER_MOBILE": "600600600", "DS_MERCHANT_CUSTOMER_SMS_TEXT": "Esto es un SMS personalizado del comercio @COMERCIO@. Debe pagar @IMPORTE@ @MONEDA@ en la siguiente url: @URL@", "DS_MERCHANT_CUSTOMER_MAIL": "mail@mail.com" } Consulta los parámetros que tienes que incluir en la petición en esta sección. El JSON con los parámetros debe estar correctamente formado. Esto implica:Sin espacios en blanco en los parámetros.Todos los parámetros son tipo cadena string. Da igual que sean números o alfanuméricos.El importe se debe indicar en céntimos. No se pueden enviar decimales. Por ejemplo, para un importe de 9,50€ se envía 950. Una vez creado el JSON, se codifica en BASE64. El JSON anterior codificado en BASE64 da como resultado esta cadena: ewogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UQ09ERSI6ICI5OTkwMDg4ODEiLAogICAgIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5IiwKICAgICJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMTUiLAogICAgIkRTX01FUkNIQU5UX0FNT1VOVCI6ICIxMDAiLAogICAgIkRTX01FUkNIQU5UX0NVUlJFTkNZIjogIjk3OCIsCiAgICAiRFNfTUVSQ0hBTlRfT1JERVIiOiAiMzAzNDU3ODAiLAogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UVVJMIjogImh0dHBzOlwvXC93ZWJob29rLnNpdGVcLzhmMzYxYzk3LTFkNDItNDdmZC1iZGZjLTFhNmVmNTViOTUxYyIsCiAgICAiRFNfTUVSQ0hBTlRfVVJMT0siOiAiaHR0cHM6XC9cL3d3dy5leGFtcGxlLmNvbVwvb2siLAogICAgIkRTX01FUkNIQU5UX1VSTEtPIjogImh0dHBzOlwvXC93d3cuZXhhbXBsZS5jb21cL29rIiwKICAgICJEU19NRVJDSEFOVF9QMkZfRVhQSVJZREFURSI6ICIyMDI1LTEyLTMxLTE3LjMwLjM1LjMxOCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfTU9CSUxFIjogIjYwMDYwMDYwMCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfU01TX1RFWFQiOiAiRXN0byBlcyB1biBTTVMgcGVyc29uYWxpemFkbyBkZWwgY29tZXJjaW8gQENPTUVSQ0lPQC4gRGViZSBwYWdhciBASU1QT1JURUAgQE1PTkVEQUAgZW4gbGEgc2lndWllbnRlIHVybDogQFVSTEAiLAogICAgIkRTX01FUkNIQU5UX0NVU1RPTUVSX01BSUwiOiAibWFpbEBtYWlsLmNvbSIKfQ== Esta es la cadena que se debe enviar en el campo Ds_MerchantParameters. Campo: Ds_MerchantParameters Valor a enviar: Cadena resultante de codificar el JSON con los datos de la petición de pago en BASE64. Ds_SignatureA continuación se explica el proceso de cálculo de firma SHA-512 V2.Para nuevas integraciones recomendamos usar esta firma, aunque ambas son válidas. Si tu comercio ya está integrado, revisa cómo se calcula la firma SHA-256 en el anexo.¿Qué es?Firma de la petición. Para calcular la firma, debes tener estos valores:El valor codificado en BASE64 que se envía en Ds_MerchantParameters.El número de pedido de la operación. Es el valor de Ds_Merchant_Order (sin codificar en BASE64).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 Ds_Merchant_Order (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 Ds_MerchantParameters codificado en BASE64, 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.A continuación tienes un ejemplo en PHP del proceso de generación de firma: <?php // Este es un fragmento de código para realizar la firma. Añádelo al resto de librerías para que el proceso se complete correctamente. class Signature { /****** AES Function ******/ static function encrypt_AES($data, $key) { $fixedKey = str_pad(substr($key, 0, 16), 16, "0"); $firma = base64_encode(openssl_encrypt($data, "aes-128-cbc", $fixedKey, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0")); return $firma; } static function mac512($data, $key) { $sha = hash_hmac('sha512', $data, $key, true); return $sha; } static function createMerchantSignature($key, $data, $diversifyingFactor) { // Se diversifica la clave con el Número de Pedido $key = self::encrypt_AES($diversifyingFactor, $key); // MAC512 del parámetro Ds_Parameters que envía Redsys $res = self::mac512($data, $key); // Se codifican los datos Base64 return Utils::base64_url_encode_safe($res); } // Función para comparar firmas. Utilizado en la verificación de la notificación. static function checkSignatures($sig1, $sig2) { if (strcasecmp($sig1, $sig2) !== 0) { throw new Exception("Integrity failure. The received signature does not match the calculated one."); } } } ?> Este código es un ejemplo para entender más fácilmente el proceso. Adapta el código a las necesidades de tu integración e incluye el resto de librerías necesarias para su funcionamiento. Consulta las librerías de Redsys para ver el código completo, recomendamos utilizar la última versión de las librerías: Librerías de Redsys Campo: Ds_SignatureValor a enviar: Valor resultante del paso 5. ¿Qué hago cuando tenga el formulario montado?Envía el formulario con los campos obtenidos. Paso 2: Recepción y gestión de la notificación No valides el número de parámetros que recibes en una notificación. El nº de parámetros recibidos puede variar entre operativas o por nuevas normativas. ¿Qué es?La notificación se envía desde el TPV Virtual al servidor del comercio una vez finaliza la operación. En PayGold con la integración REST, la notificación informa de:El resultado de la operación y otros datos.La URL de pago que tienes que enviar por mail/SMS al cliente. Se recibe en el parámetro DS_URLPAGO2FASES.ConfiguraciónLa notificación se recibe en la URL que indiques en el campo DS_MERCHANT_MERCHANTURL enviado en la petición.La notificación se recibe una vez el cliente ha completado el pago en el enlace de pago que le has compartido previamente. ¿Qué recibo en la notificación?La notificación es un JSON con los datos de la operación y su resultado. Los campos que se reciben en la notificación son iguales a los del formulario de la petición, pero con significados distintos: CampoDescripción Ds_SignatureVersionVersión del algoritmo que se usa para la firma. Ds_MerchantParametersDatos de la respuesta. Están codificados en BASE64 y sin retornos de carro. Lo componen los parámetros indicados en la tabla con los parámetros de salida. Ds_SignatureFirma de la petición. Se obtiene a partir del valor codificado en BASE64 del Ds_MerchantParameters y la clave de tu terminal. En la notificación, el comercio debe validar que esta firma coincida con la de la petición. ¿Cómo veo el resultado de la operación?Los parámetros que se reciben en Ds_MerchantParameters contienen el enlace de pago e indican el resultado de la operación. Estos parámetros vienen codificados en BASE64, para ver el resultado de la operación:Decodifica el campo Ds_MerchantParameters. (este proceso lo puedes implementar en la validación).Recupera el parámetro Ds_Response. Este campo indica el código de respuesta. (Este proceso lo puedes implementar en la validación).El valor 0000 o 9998 indica que la operación se ha registrado y el cliente tiene que finalizarla. Para el resto de valores consulta la tabla de códigos de respuesta.Recupero el parámetro DS_URLPAGO2FASES. Contiene la URL de pago que tienes que enviar al cliente por SMS/Email.Este es un ejemplo de la notificación recibida (son los parámetros del campo Ds_MerchantParameters decodificados) : { "Ds_Amount":"1050", "Ds_Currency":"978", "Ds_Order":"7422971591", "Ds_MerchantCode":"999008881", "Ds_Terminal":"99", "Ds_Response":"9998", "Ds_AuthorisationCode":"", "Ds_TransactionType":"F", "Ds_SecurePayment":"0", "Ds_Language":"1", "Ds_MerchantData":"", "Ds_UrlPago2Fases":"http://sis-t.redsys.es/sis/p2f?t=BN893229101EDE461014918EFDD0FLO91234DF" } Importante: El parámetro DS_URLPAGO2FASES contiene la URL que tienes que enviar al cliente.Este parámetro no está en la API, por lo que para mandar esta URL por canales internos requiere modificar la API. Esta modifciación se hará bajo la responsabilidad del propio comercio. ¿Qué debo validar en la notificación? A continuación se explica el proceso de cálculo de firma SHA-512 V2. Para nuevas integraciones recomendamos usar esta firma, aunque ambas son válidas. Si tu comercio ya está integrado, revisa cómo se calcula la firma SHA-256 en el anexo. Una vez se recibe la notificación, es necesario capturar y validar los campos de la misma antes de realizar acciones en el servidor del comercio. Estos son los pasos a seguir en la validación de la notificación:Recupera los parámetros recibidos en la notificación online: Ds_SignatureVersion , Ds_MerchantParameters y Ds_Signature.Decodifica el parámetro Ds_MerchantParameters. Este parámetro decodificado contiene información de la operaciónRecupera los parámetros que necesites.Para validar la firma de la operación, tendrás que recuperar el Ds_Order.Importante: Antes de realizar ninguna acción en tu servidor, valida la firma Ds_Signature recibida. Son los mismos pasos que en la creación de la firma para la petición, pero con los parámetros de la notificación: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 que has recuperado de la notificación Ds_Order (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 Ds_MerchantParameters codificado en BASE64, utilizando la clave diversificada obtenida en el paso anterior.Codifica en BASE64URL: Se codifica el resultado del HMAC-SHA512 en BASE64URL.Compara el valor obtenido: El valor que has obtenido es el Ds_Signature calculado a partir de la notificación. Compáralo con el Ds_Signature que has enviado en la petición.Si coinciden, el flujo no ha sido alterado y puedes seguir con el proceso.A continuación tienes un ejemplo en PHP del proceso de recepción y validación de la notificación: <?php // Este es un fragmento de código para realizar la firma y la verificación de notificación. // Añade este código al resto de librerías de Redsys, para tener el proceso completo. class Signature { /****** AES Function ******/ static function encrypt_AES($data, $key) { $fixedKey = str_pad(substr($key, 0, 16), 16, "0"); $firma = base64_encode(openssl_encrypt($data, "aes-128-cbc", $fixedKey, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0")); return $firma; } static function mac512($data, $key) { $sha = hash_hmac('sha512', $data, $key, true); return $sha; } static function createMerchantSignature($key, $data, $diversifyingFactor) { // Se diversifica la clave con el Número de Pedido $key = self::encrypt_AES($diversifyingFactor, $key); // MAC512 del parámetro Ds_Parameters que envía Redsys $res = self::mac512($data, $key); // Se codifican los datos Base64 return Utils::base64_url_encode_safe($res); } // Función para comparar firmas. Utilizado en la verificación de la notificación. static function checkSignatures($sig1, $sig2) { if (strcasecmp($sig1, $sig2) !== 0) { throw new Exception("Integrity failure. The received signature does not match the calculated one."); } } } ?> Este código es un ejemplo para entender más fácilmente el proceso. Adapta el código a las necesidades de tu integración e incluye el resto de librerías necesarias para su funcionamiento. Consulta las librerías de Redsys para ver el código completo, recomendamos utilizar la última versión de las librerías: Librerías de Redsys Parámetros petición PayGoldComo hemos visto en el punto anterior el Ds_MerchantParameters se envía en el formulario. A continuación tienes los parámetros que se tienen que incluir en el campo Ds_MerchantParameters para una operación PayGold.Con PayGold puedes lanzar distintas operativas:Petición de pago normal.Petición de generación de referencia/tokenización (para posterior pago 1-clic).Envía las peticiones a los siguientes endpoints: Tipo de peticiónEntornoURL trataPeticionPruebashttps://sis-t.redsys.es:25443/sis/rest/trataPeticionREST Producciónhttps://sis.redsys.es/sis/rest/trataPeticionREST El código de pedido DS_MERCHANT_ORDER no se puede repetir nunca entre transacciones. Petición de pagoEstos son los parámetros que tienes que enviar dentro del campo Ds_MerchantParameters para una petición de pago PayGold: ParámetroFormatoRequerido/OpcionalDescripciónEjemplo DS_MERCHANT_MERCHANTCODE9 caracteres NuméricoRequeridoCódigo FUC o número de comercio. No cambia entre entornos. 110034987 DS_MERCHANT_TERMINAL3 caracteres NuméricoRequeridoNúmero de terminal de tu comercio. Puede cambiar entre entornos.99 DS_MERCHANT_AMOUNT12 caracteres máximo NuméricoRequeridoImporte de la operación. Los últimos 2 dígitos corresponden a los decimales. Por ejemplo, para una operación de 10,50€, se envía 1050.1050 DS_MERCHANT_CURRENCY4 caracteres NuméricoRequeridoCódigo ISO 4217 de la divisa utilizada en la transacción. Ver códigos ISO divisas.978 DS_MERCHANT_ORDER12 caracteres Alfanumérico * (caracteres ASCII: del 48 al 57, del 65 al 90 y del 97 al 122)RequeridoCódigo de pedido. No se puede repetir un código de pedido. Recomendamos que los 4 primeros dígitos sean numéricos, para evitar problemas en la liquidación. *Sólo se permiten caracteres ASCII: – Dígitos (0–9): ASCII 48 a 57. Letras mayúsculas (A–Z): ASCII 65 a 90. – Letras minúsculas (a–z): ASCII 97 a 122. – No se permiten espacios, símbolos ni acentos.1234ABcd56EF DS_MERCHANT_TRANSACTIONTYPEValores disponibles: – F o 15RequeridoTipo de transacción. El valor enviado (F) indica que es una operación PayGold. 15 DS_MERCHANT_MERCHANTURL250 caracteres máximo AlfanuméricoRequeridoURL a la que se envía la notificación POST con el resultado de la transacción. https://www.example.com/notification DS_MERCHANT_URLOK250 caracteres AlfanuméricoRequeridoURL a la que se redirige al cliente mediante una petición HTTP GET si la transacción es exitosa (OK). Si no se envía este parámetro, se usará la URL OK configurada en Canales.https://www.example.com/ok DS_MERCHANT_URLKO250 caracteres AlfanuméricoRequeridoURL a la que se redirige al cliente mediante una petición HTTP GET si la transacción falla (KO). Si no se envía este parámetro, se usará la URL KO configurada en Canales. https://www.example.com/ko DS_MERCHANT_CUSTOMER_MOBILE19 caracteres máximo AlfanuméricoRequerido*Teléfono del cliente al que se le envía el SMS con el enlace de pago. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXT – DS_MERCHANT_P2F_XMLDATA600600600 DS_MERCHANT_CUSTOMER_MAIL100 caracteres máximo AlfanuméricoRequerido*Dirección de correo del cliente al que se le envía el SMS con el enlace de pago. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXTmail@ejemplo.com DS_MERCHANT_P2F_EXPIRYDATEFormato: – aaaa-mm-dd-HH.MM.ss.ssssRequerido*Permite especificar la fecha de caducidad del enlace, siendo posible especificar la fecha de cada operación. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_CUSTOMER_SMS_TEXT2025-12-31-17.30.35.318 DS_MERCHANT_CUSTOMER_SMS_TEXT160 caracteres máximo AlfanuméricoRequerido*Envía un mensaje SMS personalizado al cliente. Este campo contendrá una cadena de texto con los campos relevantes entre arrobas (@), es obligatorio incluir siempre la URL (@URL@). Los campos soportados son @COMERCIO@, @IMPORTE@, @MONEDA@ y @URL@. Se sustituirán dichos campos por los valores correspondientes. Es recomendable limitar la longitud del texto (máximo 160 caracteres) para que se envíe en un único SMS. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATEEsto es un SMS personalizado del comercio @COMERCIO@. Debe pagar @IMPORTE@ @MONEDA@ en la siguiente url: @URL@ DS_MERCHANT_P2F_XMLDATAValores admitidos: – nombreComprador: El nombre del comprador. Sin limitación de caracteres. – direccionComprador: La dirección del comprador. Sin limitación de caracteres. – textoLibre1: El texto que se incluirá describiendo la compra. Sin limitación de caracteres. – subjectMailCliente: Asunto del correo, resume lo máximo posible. OpcionalPersonalización de los mensajes de correo enviados. Permite pasar TAGs para la personalización. Es importante escapar los símbolos < > y / como < > y / así como dejarlos dentro del CDATA. Cualquier error aquí podría ocasionar que el XML no esté bien formado y que la petición falle por lo que es obligatorio escapar también los caracteres especiales como acentos etc. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXTNOMBRE DEL COMPRADORDIRECCION DEL COMPRADORTEXTO LIBREASUNTO EMAIL DS_MERCHANT_PAYMETHODSLetra. Valores posibles: – C (tarjetas) – z (bizum) – P (paypal) – xpay (Google Pay y Apple Pay) – R (transferencia)OpcionalMétodo de pago que se aplica en la operación. Si no se envía este parámetro, se mostrarán por defecto todos los métodos de pago que tenga el comercio.C Envía estos campos en Ds_MerchantParameters y sigue todo el proceso de envío del formulario explicado en el punto «Paygold REST: Integración paso a paso«. El enlace de pago se enviará al número de teléfono y/o al correo electrónico indicados en la petición. Ds_MerchantParameters formato JSON Ds_MerchantParameters codificado BASE64 { "DS_MERCHANT_MERCHANTCODE": "999008881", "DS_MERCHANT_TERMINAL": "99", "DS_MERCHANT_TRANSACTIONTYPE": "15", "DS_MERCHANT_AMOUNT": "100", "DS_MERCHANT_CURRENCY": "978", "DS_MERCHANT_ORDER": "30345780", "DS_MERCHANT_MERCHANTURL": "https:\/\/webhook.site\/8f361c97-1d42-47fd-bdfc-1a6ef55b951c", "DS_MERCHANT_URLOK": "https:\/\/www.example.com\/ok", "DS_MERCHANT_URLKO": "https:\/\/www.example.com\/ok", "DS_MERCHANT_P2F_EXPIRYDATE": "2025-12-31-17.30.35.318", "DS_MERCHANT_CUSTOMER_MOBILE": "600600600", "DS_MERCHANT_CUSTOMER_SMS_TEXT": "Esto es un SMS personalizado del comercio @COMERCIO@. Debe pagar @IMPORTE@ @MONEDA@ en la siguiente url: @URL@", "DS_MERCHANT_CUSTOMER_MAIL": "mail@mail.com" } ewogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UQ09ERSI6ICI5OTkwMDg4ODEiLAogICAgIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5IiwKICAgICJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMTUiLAogICAgIkRTX01FUkNIQU5UX0FNT1VOVCI6ICIxMDAiLAogICAgIkRTX01FUkNIQU5UX0NVUlJFTkNZIjogIjk3OCIsCiAgICAiRFNfTUVSQ0hBTlRfT1JERVIiOiAiMzAzNDU3ODAiLAogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UVVJMIjogImh0dHBzOlwvXC93ZWJob29rLnNpdGVcLzhmMzYxYzk3LTFkNDItNDdmZC1iZGZjLTFhNmVmNTViOTUxYyIsCiAgICAiRFNfTUVSQ0hBTlRfVVJMT0siOiAiaHR0cHM6XC9cL3d3dy5leGFtcGxlLmNvbVwvb2siLAogICAgIkRTX01FUkNIQU5UX1VSTEtPIjogImh0dHBzOlwvXC93d3cuZXhhbXBsZS5jb21cL29rIiwKICAgICJEU19NRVJDSEFOVF9QMkZfRVhQSVJZREFURSI6ICIyMDI1LTEyLTMxLTE3LjMwLjM1LjMxOCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfTU9CSUxFIjogIjYwMDYwMDYwMCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfU01TX1RFWFQiOiAiRXN0byBlcyB1biBTTVMgcGVyc29uYWxpemFkbyBkZWwgY29tZXJjaW8gQENPTUVSQ0lPQC4gRGViZSBwYWdhciBASU1QT1JURUAgQE1PTkVEQUAgZW4gbGEgc2lndWllbnRlIHVybDogQFVSTEAiLAogICAgIkRTX01FUkNIQU5UX0NVU1RPTUVSX01BSUwiOiAibWFpbEBtYWlsLmNvbSIKfQ== Petición de tokenización y pago 1-clicEl comercio tiene que pedir a su oficina la activación de la tokenización. Con PayGold, puedes lanzar links de pago para generar una referencia o token de la tarjeta, y luego lanzar peticiones de pago con el token para que el cliente no tenga que introducir los datos de la tarjeta. Para poder operar con tokenización y pagos 1-clic el comercio tiene que pedir su activación a su oficina. La tokenización se activa para todo el comercio y sus terminales. Estos son los parámetros que tienes que enviar dentro del campo Ds_MerchantParameters para una tokenización y para el pago 1-clic:Recuerda: El campo DS_MERCHANT_IDENTIFIER sirve tanto como para pedir la referencia (valor REQUIRED) como para enviar la referencia (valor recibido en la notificación donde se pide la referencia). ParámetroFormatoRequerido/OpcionalDescripciónEjemplo DS_MERCHANT_MERCHANTCODE9 caracteres NuméricoRequeridoCódigo FUC o número de comercio. No cambia entre entornos. 110034987 DS_MERCHANT_TERMINAL3 caracteres NuméricoRequeridoNúmero de terminal de tu comercio. Puede cambiar entre entornos.99 DS_MERCHANT_AMOUNT12 caracteres máximo NuméricoRequeridoImporte de la operación. Los últimos 2 dígitos corresponden a los decimales. Por ejemplo, para una operación de 10,50€, se envía 1050.1050 DS_MERCHANT_CURRENCY4 caracteres NuméricoRequeridoCódigo ISO 4217 de la divisa utilizada en la transacción. Ver códigos ISO divisas.978 DS_MERCHANT_ORDER12 caracteres Alfanumérico * (caracteres ASCII: del 48 al 57, del 65 al 90 y del 97 al 122)RequeridoCódigo de pedido. No se puede repetir un código de pedido. Recomendamos que los 4 primeros dígitos sean numéricos, para evitar problemas en la liquidación. *Sólo se permiten caracteres ASCII: – Dígitos (0–9): ASCII 48 a 57. Letras mayúsculas (A–Z): ASCII 65 a 90. – Letras minúsculas (a–z): ASCII 97 a 122. – No se permiten espacios, símbolos ni acentos.1234ABcd56EF DS_MERCHANT_TRANSACTIONTYPEValores disponibles: – F o 15RequeridoTipo de transacción. El valor enviado (F) indica que es una operación PayGold. 15 DS_MERCHANT_MERCHANTURL250 caracteres máximo AlfanuméricoRequeridoURL a la que se envía la notificación POST con el resultado de la transacción. https://www.example.com/notification DS_MERCHANT_URLOK250 caracteres AlfanuméricoRequeridoURL a la que se redirige al cliente mediante una petición HTTP GET si la transacción es exitosa (OK). Si no se envía este parámetro, se usará la URL OK configurada en Canales.https://www.example.com/ok DS_MERCHANT_URLKO250 caracteres AlfanuméricoRequeridoURL a la que se redirige al cliente mediante una petición HTTP GET si la transacción falla (KO). Si no se envía este parámetro, se usará la URL KO configurada en Canales. https://www.example.com/ko DS_MERCHANT_CUSTOMER_MOBILE19 caracteres máximo AlfanuméricoRequerido*Teléfono del cliente al que se le envía el SMS con el enlace de pago. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXT – DS_MERCHANT_P2F_XMLDATA600600600 DS_MERCHANT_CUSTOMER_MAIL100 caracteres máximo AlfanuméricoRequerido*Dirección de correo del cliente al que se le envía el SMS con el enlace de pago. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXTmail@ejemplo.com DS_MERCHANT_P2F_EXPIRYDATEFormato: – aaaa-mm-dd-HH.MM.ss.ssssRequerido*Permite especificar la fecha de caducidad del enlace, siendo posible especificar la fecha de cada operación. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_CUSTOMER_SMS_TEXT2025-12-31-17.30.35.318 DS_MERCHANT_CUSTOMER_SMS_TEXT160 caracteres máximo AlfanuméricoRequerido*Envía un mensaje SMS personalizado al cliente. Este campo contendrá una cadena de texto con los campos relevantes entre arrobas (@), es obligatorio incluir siempre la URL (@URL@). Los campos soportados son @COMERCIO@, @IMPORTE@, @MONEDA@ y @URL@. Se sustituirán dichos campos por los valores correspondientes. Es recomendable limitar la longitud del texto (máximo 160 caracteres) para que se envíe en un único SMS. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATEEsto es un SMS personalizado del comercio @COMERCIO@. Debe pagar @IMPORTE@ @MONEDA@ en la siguiente url: @URL@ DS_MERCHANT_P2F_XMLDATAValores admitidos: – nombreComprador: El nombre del comprador. Sin limitación de caracteres. – direccionComprador: La dirección del comprador. Sin limitación de caracteres. – textoLibre1: El texto que se incluirá describiendo la compra. Sin limitación de caracteres. – subjectMailCliente: Asunto del correo, resume lo máximo posible. OpcionalPersonalización de los mensajes de correo enviados. Permite pasar TAGs para la personalización. Es importante escapar los símbolos < > y / como < > y / así como dejarlos dentro del CDATA. Cualquier error aquí podría ocasionar que el XML no esté bien formado y que la petición falle por lo que es obligatorio escapar también los caracteres especiales como acentos etc. *Requerido si se envían: – DS_MERCHANT_CUSTOMER_MOBILE – DS_MERCHANT_CUSTOMER_MAIL – DS_MERCHANT_P2F_EXPIRYDATE – DS_MERCHANT_CUSTOMER_SMS_TEXTNOMBRE DEL COMPRADORDIRECCION DEL COMPRADORTEXTO LIBREASUNTO EMAIL DS_MERCHANT_PAYMETHODSLetra. Valores posibles: – C (tarjetas) – z (bizum) – P (paypal) – xpay (Google Pay y Apple Pay) – R (transferencia)OpcionalMétodo de pago que se aplica en la operación. Si no se envía este parámetro, se mostrarán por defecto todos los métodos de pago que tenga el comercio.C DS_MERCHANT_IDENTIFIERValores posibles: – Para generar referencia: REQUIRED – Para enviar el token generado: 40 caracteres y numéricoRequeridoPuede indicar dos cosas: – Indica la solicitud de generar la referencia. – Indica el token de la tarjeta. * Requerido para la primera operación COF y el pago 1-clic.REQUIRED DS_MERCHANT_GROUP9 caracteres NuméricoOpcional Código del grupo de comercios. Para comercios que compartan referencias. Envía estos campos en Ds_MerchantParameters y sigue todo el proceso de envío del formulario explicado en el punto «Paygold REST: Integración paso a paso«.El enlace de pago se enviará al número de teléfono y/o al correo electrónico indicados en la petición.Una vez has solicitado la referencia y la has recibido en la notificación, puedes lanzar el resto de peticiones con DS_MERCHANT_IDENTIFIER y el valor de la referencia. Ds_MerchantParameters formato JSON Ds_MerchantParameters codificado BASE64 { "DS_MERCHANT_MERCHANTCODE": "999008881", "DS_MERCHANT_TERMINAL": "99", "DS_MERCHANT_TRANSACTIONTYPE": "15", "DS_MERCHANT_AMOUNT": "100", "DS_MERCHANT_CURRENCY": "978", "DS_MERCHANT_ORDER": "78085098", "DS_MERCHANT_MERCHANTURL": "https:\/\/webhook.site\/8f361c97-1d42-47fd-bdfc-1a6ef55b951c", "DS_MERCHANT_URLOK": "https:\/\/www.example.com\/ok", "DS_MERCHANT_URLKO": "https:\/\/www.example.com\/ok", "DS_MERCHANT_P2F_EXPIRYDATE": "2025-12-31-17.30.35.318", "DS_MERCHANT_CUSTOMER_MOBILE": "600600600", "DS_MERCHANT_CUSTOMER_SMS_TEXT": "Esto es un SMS personalizado del comercio @COMERCIO@. Debe pagar @IMPORTE@ @MONEDA@ en la siguiente url: @URL@", "DS_MERCHANT_CUSTOMER_MAIL": "mail@mail.com", "DS_MERCHANT_IDENTIFIER": "REQUIRED" } ewogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UQ09ERSI6ICI5OTkwMDg4ODEiLAogICAgIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5IiwKICAgICJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMTUiLAogICAgIkRTX01FUkNIQU5UX0FNT1VOVCI6ICIxMDAiLAogICAgIkRTX01FUkNIQU5UX0NVUlJFTkNZIjogIjk3OCIsCiAgICAiRFNfTUVSQ0hBTlRfT1JERVIiOiAiNzgwODUwOTgiLAogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UVVJMIjogImh0dHBzOlwvXC93ZWJob29rLnNpdGVcLzhmMzYxYzk3LTFkNDItNDdmZC1iZGZjLTFhNmVmNTViOTUxYyIsCiAgICAiRFNfTUVSQ0hBTlRfVVJMT0siOiAiaHR0cHM6XC9cL3d3dy5leGFtcGxlLmNvbVwvb2siLAogICAgIkRTX01FUkNIQU5UX1VSTEtPIjogImh0dHBzOlwvXC93d3cuZXhhbXBsZS5jb21cL29rIiwKICAgICJEU19NRVJDSEFOVF9QMkZfRVhQSVJZREFURSI6ICIyMDI1LTEyLTMxLTE3LjMwLjM1LjMxOCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfTU9CSUxFIjogIjYwMDYwMDYwMCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VTVE9NRVJfU01TX1RFWFQiOiAiRXN0byBlcyB1biBTTVMgcGVyc29uYWxpemFkbyBkZWwgY29tZXJjaW8gQENPTUVSQ0lPQC4gRGViZSBwYWdhciBASU1QT1JURUAgQE1PTkVEQUAgZW4gbGEgc2lndWllbnRlIHVybDogQFVSTEAiLAogICAgIkRTX01FUkNIQU5UX0NVU1RPTUVSX01BSUwiOiAibWFpbEBtYWlsLmNvbSIsCiAgICAiRFNfTUVSQ0hBTlRfSURFTlRJRklFUiI6ICJSRVFVSVJFRCIKfQ== Códigos de error de PayGold y generalesEn la notificación recibes el parámetro DS_RESPONSE, que son unos dígitos que indican el resultado de la operación.También puedes recibir el parámetro DS_ERRORCODE.En el siguiente enlace tienes los códigos de error y denegaciones: Códigos de error y denegaciones Anexo: Firma de la petición SHA-256A continuación se explica el proceso de cálculo de la firma SHA-256.Esta firma es utilizada en los siguientes pasos de la integración:En el envío de la petición. Es el valor que se envía en Ds_Signature.En la validación de la notificación. Se tiene que validar la firma recibida en la notificación para comprobar que coinciden.Para nuevas integraciones recomendamos usar la firma SHA-512, aunque ambas son válidas.¿Qué es?Firma de la petición. Para calcular la firma, debes tener estos valores:El valor codificado en BASE64 que se envía en Ds_MerchantParameters. El número de pedido de la operación. Es el valor de Ds_Merchant_Order (sin codificar en BASE64).La clave SHA-256 de tu terminal. Esta clave cambia del entorno de pruebas y el de producción. Tipado: Texto plano.La clave SHA-256 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.¿Cómo se obtiene?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 Ds_Merchant_Order.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 Ds_MerchantParameters.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.Este es un ejemplo en PHP de cómo generar la firma de Ds_Signature siguiendo los pasos anteriores: <?php function createMerchantSignature($key){ $key = $this->decodeBase64($key); // 1. Decodifica la clave SHA-256 en base64 $ent = $this->createMerchantParameters(); // Crea el JSON con los datos y lo codifica en base64 (utilizado en el paso 3) $key = $this->encrypt_3DES($this->getOrder(), $key); // 2. Aplica 3DES con el número de pedido y la clave decodificada la función para encriptar es 3DES Function $res = $this->mac256($ent, $key); // 3. Calcula el HMAC-SHA256. Lo hace en la función return $this->encodeBase64($res); // 4. Codifica el HMAC resultante en base64. Será el valor enviado en Ds_Signature } /****** 3DES Function ******/ function encrypt_3DES($message, $key){ // Se cifra $l = ceil(strlen($message) / 8) * 8; return substr(openssl_encrypt($message . str_repeat("\0", $l - strlen($message)), 'des-ede3-cbc', $key, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0"), 0, $l); } /****** MAC Function ******/ function mac256($ent,$key){ $res = hash_hmac('sha256', $ent, $key, true);//(PHP 5 >= 5.1.2) return $res; } ?> Este código es un ejemplo para entender más fácilmente el proceso. Adapta el código a las necesidades de tu integración e incluye el resto de librerías necesarias para su funcionamiento. Descarga las librerías de Redsys para implementar la firma SHA-256 en tu integración. Librerías de Redsys Firma SHA-256 para validar la notificaciónUna vez se recibe la notificación, es necesario capturar y validar los campos de la misma antes de realizar acciones en el servidor del comercio. Estos son los pasos a seguir en la validación de la notificación:Recupera los parámetros recibidos en la notificación online: Ds_SignatureVersion , Ds_MerchantParameters y Ds_Signature.Decodifica el parámetro Ds_MerchantParameters. Este parámetro decodificado contiene los parámetros que indican el resultado de la operación.Una vez decodificado el parámetro Ds_MerchantParameters, recupera los parámetros que necesites.Importante: Antes de realizar ninguna acción en tu servidor, valida la firma Ds_Signature recibida. Son los mismos pasos que en la creación de la firma para la petición, pero con los parámetros de la notificación:Esto implica utilizar el número de pedido Ds_Order recibido en la notificación (este parámetro lo recuperas al decodificar el parámetro Ds_MerchantParameters de la notificación.Realiza el cálculo de la firma y compara el valor obtenido con el Ds_Signature recibido en la notificación.
