Propuesta:
Manual de integración de los comercios con la plataforma Enzona
Versión 1.0.0
Unidad Empresarial de Base Economía Digital .
Empresa de Tecnologías de la Información para la Defensa(XETID)
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
Índice
1. Introducción...................................................................................................................................................3
2. Pasos para obtener el token............................................................................................................................3
3. Gestión de Token...........................................................................................................................................6
3.1. Autorización de solicitud...........................................................................................................................6
3.2. Actualización de Token..............................................................................................................................7
3.3. Revocar Token...........................................................................................................................................8
4. Conclusiones...............................................................................................................................................10
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
1. Introducción.
La plataforma publica una Interface de Programación de Aplicaciones (API) la cual es el punto de entrada para
iniciar el proceso de pago. El API recibe la petición de pago, luego de validar la aplicación emisora mediante la
comprobación de un token de seguridad basado en OAUTH2 previamente asignado, le concede los privilegios
de consumir los recursos expuestos en el API.
1.1. Comercios.
Son aplicaciones clientes del servicio. Dichas aplicaciones deben estar previamente registradas en la
plataforma. Posteriormente se pueden suscribir al API y obtener las credenciales de seguridad que le
posibilitan el consumo de la misma.
2. Pasos para obtener el token
2.1. Lo primero que se debe hacer es autenticarse en el api manager para poder obtener el token de acceso,
consumer key, consumer secret y el alcance.
2.2. Para poder autenticarse en el API Manager debe haber registrado un comercio en la url
[Link] en el caso de producción o en [Link] en caso de
Sandbox y esperar a que enzona le mande las credenciales. El entorno de Sandbox le proporciona una
aplicación creada una vez que se ha registrado para obtener una cuenta. Es importante mantener en
secreto estos valores. Asegúrese de almacenar sus credenciales de cliente de forma segura.
2.3. Una vez completado el paso anterior puede acceder con su usuario generado por Enzona y su
contraseña. A entrar al sistema podrá ver las APIs PaymentAPI y QRAPI con su aplicación que se creó
en el paso anterior ya subscrita por defecto a las mismas.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
2.4. Lo siguiente es ver donde se encuentra el token de acceso, consumer key y el consumer secrect. Para
esto seleccionamos en el menú de la izquierda la opción que dice comercios, en la cual se mostrará los
comercios registrados.
2.5. Luego Seleccionamos el comercio y seleccionamos el Tab Production Keys en el caso de Producción o
Sandbox Keys en el caso de prueba.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
2.6. Ahí se verá el Consumer Key, Consumer Secret y al final el Token de acceso; en el cual se podrá
generar el token de acceso seleccionando el alcance y luego dando clic en el botón Regenerar.
2.7. A partir de aquí ya obtendrá el token para poder probar las APIs de PaymentAPI y QRAPI.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
3. Gestión de Token.
OAuth es un framework de autorización que permite a una aplicación de terceros obtener acceso a recursos
protegidos (payments, complete, etc.) en la API de enzona. Esta sección cubre la autenticación de la aplicación
que está diseñada para aplicaciones de servidor a servidor que utilizan la API de enzona.
Enzona utiliza el protocolo OAuth2 para facilitar la autorización. La seguridad del API está basada en
OAUHT2, donde para consumir los recursos se debe enviar en la cabecera de la petición un token. Dicho token
es una cadena de texto del tipo “Authorization Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a”, generado y
validado por el API Enzona. Los clientes del servicio que implementen los comercios deben realizar los
siguientes procesos:
3.1. Autorización de solicitud
El flujo de credenciales del cliente es la concesión OAuth 2 más simple, con un intercambio de servidor a
servidor de las credenciales client_id, client_secret para obtener un token de acceso a la aplicación. Para
ejecutar este flujo, su aplicación enviará solicitudes POST con el encabezado de “Authorization” que contiene la
palabra “Basic” seguida de un espacio y una cadena codificada en base64 client_id:client_secret.
Authorization: Basic Base64(client_id:client_secret)
Solicitud HTTP
POST [Link]
La solicitud se envía al endpoint del token con grant_type=client_credentials en el cuerpo de la solicitud.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
El siguiente código PHP muestra un ejemplo de cómo obtener token con el grant_type=client_credentials:
El siguiente código PHP muestra un ejemplo de cómo obtener token con el grant_type=password, que no es más
que el usuario y la contraseña que se obtiene al registrar el comercio con Enzona:
Figura 1 Obtener Token.
3.2. Actualización de Token.
Los token obtenidos pueden ser renovados a elección de cada comercio. El siguiente código PHP muestra
cómo sería el proceso:
Figura 1 Actualizar Token.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
3.3. Revocar Token.
Una vez obtenido el token el mismo puede ser revocado por motivos particulares, el siguiente código PHP
muestra cómo realizar el proceso:
Figura 1 Revocar Token.
3.4. Parámetros de respuesta
Parámetro Descripción
Un nuevo token de acceso que se utiliza para autenticarse en los recursos que pertenecen a la
access_token propia aplicación.
expires_in La vida útil del token de acceso, en segundos. El valor predeterminado es 3600.
token_type Siempre Bearer.
Ejemplo de respuesta de token de acceso
{
"access_token": "19af2f73-4a6c-300b-8ca5-ccbee9b878f3",
"scope": "am_application_scope enzona_business_payment enzona_business_qr",
"token_type": "Bearer",
"expires_in": 35999456813
}
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
4. Conclusiones.
El presente documento describe los principales elementos que integran la solución utilizando la red de datos
como medio de transporte y una arquitectura orientada a servicios como solución arquitectónica. La seguridad
para el consumo del API está basada en OAUTH2 mediante la utilización de un token previamente asignado.
Calle 296 A, e/ 217 y 203,
municipio Boyeros, La Habana
(+53) 7837 3600 / (+53) 7837
3611 xetid@[Link]
[Link]
