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 |
Servicios de creació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 | Condicional |
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 |
Importante:
Los campos
order_idymercantil_usnno son obligatorios para algunos servicios de creación de transacciones y, por lo tanto, deben seguir la misma regla, siendo informados con los mismos valores contenidos en el cuerpo de la solicitud.
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".
