Deberás implementar y exponer en tu backend los endpoints de “Autorización” y “Ajustes” para que podamos comunicarnos.

Durante el flujo online

Cada vez que un usuario utiliza su tarjeta en cualquier tienda o comercio electrónico.

Cuando la red (Mastercard, Visa, etc) solicita la conciliación de todos los pagos que presentan los comerciantes.

Si hubiera una diferencia en la conciliación, solicitaremos una corrección a tu API. Necesitaremos que tus endpoints respondan lo más rápido posible para garantizar una buena experiencia de usuario. Si la respuesta se demora, rechazaremos la transacción.

Como una solicitud HTTP puede dar timeout, tenemos que asegurarnos de que al reintentar se procese una única vez. Para eso, en cada solicitud, te enviaremos un header x-idempotency-key con ID único que deberás procesar con un caché en memoria (por ejemplo: redis).

Al comienzo de cada transacción, deberás verificar si la clave de idempotencia que te enviamos ya está en la caché en memoria y dependiendo de si está o no, deberás realizar lo siguiente:

No existe el header de idempotencia en la caché

Deberás almacenar en la caché en memoria la relación clave de idempotencia → pedido con un estado en tránsito con un TTL de 3 minutos.

Cuando apruebes o rechaces la transacción, deberás almacenar el resultado en la caché y actualizar el estado de la clave de idempotencia a terminado.

Existe el header de idempotencia en la caché

En caso de una solicitud duplicada, deberás verificar el estado de la transacción en la caché.

• Si está en estado terminado deberás responder con un código HTTP 200 con el body esperado para el endpoint y completarlo con el resultado de la caché.
• Si está en estado en tránsito deberás responder con un código HTTP 425 (Too Early: RFC 8470) con el body esperado para el endpoint. Nosotros volveremos a buscar la respuesta de esta solicitud unos milisegundos más tarde.

La comunicación entre nuestros backends debe ser estrictamente segura ya que los endpoints permitirán cargar y deducir fondos.

Para eso, requerimos que implementes tres medidas:

• Exponer endpoint HTTPS
• Whitelist de las IPs de Pomelo
• Firma hmac-sha256 del pedido y la respuesta

Toda comunicación con nosotros debe ser vía HTTPS, sin importar quien emite el certificado.

Te acercamos algunos de los proveedores más reconocidos

• https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-client-side-ssl-authentication.html
• https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
• https://cloud.google.com/load-balancing/docs/ssl-certificates/google-managed-certs

Siempre nos comunicaremos con tu backend desde IPs específicas. Recomendamos que solo aceptes request de las siguientes IPs y que rechaces cualquier otra:

IPS de Pomelo:

• Ambiente de Testing/Staging:

34.226.254.178            
44.198.3.59
34.223.185.46
100.20.205.117

• Ambiente de Producción:

34.206.159.176            
52.0.20.124
35.84.78.117
52.43.46.111

Para asegurarnos de que los únicos participantes en la comunicación sean nuestros backends (Pomelo y el Cliente), en el momento del onboarding le proporcionaremos una api-key y api-secret para firmar digitalmente el contenido de la comunicación.

El proceso será algo así:

1. En el onboarding haremos el intercambio de llaves api-key y api-secret.

2.

Al momento de una autorización de pago, nosotros firmamos con hmac-sha256 cada pedido de autorización con el api-secret.

4. Validas la firma hmac-sha256 con tu api-secret que se corresponde con el api-key del request.

5. Autorizas el pedido, debitas los fondos del usuario y firmas la respuesta con hmac-sha256 usando el api-secret.

6. Verificamos la firma hmac-sha256 y terminamos de procesar el pago.

Durante el proceso de onboarding, crearemos una api-key y api-secret específicas para ti.

