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):
# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
  • No Windows:

Utilizar ssh-keygen en el prompt de comando

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Utilice una versión de openssl para windows, ejecute como administrador y ejecute el siguiente comando:

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Cuidado:

Este archivo de clave pública jwtRS256.key.pub es 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:

{
"alg": "RS256",
"typ": "JWT"
}

Encbezado Base64:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Segunda parte (payload)#

La parte de datos (payload) varía según la operación a firmar. Ejemplo:

{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"order_id": "182367r12831t29b",
"merchant_usn": "92837429837",
"timestamp": "1605034925174"
}

Payload Base64:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

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ámetroDescripciónFormatoObligatorio
merchant_idCódigo de la tienda en el Portal Carat.= 15 ANSI
merchant_keyclave de autentificación de la tienda en el Portal Carat.< 80 ANSIM
timestampRepresentació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 NSI
{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"timestamp": "1605034925174"
}

Servicios de edición y consulta de la tienda#

ParámetroDescripciónFormatoObligatorio
merchant_idCódigo de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes.= 15 ANSI
merchant_keyClave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. < 80 ANSI
timestampRepresentació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 NSI
register_merchant_idCódigo de la tienda creada o por crear en PayPal. Los códigos de producción y certificación serán diferentes.= 15 ANSI
{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"registered_merchant_id": "YYYYYYY",
"timestamp": "1605034925174"
}

Servicios de creación de transacciones#

ParámetroDescripciónFormatoObligatorio
merchant_idCódigo de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes.= 15 ANSI
merchant_keyClave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. < 80 ANSI
order_idCódigo de pedido definido por el comerciante. < 40 ANCondicional
merchant_usnNúmero secuencial único para cada pedido, creado por la tienda. < 12 NCondicional
timestampRepresentació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 NSI

Importante:

Los campos order_id y mercantil_usn no 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:

{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"order_id": "182367r12831t29b",
"merchant_usn": "92837429837",
"timestamp": "1605034925174"
}

Otros servicios#

ParámetroDescripciónFormatoObligatorio
nitIdentificador de transacción en el Portal Carat.= 64 ANSI
merchant_idCódigo de tienda en Portal Carat. Los códigos de producción y certificación serán diferentes.= 15 ANSI
merchant_keyClave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. < 80 ANSI
timestampRepresentació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 NSI

Ejemplo:

{
"nit": "asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"timestamp": "1605034925174"
}

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:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Finalmente, se debe realizar un cifrado RSA, utilizando la clave privada de la tienda, en este contenido. Ejemplo:

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Firma final#

La firma final es la concatenación de las 3 partes separadas por("."):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0.LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

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. &quot;Jwt&quot; -no-filter

Si la clave pública no es válida, se mostrará el mensaje "Firma no válida". &quot;Jwt&quot; -no-filter