Autenticación con firma
Para garantizar una mayor comodidad y seguridad a sus clientes, Portal Carat ofrece, además de la autenticación a través de la llamada POST a la URL registrada ([más información] (recarga-rest-begin.md # parametros-enviados-por- el- e-sitef-en-el-post-https)), la opción de firma de mensajes, en la que se garantiza la integridad y autenticidad del contenido y del remitente, respectivamente. De esta manera, la tienda recibe la información de la transacción recién creada directamente en la respuesta de su llamada REST y ya no a través del POST de autenticidad.
Que necesitarás#
- Registro activo en el ambiente de aprobación de Portal Carat (obtenido de nuestro equipo de soporte);
- La creación de una clave pública y la gestión de su respectiva clave privada;
- Registro de la clave pública en el Portal Carat (realizado a través de nuestro equipo de soporte).
Creando claves públicas y privadas#
Ejemplos de cómo crear claves públicas y privadas:
- En Linux (usando la terminal):
- No Windows:
Utilizar ssh-keygen en el prompt de comando
Utilice una versión de openssl para windows, ejecute como administrador y ejecute el siguiente comando:
Cuidado:
Este archivo de clave pública
jwtRS256.key.pubes el único archivo que debe enviar a nuestro equipo de soporte. Mantenga siempre a salvo su clave privada y contraseña, si ha registrado una.
Algoritmo de firma#
El algoritmo soportado por la aplicación es RS256 junto con el estándar [JWT (RFC 7519)] (https://jwt.io/introduction/).
Con este estándar, una firma se compone de tres partes: encabezado, datos (payload) y verificación de la firma. A cada una de estas partes, se aplica una codificación Base64.
Primera parte (encabezado)#
El encabezado debe contener el siguiente contenido fijo:
Encbezado Base64:
Segunda parte (payload)#
La parte de datos (payload) varía según la operación a firmar. Ejemplo:
Payload Base64:
Composición del payload#
Dependiendo del servicio llamado, los campos de carga útil serán diferentes. Los campos requeridos para cada servicio se describen a continuación.
Servicios de creación y listado de tiendas#
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de la tienda en el Portal Carat. | = 15 AN | SI |
merchant_key | clave de autentificación de la tienda en el Portal Carat. | < 80 AN | SIM |
timestamp | Representación en milisegundos del tiempo de generación de la firma. Destacando que el campo de marca de tiempo tiene un límite de validez de 10 minutos. | < 13 N | SI |
Servicios de edición y consulta de la tienda#
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes. | = 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. | < 80 AN | SI |
timestamp | Representación en milisegundos del tiempo de generación de la firma. Destacando que el campo de marca de tiempo tiene un límite de validez de 10 minutos. | < 13 N | SI |
register_merchant_id | Código de la tienda creada o por crear en PayPal. Los códigos de producción y certificación serán diferentes. | = 15 AN | SI |
Servicio de cancelación de transacciones#
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes. | = 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. | < 80 AN | SI |
order_id | Código de pedido definido por el comerciante. | < 40 AN | SI |
merchant_usn | Número secuencial único para cada pedido, creado por la tienda. | < 12 N | Condicional |
timestamp | Representación en milisegundos del tiempo de generación de la firma. Destacando que el campo de marca de tiempo tiene un límite de validez de 10 minutos. | < 13 N | SI |
Ejemplo:
Otros servicios#
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
nit | Identificador de transacción en el Portal Carat. | = 64 AN | SI |
merchant_id | Código de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes. | = 15 AN | SI |
merchant_key | Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. | < 80 AN | SI |
timestamp | Representación en milisegundos del tiempo de generación de la firma. Destacando que el campo de marca de tiempo tiene un límite de validez de 10 minutos. | < 13 N | SI |
Ejemplo:
Tercera parte (verificación)#
La tercera y última parte es el resultado del cifrado RSA de las dos partes anteriores codificadas por separado en Base64 y concatenadas por un punto (".").
Dos partes anteriores codificadas por separado en Base64 y concatenadas por un punto ("."), Donde el primer segmento del texto - antes del punto - corresponde al encabezado y el segundo corresponde a payload:
Finalmente, se debe realizar un cifrado RSA, utilizando la clave privada de la tienda, en este contenido. Ejemplo:
Firma final#
La firma final es la concatenación de las 3 partes separadas por("."):
Estas tres partes de la firma, representadas por el ejemplo anterior, deben enviarse en el encabezado Authorization con valorBearer <firma>. Con esto, Portal Carat podrá validar la suscripción utilizando la clave pública de la tienda.
Uso del sitio JWT para realizar pruebas#
Puede utilizar el sitio web [JWT] (https://jwt.io/) para crear una suscripción válida para realizar pruebas. Para ello es necesario seleccionar el algoritmo RS256 y pasar la respectiva carga útil y una clave pública y privada.
Si la clave pública no es válida, se mostrará el mensaje "Firma no válida".
