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:
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:

{TOKEN_JWT_EXAMPLE}

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:

{TOKEN_JWT_EXAMPLE}

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

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

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

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

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:

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

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:

{
  "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:

{TOKEN_JWT_EXAMPLE}

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

SIGNATURE_EXAMPLE_DO_NOT_USE_IN_PRODUCTION

Firma final

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

{TOKEN_JWT_EXAMPLE}

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. "Jwt" -no-filter

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