Anexo 1: Integración Custom (Bienes digitales y/o físicos)

 

El comercio tiene la posibilidad de integrar los widgets de Amazon Pay en su propio sitio web (incluyendo la integración del “Login con Amazon” y los diferentes widgets de direcciones de envío y tarjetas). Para ello deberá asumir el desarrollo de la parte de presentación de Amazon Pay, incluyendo además la gestión de errores y de los gastos de envío, en caso de utilizar el widget de direcciones de envío proporcionado por Amazon Pay.

Puede encontrar la información necesaria para su integración en el siguiente enlace:

https://developer.amazon.com/es/docs/eu/amazon-pay-onetime/amazon-pay-and-login-with-amazon-introduction.html

 

Posteriormente, el comercio utilizará la conexión por redirección del TPV Virtual para procesar la orden, efectuando la autenticación del titular contra su entidad emisora.

Redsys ofrece la posibilidad de proporcionar al comercio la dirección de envío seleccionada por el usuario en el widget de direcciones de envío a través de una petición REST:

Para ello será necesario realizar una petición Rest a Redsys para obtener la dirección de envío seleccionada por el usuario. El comercio utilizará este servicio para obtener la dirección de envío seleccionada por parte del cliente y realizar el cálculo de los gastos de envío antes de solicitar el pago.

Para realizar esta llamada serán necesarios los siguientes parámetros:

 

Nombre del parámetro

Long. / Tipo

Descripción

DS_MERCHANT_ORDER

12 / A-N

Obligatorio. Número de pedido. Necesario para diversificar la clave de firma, pero no es necesario hacer match con la posterior autorización del pago.

DS_MERCHANT_MERCHANTCODE

9 / N

Obligatorio. Código FUC asignado al comercio.

DS_MERCHANT_TERMINAL

3 / N

Obligatorio. Número de Terminal que le asignará su banco.

DS_MERCHANT_AMAZONORDERREFERENCE

20 / A-N

Obligatorio. Identificador de la orden de Amazon Pay sobre la que hacer la consulta

DS_MERCHANT_AMAZONACCESSTOKEN

800 / A-N

Obligatorio. Valor obtenido en el Login con Amazon. Necesario para obtener los datos completos de envío.

 

Los diferentes endpoints para la llamada al servicio son los siguientes:

  • Test: https://sis-t.redsys.es:25443/sis/services/rest/getAddressByAmazonOrderId
  • Producción: https://sis.redsys.es/sis/services/rest/getAddressByAmazonOrderId

 

Como respuesta, se devolverán los siguientes parámetros asociados a la dirección de envío:

  • destinationType →Physical
  • addressLine1
  • addressLine2
  • addressLine3
  • city
  • countryCode
  • county
  • district
  • names
  • phone
  • postalCode
  • stateOrRegion


En caso de error, se enviará un único parámetro “error” indicando que no hay dirección disponible.

 

 

Mensajería Rest

 

Las peticiones deberán incluir los siguientes parámetros:

  • Ds_SignatureVersion: Constante que indica la versión de firma que se está utilizando.
  • Ds_MerchantParameters: Cadena en formato JSON con todos los parámetros de la petición codificada en Base 64 y sin retornos de carro
  • Ds_Signature: Firma de los datos enviados. Es el resultado del HMAC SHA256 de la cadena JSON codificada en Base 64 enviada en el parámetro anterior.

 

Para facilitar la integración del comercio, a continuación, se explica de forma detallada los pasos a seguir para montar el formulario de petición de pago:

 

 

1. Identificar la versión de algoritmo de firma a utilizar

 

En la petición se debe identificar la versión concreta de algoritmo que se está utilizando para la firma. Actualmente se utiliza el valor HMAC_SHA256_V1 para identificar la versión de todas las peticiones, por lo que este será el valor del parámetro Ds_SignatureVersion.

 

2. Montar la cadena de datos de la petición

 

Se debe montar una cadena con todos los datos de la petición en formato JSON. El nombre de cada parámetro debe indicarse en mayúsculas o con estructura “CamelCase” (Por ejemplo: DS_MERCHANT_ORDER o Ds_Merchant_Order).

A continuación, se muestran un ejemplo del objeto JSON de una petición de dirección de envío:

{"DS_MERCHANT_MERCHANTCODE":"999008881","DS_MERCHANT_TERMINAL":"4","DS_MERCHANT_ORDER":1559562306,"DS_MERCHANT_AMAZONORDERREFERENCE":"S02-1829909-6380300","DS_MERCHANT_AMAZONACCESSTOKEN":"Atza|IwEBIJ56QjIIuEC5FU-dI7tRVLrEKasouUxyt7yb6BDRZA1g2KZU0yNLDgXsDQcWqiRSVDI3Onx50_XD6X17EVRl_gludUiAGihfso94v6kv75qhJvdq0uytCfVnhe4u_yzPzhmSAYyIeffjzU6fEYb2PdGNlbL_gdkrU76Bg7DmiDeRco83cmHaD-OS4iDBRn02aa_M3Ajxcp7879svXsY8LHld_Qr2YYeXb3Eq5zaXvE6HHnKyASJuhnKdbMWmi-buMxyeAg37izrg2lt1YbXFNGXx59D9LjJYrzzY1SwJ3cgpsUQirliKcVSbUP768g5YQU5DGzkFGJT9veJVMJTW4zd1ihsbjcmGr2hSrjdK_dmu9lhlLOdEy0wCx9ss9QZ1m6sIIVNTLi-PArHXkQdLR5zImRJN_99rCRatHPMv2Ybgy7galHxfuwm589fk4jBovTnuYju-5uzQpToBa-MicdMKJM5KNjnDBWOlRVDolG2lMkUklvpI-_kadK9xLBrjXhvmuib1nEvvt6G2MkPPoTA7xPBwzzj0X5H-OKvfqffDSqzAJagGcrqQV1N6P8ZaTX5P89l-HJuLBv48wEDoX9ZSVJQBgkvpUrD1can0WjNbhA"}

 

