Este documento especifica y guía el proceso de integración del botón de recaudación UPago en la plataforma de su cliente. Detalla las consideraciones y restricciones de este servicio, así como también todos los detalles y la lógica operativa del proceso transaccional para efectuar operaciones de recaudación de pagos en línea con todos los medios que UPago dispone a su cliente según convenio.
UPago ha dispuesto su Botón de Recaudación el cual permite a su cliente que sus usuarios realicen pagos de cuentas a través de su sitio web mediante las formas de pago que UPago dispone según contrato.
A continuación se detallan características y condiciones de este servicio que el cliente debe considerar para su habilitación.
En total, son ejecutados 4 pasos para lograr una transacción de recaudación con UPago. Los pasos son descritos a continuación.
Para que el cliente de curso a una nueva transacción a ser recaudada por UPago, lo primero es solicitar una operación de transacción. Esta solicitud conlleva lo siguiente:
Ambiente de certificación:
https://certif.upago.cl/payment/br/v1/request_transaction
Ambiente de producción:
https://pay.upago.cl/payment/br/v1/request_transaction
Nombre | Authorization |
---|---|
Valor | Bearer TOKEN_DE_SEGURIDAD_DE_CLIENTE |
TOKEN_DE_SEGURIDAD_DE_CLIENTE corresponde al token de seguridad compartido entregado por UPago al cliente para este servicio. Permitirá autenticar la comunicación entre ambas plataformas para aumentar la seguridad.
{
Añadir estructura JSON
}
Con la respuesta obtenida a la Solicitud de Transacción, la plataforma de cliente debe redireccionar a su usuario pagador a UPago para que éste realice el pago correspondiente. Esta operación conlleva lo siguiente:
a. Con la respuesta de la Solicitud de Transacción, la plataforma cliente debe redireccionar a su usuario mediante una solicitud POST a la URL que se encuentra almacenada en el atributo “url” en la respuesta. Además, debe incluir un parámetro con nombre de “token” y su valor debe ser el mismo que se encuentra almacenado en el atributo “token” en la respuesta. La redirección puede ser realizada mediante un formulario HTML < form > auto-enviado con los datos de respuesta ya descritos.
b. En una correcta redirección a UPago, el usuario siguientemente interactuará con el sitio de UPago para realizar el pago correspondiente.
UPago envía al cliente un ejemplo de un archivo HTML plano en correo oficial de inicio de habilitación, que incluye un formulario oculto que sirve para redireccionar al usuario a Upago según la respuesta de la Solicitud de Transacción. Los parámetros de redirección deben ser correctamente insertados según el lenguaje y/o framework de programación que utilice el cliente.
En el caso que el usuario concrete la acción de pago, UPago notificará de esto a la plataforma del cliente de la siguiente forma:
a. La notificación de pago con su resultado será enviada a la URL de plataforma de cliente previamente configurada en proceso de habilitación del servicio. Esta URL tendrá el propósito de recibir las notificaciones de pago enviadas por la plataforma UPago. UPago siempre enviará resultados de pagos exitosos; podrá enviar resultados de pagos rechazados por pasarelas de forma opcional (si cliente lo solicita) y con condición que este estado sea soportado por la pasarela de pago empleada en el pago respectivo; y podrá enviar resultados de pagos reversados de forma opcional (si cliente lo solicita).
b. La notificación de pago sólo se realizará mediante solicitud POST a una URL de conexión segura vía protocolo HTTPS.
c. UPago enviará el token de seguridad compartido en la cabecera de la solicitud POST en la notificación:
Nombre | Authorization |
---|---|
Valor | Bearer TOKEN_DE_SEGURIDAD_DE_CLIENTE |
Prefijo Bearer no es incluido en el valor de la cabecera Authorization
UPago envía al cliente un ejemplo de esta estructura de JSON en correo oficial de inicio de habilitación.
e. Al procesar la notificación de pago la plataforma del cliente deberá responder con un código de respuesta HTTP 200 (“200 OK”) para indicar que la notificación fue recibida correctamente. Cualquier otro código de respuesta será entendido como un error en el procesamiento de la notificación e implicará que esta vuelva a ser re-enviada posteriormente (ver f.).
f. La notificación de pago podría eventualmente informarse múltiples veces si no se logró una primera comunicación (cuando se cursó el pago) con la plataforma del cliente o si se dan ciertos resultados por el lado de UPago en el momento del pago del tipo “en espera de confirmación….” que son descritos en 3.4 d. La configuración por defecto de reintentos en UPago enviará el mensaje 5 veces cada 30 segundos hasta lograr una recepción exitosa. La configuración de reintentos puede ser a medida del cliente.
Una vez que el usuario pagador finalice el proceso de pago, UPago lo redireccionará a la plataforma del cliente independiente del estado final del proceso de pago. Esta operación conlleva lo siguiente:
a. UPago redireccionará al usuario a la URL de plataforma de cliente previamente configurada en proceso de habilitación del servicio o que fue informada como url de retorno en solicitud de transacción original. Esta URL tendrá el propósito de recibir al usuario una vez finalizado el proceso de pago. Debe considerar que el proceso de pago puede terminar en diferentes estados expuestos más adelante y que un pago exitoso sólo debe ser considerado oficialmente en la Confirmación de Pago a la plataforma del cliente (ver 3.3).
b. El cambio de contexto sólo se realizará mediante solicitud GET a una URL de conexión segura vía protocolo HTTPS.
d. La plataforma del cliente debe utilizar el parámetro enviado “token” para obtener los datos de la transacción original asociada en su plataforma. El parámetro “status” indicará el resultado de pago de la transacción que es informado por UPago. Importante: La confirmación oficial del pago exitoso (status PAID) sólo debe ser procesada en la comunicación oficial de Confirmación de Pago a la plataforma del cliente (ver 3.3). Si obtiene estado PAID en este parámetro en la vuelta del usuario pero sin haber obtenido antes Confirmación de Pago oficial entonces se recomienda mostrar un mensaje al usuario de “Esperando confirmación final del pago, actualice minutos más tarde” o similar. La plataforma del cliente siempre debe ser capaz de interpretar bien los posibles resultados de pago para mostrar información correcta al usuario en su vuelta. En la siguiente tabla se describen los estados posibles de resultado de pago: