Este documento especifica y guía el proceso de integración del Portal de Pagos UPago con 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 comunicacional para efectuar operaciones de recaudación de pagos con todos los medios que UPago dispone a su cliente según convenio.
UPago ha dispuesto su Portal de Pagos el cual permite a su cliente realizar recaudación y cobranza preventiva de las cuentas facturadas a sus usuarios en un proceso en línea y automatizado.
A continuación, se detallan características y condiciones de este servicio que el cliente debe considerar para su habilitación.
Toda comunicación entre las plataforma debe ser realizada a través del protocolo HTTPS con TLS 1.2. La comunicación no asegura por protocolo HTTP será rechazada.
El intercambio de mensaje en las comunicaciones estará basada en el formato JSON (JavaScript Object Notation), el cual es un formato de texto sencillo para el intercambio de datos. UPago describe en este documento la estructura utilizada y los datos intercambiados para cada paso en la comunicación.
Todo dato requerido para la comunicación desde la plataforma cliente hacia la plataforma UPago deberá ser respetado para lograr una correcta comunicación.
El cliente es responsable de mantener su servicio en alta disponibilidad para responder a la comunicación desde la plataforma UPago hacia la plataforma del cliente.
Upago dispone 2 ambiente para la habilitación del servicio: uno de certificación (sandbox) y otro de producción. Para cada ambiente UPago entrega al cliente datos de acceso y autenticación específicos.
El ambiente de certificación entrega al cliente la posibilidad de ejecutar transacciones con datos de pago de prueba. UPago dispone sólo de algunos medios de pagos en este ambiente.
El ambiente de producción entrega al cliente la ejecución de transacciones con pagos reales mediante todos los medios de pagos que UPago habilita al cliente según convenio.
El cliente debe disponer de las urls que se especifican más adelante para todas las comunicaciones requeridas.
La comunicación para cumplir el ciclo completo de recaudación por parte de UPago y la plataforma del cliente consta de 4 pasos que son resumidos de la siguiente manera:
1. Carga Masiva de Deudas:
Esta es la primera comunicación que realiza la plataforma del cliente para informar de forma masiva todas sus deudas para ser recaudadas por UPago. Se informa una lista de Clientes (usuarios que pagan), junto a sus Consumos (tipos de cuentas a recaudar como por ej. un crédito de consumo, honorarios mensuales, cuenta de servicio básico, etc..) y los Ítems de deuda asociados a cada Consumo (cuotas de pago/boletas/facturas/nro de folios/etc que generan un monto de deuda en un periodo específico). En general, si el cliente posee una lógica de cálculo y actualización de montos asociados a la deuda (como por ej. monto capital, intereses penales, etc..) que sea de forma diaria, entonces esta comunicación puede efectuarse en la madrugada de todos los días para asegurar que la información de recaudación en UPago esté día a día actualizada. La periodicidad de la comunicación dependerá de la lógica de negocio del cliente. Cada comunicación masiva nueva reemplaza toda información de deudas pendientes de pago que hayan sido comunicadas previamente.
2. Notificación de Pagos Recibidos:
UPago en cada pago recibido sobre transacciones de pago exitosas efectuadas por los usuarios, notificará a la plataforma cliente con todos los detalles de la transacción de pago (ID,monto, fecha pago, fecha contable, deudas asociadas pagadas, entre varios otros atributos). Cada pago recibido y notificado por esta vía será luego finalmente confirmado en la notificación de rendición diaria de recaudación respectiva que UPago enviará al término de cada día hábil bancario a la plataforma cliente. Es importante que el cliente se resguarde que algunos pagos recibidos notificados por la presenta vía de comunicación podrían ser reversados por diferentes causales y por tanto no deben ser considerados como pagos totalmente confirmados hasta la rendición.
3. Notificación de Rendición Diaria de Recaudación:
UPago en cada día hábil bancario o también llamada fecha contable (esto es en general de Lunes a Viernes excepto feriados), notificará a la plataforma de cliente con su rendición diaria de recaudación, la cual contendrá el resumen y los detalles de todos los pagos recibidos confirmados y reversados que hayan sido cursados en la fecha contable respectiva.
4. Notificación de Pago Recibido por cliente de forma externa:
Para lograr una buena experiencia de recaudación hacia los usuarios pagadores y el cliente, la plataforma cliente podrá comunicar de un pago recibido de forma externa (fuera de UPago) con la intención de que UPago ya no ejerza acciones de recaudación futura sobre la(s) deuda(s) asociadas a dicho pago recibido de forma externa.
5. Carga de un Cliente con sus Deudas:
Para lograr una buena experiencia de recaudación hacia los usuarios pagadores y el cliente, la plataforma del cliente podrá informar la información actualizada y particular de un Cliente con sus deudas en una modalidad en línea cuando sea requerido. Esta comunicación es ideal por ejemplo para casos en que la plataforma del cliente reciba modificaciones sobre la deuda particular de un Cliente y esta tenga que ser informada de inmediato a UPago sin la necesidad de esperar el proceso batch nocturno para así asegurar la correcta sincronización de deudas entre sistemas y evitar notificaciones o cobros de montos de deudas que hayan cambiado. Cada comunicación nueva reemplaza la información de deudas pendientes de pago asociada al Cliente que hayan sido comunicadas previamente.
UPago dispone un endpoint en su API REST para que la plataforma cliente pueda comunicar de forma masiva una lista de sus Clientes con todas sus cuentas y deudas pendientes de pago que serán recaudadas en el futuro. Este endpoint tiene la intención de ser consumido en modalidad proceso batch ejecutado en un horario nocturno y especialmente en casos de un volumen alto de datos, pero de igual forma puede ser consumido en línea cuando se requiera. Para cada registro de Cliente UPago realizará la siguiente acción: Si al momento de la comunicación el Cliente no existe, UPago lo creará junto a la información de sus deudas. En el caso que el Cliente exista, reemplazará toda la información del Cliente y la de sus
deudas. Esta comunicación conlleva lo siguiente:
Ambiente de certificación:
https://certif.upago.cl/web/rest/v1.1/business/customers/bulk/inform-debts
Ambiente de producción:
https://www.upago.cl/rest/v1.1/business/customers/bulk/inform-debts
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
}
UPago envía al cliente un ejemplo de esta estructura de JSON en correo oficial de inicio de habilitación.
En el caso que un usuario concrete una transacción de pago exitoso por el proceso de pago de una o más deudas, UPago notificará de esto a la plataforma del cliente de la siguiente forma:
a. La notificación de pago 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 todas las notificaciones de pago recibido que UPago enviará a la plataforma cliente.
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. Al igual como sucede en 3.1 b; UPago enviará el token de seguridad compartido en la cabecera de la solicitud POST en la notificación:
Nombre | Authorization |
---|---|
Valor | TOKEN_DE_SEGURIDAD_DE_CLIENTE |
Nota: En esta notificación a plataforma cliente no se incluye el prefijo “Beare“ que si debe ser incluido en 3.1 b.
{
Añadir estructura JSON
}
UPago envía al cliente un ejemplo de esta estructura de JSON en correo oficial de inicio de habilitación.
En cada día hábil bancario (fecha contable) UPago notificará a plataforma de cliente con su rendición diaria de recaudación, la cual contendrá el resumen y los detalles de todos los pagos recibidos confirmados y reversados que hayan sido cursados en la fecha contable respectiva. UPago notificará de esto a la plataforma del cliente de la siguiente forma:
Nombre | Authorization |
---|---|
Valor | TOKEN_DE_SEGURIDAD_DE_CLIENTE |
Nota: En esta notificación a plataforma cliente no se incluye el prefijo “Bearer “ que si debe ser incluido en 3.1 b.
{
Añadir estructura JSON
}
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 rendición diaria de recaudación, 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.
f. La notificación de rendición diaria de recaudación podría eventualmente informarse múltiples veces si no se logró una primera comunicación con la plataforma del cliente.
g. La siguiente tabla describe los estados posibles que pueden obtener los pagos recibidos confirmados y reversados en una rendición:
UPago dispone un endpoint en su API REST para que la plataforma cliente pueda comunicar la acción de un pago recibido de forma externa (fuera de UPago), la cual es una comunicación importante para que UPago ya no ejerza ninguna acción de recaudación futura sobre la(s) deuda(s) asociadas al pago recibido de forma externa. Esta comunicación conlleva lo siguiente:
Ambiente de certificación:
https://certif.upago.cl/web/rest/v1.1/business/customers/{customer_remoteId}/debts/notify_external_payment
Ambiente de producción:
https://www.upago.cl/rest/v1.1/business/customers/{customer_remoteId}/debts/notify_external_payment
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
}
UPago dispone un endpoint en su API REST para que la plataforma cliente pueda comunicar la información de un Cliente con todas sus cuentas y deudas pendientes de pago que serán recaudadas en el futuro. Este endpoint tiene la intención de ser consumido en modalidad en línea cuando sea requerido. Si al momento de la comunicación el Cliente no existe, UPago lo creará junto a la información de sus deudas. En el caso que el Cliente exista, reemplazará toda la información del Cliente y la de sus deudas. Esta comunicación conlleva lo siguiente:
Ambiente de certificación:
https://certif.upago.cl/web/rest/v1.1/business/customers/inform-customer-with-debts
Ambiente de producción:
https://www.upago.cl/rest/v1.1/business/customers/inform-customer-with-debts
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.
UPago envía al cliente un ejemplo de esta estructura de JSON en correo oficial de inicio de habilitación.
{
Añadir estructura JSON
}