Una vez montada la cadena JSON con todos los campos, es necesario codificarla en BASE64 sin retornos de carro para asegurarnos de que se mantiene constante y no es alterada en el proceso de envío. A continuación, se muestra el objeto JSON codificado en BASE64:


eyJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjQiLCJEU19NRVJDSEFOVF9PUkRFUiI6MTU1OTU2MjMwNiwiRFNfTUVSQ0hBTlRfQU1BWk9OT1JERVJSRUZFUkVOQ0UiOiJTMDItMTgyOTkwOS02MzgwMzAwIiwiRFNfTUVSQ0hBTlRfQU1BWk9OQUNDRVNTVE9LRU4iOiJBdHphfEl3RUJJSjU2UWpJSXVFQzVGVS1kSTd0UlZMckVLYXNvdVV4eXQ3eWI2QkRSWkExZzJLWlUweU5MRGdYc0RRY1dxaVJTVkRJM09ueDUwX1hENlgxN0VWUmxfZ2x1ZFVpQUdpaGZzbzk0djZrdjc1cWhKdmRxMHV5dENmVm5oZTR1X3l6UHpobVNBWXlJZWZmanpVNmZFWWIyUGRHTmxiTF9nZGtyVTc2Qmc3RG1pRGVSY284M2NtSGFELU9TNGlEQlJuMDJhYV9NM0FqeGNwNzg3OXN2WHNZOExIbGRfUXIyWVllWGIzRXE1emFYdkU2SEhuS3lBU0p1aG5LZGJNV21pLWJ1TXh5ZUFnMzdpenJnMmx0MVliWEZOR1h4NTlEOUxqSllyenpZMVN3SjNjZ3BzVVFpcmxpS2NWU2JVUDc2OGc1WVFVNURHemtGR0pUOXZlSlZNSlRXNHpkMWloc2JqY21HcjJoU3JqZEtfZG11OWxobExPZEV5MHdDeDlzczlRWjFtNnNJSVZOVExpLVBBckhYa1FkTFI1ekltUkpOXzk5ckNSYXRIUE12MlliZ3k3Z2FsSHhmdXdtNTg5Zms0akJvdlRudVlqdS01dXpRcFRvQmEtTWljZE1LSk01S05qbkRCV09sUlZEb2xHMmxNa1VrbHZwSS1fa2FkSzl4TEJyalhodm11aWIxbkV2dnQ2RzJNa1BQb1RBN3hQQnd6emowWDVILU9LdmZxZmZEU3F6QUphZ0djcnFRVjFONlA4WmFUWDVQODlsLUhKdUxCdjQ4d0VEb1g5WlNWSlFCZ2t2cFVyRDFjYW4wV2pOYmhBIn0=


La cadena resultante de la codificación en BASE64 será el valor del parámetro Ds_MerchantParameters.

 

3. Identificar clave de firma

 

Para calcular la firma es necesario utilizar una clave específica para cada terminal. Se puede obtener la clave accediendo al Módulo de Administración, opción Consulta datos de Comercio, en el apartado “Ver clave”, tal y como se muestra en la siguiente imagen:

 

 

NOTA IMPORTANTE: Esta clave debe ser almacenada en el servidor del comercio de la forma más segura posible para evitar un uso fraudulento de la misma. El comercio es responsable de la adecuada custodia y mantenimiento en secreto de dicha clave.

 

4. Firma de los datos de la petición

 

Una vez se tiene montada la cadena de datos a firmar y la clave específica del terminal se debe calcular la firma siguiendo los siguientes pasos:

1. Se genera una clave específica por operación. Para obtener la clave derivada a utilizar en una operación se debe realizar un cifrado 3DES entre la clave del comercio, la cual debe ser previamente decodificada en BASE 64, y el valor del número de pedido de la operación (Ds_Merchant_Order).

2. Se calcula el HMAC SHA256 del valor del parámetro Ds_MerchantParameters y la clave obtenida en el paso anterior.

3. El resultado obtenido se codifica en BASE 64, y el resultado de la codificación será el valor del parámetro Ds_Signature.

 

5. Recepción del resultado

 

Una vez gestionada la petición, se informará el resultado de la misma con la información del resultado incluida en un fichero JSON. En él se incluirán los siguientes campos:

  • Ds_SignatureVersion: Constante que indica la versión de firma que se está utilizando.
  • Ds_MerchantParameters: Cadena en formato JSON con todos los parámetros de la respuesta codificada en Base 64 y sin retornos de carro.
  • Ds_Signature: Firma de los datos enviados. Resultado del HMAC SHA256 de la cadena JSON codificada en Base 64 enviada en el parámetro anterior. El comercio es responsable de validar el HMAC enviado por el TPV Virtual para asegurarse de la validez de la respuesta. Esta validación es necesaria para garantizar que los datos no han sido manipulados y que el origen es realmente el TPV Virtual.