También es posible usar gpg o algún plugin de correo electrónico (como por ejemplo https://flowcrypt.com/).

Veamos un ejemplo usando openssl en la línea de comandos.

1. Creamos las api-key y api-secret:

$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt

$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

2. Creas tu clave pública-privada:

$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem

3. Nos envías tu clave pública public.pem por email o Slack.

4. Encriptamos el archivo de credenciales con la clave pública que nos diste:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin

5. Enviamos el archivo api-credentials.txt.enc por email o Slack

6. Desencriptas el archivo api-credentials.txt.enc con tu clave privada private.pem:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

7. Guardas la api-secret en un lugar seguro y que sea accesible únicamente por la aplicación de “Autorizar pagos”, asociada al api-key.

Junto con el pedido de autorización o ajuste te enviaremos headers HTTP con la firma, el timestamp de la firma y la api-key para que verifiques que la firma sea correcta.

Los headers HTTP que enviamos son:

• x-api-key : este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.

• x-signature : este header contiene la firma digital (body + timestamp + endpoint) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.

• x-timestamp : este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.

• x-endpoint : el endpoint al que se realiza el pedido y que se uso para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.

Importante: además de chequear la firma que te enviamos, al generar la respuesta deberás firmar tu body junto con el timestamp y el endpoint de respuesta con tu api-secret luego de impactar la operación. Ten en cuenta que validaremos la firma y rechazaremos la transacción si la firma no coincide o expiró.

Puedes testear la implementación de tu backend con algunas operaciones típicas que enviaremos con una colección de Postman incluida en nuestro repositorio de ejemplos públicos. Podrás importar la colección a una instancia de Postman y así simular pedidos reales hacia tu backend, incluido el algoritmo de generación y chequeo de firma.

En el repositorio también encontrarás ejemplos de implementación del algoritmo de generación y validación de firma en varios lenguajes.

Este es un proceso opcional, pero recomendamos ejecutarlo a diario.

En el servidor SFTP que te disponibilizaremos encontrarás estos archivos:

• Archivo de transacciones
• Archivo de presentación

Contiene el detalle de cada transacción que te generamos el día anterior.

El nombre del archivo tiene el siguiente formato: transaction_yyyy-mm-dd_<nombre cliente>_<pais>.csv

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

En caso de que esté intentando ajustar un crédito a un usuario final que no tenga fondos suficientes en la cuenta, debe seguir intentando obtener los fondos de ese usuario.

Se convierte en una deuda entre el cliente y el usuario final.

Contiene el detalle de cada transacción que presentan los comerciantes el día anterior.

El nombre del archivo tiene el siguiente formato: presentment_yyyy-mm-dd_<nombre cliente>_<pais>.csv

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

Nuestro equipo de finanzas enviará diariamente un detalle con la deuda a pagar. Ese detalle tendrá todas las presentaciones que recibimos en el archivo de presentación.

Disponibilizaremos un servidor SFTP desde donde podrás descargar los archivos de Transacciones y Presentaciones.

Tenemos dos ambientes para los servidores SFTP: un ambiente productivo y otro de desarrollo.

Para conectarte a los servidores SFTP necesitaremos que nos envíes una llave pública para generarte un usuario.

Estos son los datos para conectarte a cada ambiente:

Host: sftp.pomelo.la
Puerto: 22
Usuario: <tu_usuario> # el que te generamos a partir de tus llaves públicas.

Host: sftp-dev.pomelo.la
{Puerto}: 22
Usuario: <tu_usuario> # el que te generamos a partir de tus llaves públicas.

Para generar la clave pública tendrás que usar el comando acorde a tu sistema operativo:

1. Crea una RSA Key Pair, cambiando la variable $Cliente por el nombre propio

ssh-keygen -t rsa -b 2048 -C $Cliente

El comando creará un par de claves RSA de 2048 bits de forma predeterminada. ​También podrás crear una clave más grande de 4096 bits ingresando -b 4096.

El comando produce esta salida:

Generating public/prive rsa key pair.
Ingresa un archivo en el que guardar la clave (/your_home/.ssh/id_rsa):

Presiona Enter para guardar el par de claves en .ssh /, o especifica otra ubicación.

2. Crea una frase de contraseña para tu clave SSH

Presiona Enter para dejarlo en blanco y usa solo la clave para establecer conexiones SSH. Ingresa una contraseña para una capa de seguridad adicional.

3. Obtener la clave pública generada leyendo el contenido del archivo público

cat ~/.ssh/id_rsa.pub

La clave generada comenzará con ssh-rsa.

Ahora puedes copiar y pegar tu clave SSH pública en tu consola Shell, o en cualquier servidor, para establecer una conexión segura.

Genera claves SSH usando PuTTY. Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

1. Genera claves SSH usando PuTTY

Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

2. Ejecuta el generador de claves PuTTY SSH

• Presiona la tecla de Windows.
• Escribe puttygen.
• Haz clic con el botón derecho en PuTTYgen.
• Haz clic en Ejecutar como administrador.
• Haz clic en Sí si el sistema te consulta “¿Desea permitir que esta aplicación realice cambios en su dispositivo?”

3. Usa PuTTY para crear un par de claves SSH

Si bien la herramienta PuTTY keygen ofrece varios otros algoritmos, te contaremos cómo generar claves RSA, una de las más usadas:

• En la ventana del generador de claves PuTTY, toca Generar.
• Mueve el cursor en el cuadro gris para llenar la barra verde.
• Genera un par de claves SSH en Putty.
• Guarda la clave pública haciendo clic en el botón Guardar clave pública. Luego tendrás que elegir una ubicación para guardar la clave y asignarle un nombre a la clave.
• Guarda la clave privada:
  • Haz clic en el menú Conversiones en la parte superior.
  • Haz clic en Exportar clave OpenSSH.
  • El sistema te preguntará si quieres guardar una clave sin una frase de contraseña. Haz clic en Sí.
  • Elige una ubicación para guardar la clave (generalmente la misma carpeta que la clave pública).
  • Asigna un nombre a la clave (por ejemplo, putty_key).