V.1.2. rev2 del 09-10-2025
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.
La ejecución de transacciones de recaudación en UPAGO sigue una secuencia lógica que es representada en el siguiente diagrama de contexto.
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:
Hacer una solicitud POST a la siguiente URL de UPAGO:
Ambiente de Certificación:
https://certif.upago.cl/payment/br/v1.3/request_transaction
Ambiente de Producción:
https://pay.upago.cl/payment/br/v1.3/request_transaction
Anexar en la cabecera de la solicitud la siguiente directiva de seguridad:
| Nombre | Valor |
|---|---|
| Authorization | 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.
c. Anexar en el cuerpo de la solicitud la siguiente estructura de JSON:
Representa a una solicitud de inicio de transacción para recaudación de dinero en UPAGO.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| transactionIdOnClient | ABCDE4567 | Corresponde al ID de transacción de pago con origen en la plataforma del cliente. El valor a enviar es único por solicitud de transacción. Tipo Dato: Alfanumérico. Formato: Largo máximo de 64 caracteres. Requerido |
| amount | 235000.00 | Monto total que será recaudado por UPAGO. Puede estar limitado a monto máximo de recaudación fijado en contrato. Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Valor máximo de 99999999.99. Requerido |
| currency | CLP | Tipo de Moneda en la recaudación. Posibles valores: CLP (peso chileno), UF (unidad de fomento - Chile), USD (dólar estadounidense). Tipo Dato: Alfanumérico. Formato: Largo máximo de 3 caracteres. Requerido |
| customer | ver tabla 2 | Corresponde a un objeto del tipo Cliente que realiza pagos. Ver sus detalles en tabla 2. Requerido |
| consumptions | ver tabla 3 | Corresponde a un arreglo de objetos del tipo Consumo de Cliente. Ver sus detalles en tabla 3. Requerido |
| returnUserToURL | https://sitiowebdelcliente.com/payment-summary |
Corresponde a una URL de retorno donde será enviado el usuario pagador al finalizar el pago en cualquiera de sus estados. Si NO es incluido entonces UPAGO enviará al usuario pagador a una URL fija de la plataforma del cliente previamente configurada en los servidores de UPAGO. Tipo Dato: Alfanumérico. Formato: Largo máximo de 300 caracteres. Opcional |
Representa a un Cliente que realiza pagos y que está asociado a una transacción de recaudación de dinero.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| remoteId | 15615145-9 | Corresponde al ID del Cliente asociado al pago con origen en la plataforma del cliente. Debe ser único. Tipo Dato: Alfanumérico. Formato: Largo máximo de 64 caracteres. Requerido |
| name | Felipe Godoy | Corresponde al Nombre del Cliente. Tipo Dato: Alfanumérico. Formato: Largo máximo de 100 caracteres. Requerido |
| nationalId | 15615145-9 | Corresponde al Identificador Nacional del Cliente (ej. identificación nacional, pasaporte o identificador de plataforma). Sugerido informar para búsqueda de usuario. Tipo Dato: Alfanumérico. Formato: Largo máximo de 30 caracteres. Opcional |
| example1@gmail.com | Corresponde al Email del Cliente. Sugerido informar para envío de comprobante de pago. Tipo Dato: Alfanumérico. Formato: Largo máximo de 100 caracteres. Opcional | |
| mobile | 56956751239 | Corresponde al número telefónico Móvil del Cliente. Sugerido informar para envío de comprobante de pago. Tipo Dato: Alfanumérico. Formato: Largo máximo de 100 caracteres. Opcional |
Representa al conjunto de Consumos (tipos de cuentas) del Cliente que están asociados a una transacción de recaudación de dinero.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| remoteId | C-1 | Corresponde al ID del Consumo de Cliente con origen en la plataforma del cliente. Debe ser único. Tipo Dato: Alfanumérico. Formato: Largo máximo de 64 caracteres. Requerido |
| description | Compra de Insumos Oficina | Corresponde a la Descripción del Consumo de Cliente. Tipo Dato: Alfanumérico. Formato: Largo máximo de 255 caracteres. Requerido |
| items | ver tabla 4 | Corresponde a un arreglo de objetos del tipo Ítem de Consumo. Ver sus detalles en tabla 4. Requerido |
Representa al conjunto de Ítems (cobros/cuotas/deudas) de Consumo que están asociados a una transacción de recaudación de dinero.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| remoteId | DEBT-1 | Corresponde al ID del Ítem de Consumo (deuda) con origen en la plataforma del cliente. Debe ser único. Tipo Dato: Alfanumérico. Formato: Largo máximo de 64 caracteres. Requerido |
| description | Número de OC: 34567853 | Corresponde a la descripción de la deuda. Tipo Dato: Alfanumérico. Formato: Largo máximo de 255 caracteres. Requerido |
| amount | 45000.00 | Monto capital de la deuda. Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Valor máximo de 99999999.99. Requerido |
| penaltyAmount | 32000.00 | Monto de intereses de mora aplicado por atraso de pago de la deuda (deuda vencida). Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Valor máximo de 99999999.99. Requerido (0.00 si no existe penalidad aplicada) |
| penaltyDays | 30 | Los días de intereses de mora aplicados por atraso de pago de la deuda (deuda vencida). Tipo Dato: Numérico sin decimales. Formato: Número entero. Valor máximo de 9999. Requerido (0 si no existe penalidad aplicada) |
| penaltyType | Interés mensual x% | El detalle de los intereses de mora aplicados por atraso de pago de la deuda (deuda vencida). Tipo Dato: Alfanumérico. Formato: Largo máximo de 255 caracteres. Opcional |
| prejudicialCollectionAmount | 4700.00 | Monto por gastos de cobranza de la deuda. Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Valor máximo de 99999999.99. Requerido (0.00 si no existe gastos de cobranza) |
| balance | 356700.00 | Monto del saldo total no pagado de la deuda. La suma total de todos estos montos de "balance" debe ser igual al monto total que será recaudado por UPAGO (ver Tabla 1).* Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Valor máximo de 99999999.99. Requerido |
| issueDate | 2020-01-01 | Fecha de la emisión de la deuda. Tipo Dato: Fecha. Formato: yyyy-MM-dd (año 4 dígitos – mes 2 dígitos – día 2 dígitos). Requerido |
| valuationAt | 2020-02-10 | Fecha en que se valorizaron todos los montos asociados a la deuda. Puede ser entendida como la fecha de última actualización de la deuda. Tipo Dato: Fecha. Formato: yyyy-MM-dd (año 4 dígitos – mes 2 dígitos – día 2 dígitos). Opcional |
| expirationAt | 2020-01-10 | Fecha de vencimiento de la deuda (si la fecha es pasada entonces refiere a una deuda vencida). Tipo Dato: Fecha. Formato: yyyy-MM-dd (año 4 dígitos – mes 2 dígitos – día 2 dígitos). Requerido |
UPAGO envía al cliente un ejemplo de esta estructura de JSON en correo oficial de inicio de habilitación.
d. Si la información en la solicitud POST es autenticada y validada correctamente, UPAGO responderá con un objeto JSON simple que contiene los siguientes atributos:
Representa a la respuesta a la Solicitud de Transacción correctamente autenticada y validada.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| url | https://pay.upago.cl/payment/bp-checkout |
Corresponde a la URL de UPAGO donde el usuario pagador debe ser redireccionado desde la plataforma del cliente para efectuar el pago. Tipo Dato: Alfanumérico. Formato: Largo máximo de 2.048 caracteres. Requerido |
| token | 3C469E9D6C5875D37A43F353D4F88E61FCF812C66EEE3457465A40B0DA4153E0 | Corresponde a un token que UPAGO asigna para la transacción. Siempre es un valor único por cada Solicitud de Transacción. Este valor debiera ser almacenado por la plataforma del cliente y asociarlo con el ID de Transacción de recaudación informado en la Solicitud de Transacción (ver Tabla 1). Tipo Dato: Alfanumérico. Formato: Se recomienda almacenar esta información en un campo del tipo TEXT en base de datos para efectos de compatibilidad futura. Requerido |
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 seguidamente 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 | Valor |
|---|---|
| Authorization | TOKEN_DE_SEGURIDAD_DE_CLIENTE |
Prefijo Bearer no es incluido en el valor de la cabecera Authorization.
d. UPAGO anexará en el cuerpo de la notificación la siguiente estructura de JSON:
Representa a una notificación de pago sobre una transacción de pago realizada por el usuario pagador.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| transactionId | 20190225141000520C4 | Corresponde al ID de transacción de pago con origen en la plataforma de UPAGO. El valor a enviar es único por notificación de pago. Tipo Dato: Alfanumérico. Formato: Largo máximo de 64 caracteres. Requerido |
| token | 3C469E9D6C5875D37A43F353D4F88E61FCF812C66EEE3457465A40B0DA4153E0 | Corresponde a un token que UPAGO asigna para la transacción. Siempre es un valor único por cada Solicitud de Transacción. Este valor debiera ser almacenado por la plataforma del cliente y asociarlo con el ID de Transacción de recaudación informado en la Solicitud de Transacción (ver Tabla 1). Tipo Dato: Alfanumérico. Formato: Se recomienda almacenar esta información en un campo del tipo TEXT en base de datos para efectos de compatibilidad futura. Requerido |
| paymentAt | 2019-02-25T20:10:00.000Z | Fecha y hora en que se cursó el pago. Nulo Si la notificación es de pago rechazado por pasarela de pagos empleada. Tipo Dato: Fecha con hora y zona. Formato: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. Su valor siempre es devuelto en UTC 0 hora global. Opcional |
| paymentAccountingDate | 2019-02-26 | Fecha contable del pago. Similar a una fecha contable bancaria de una transacción. Nulo si la notificación es de pago rechazado por pasaela de pagos empleada. Tipo Dato: Fecha. Formato: yyyy-MM-dd. Opcional |
| amount | 235000.00 | Monto pagado por usuario en la transacción. Tipo Dato: Numérico con 2 decimales. Formato: División decimal indicado por un punto. Sin carácter separador de miles. Requerido |
| currency | CLP | Moneda de pago utilizada en la transacción. Posibles valores: CLP (peso chileno), UF (unidad de fomento - Chile), USD (dólar estadounidense). Tipo Dato: Alfanumérico. Formato: Largo máximo de 3 caracteres. Requerido |
| paymentGateway | PASARELA_DE_PAGO | Pasarela de pago utilizada en la transacción. Posibles valores según los medios de pago habilitados por UPAGO para el cliente. Tipo Dato: Alfanumérico. Formato: Largo máximo de 50 caracteres. Requerido |
| status | PAID | Estado del pago en la transacción. Posibles valores: PAID, REJECTED_BY_PAYMENTPROCESSOR, REJECTED_BY_DOUBLEPAYMENT, REVERSED_BY_PAYMENTPROCESSOR, o REVERSED_BY_BUSINESS (ver Tabla 9 para una descripción completa de estos estados). Tipo Dato: Alfanumérico. Formato: Largo máximo de 50 caracteres. Requerido |
| customer | ver tabla 2 | Corresponde a un objeto del tipo Cliente que realizó el pago. Ver sus detalles en tabla 2. Requerido |
| itemsPaid | ver tabla 4 | Corresponde a un arreglo de objetos del tipo Ítem de Consumo. Ver sus detalles en tabla 4. Requerido |
| gatewayResponse | ver tabla 7 | Corresponde a un objeto del tipo Respuesta de Pasarela de Pago donde se procesó efectivamente el pago. Ver sus detalles en tabla 7. Requerido |
Representa a la respuesta obtenida por la pasarela de pago donde se procesó efectivamente el pago.
| Nombre Atributo | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| transactionId | ecfcb13fb7fd390def245531b48a6380e10a82d17ebff5b4afdf2f0d444554et | Corresponde al ID de transacción de pago con origen en la plataforma de la Pasarela de Pago donde se procesó efectivamente el pago. El valor a enviar es único por notificación de pago. Puede contener valor Nulo. Tipo Dato: Alfanumérico. Formato: Se recomienda almacenar esta información en un campo del tipo TEXT en base de datos para efectos de compatibilidad futura. Opcional |
| paymentMethodCode | VN | Corresponde al código del método de pago con origen en la plataforma de la Pasarela de Pago. Puede contener valor Nulo. Tipo Dato: Alfanumérico. Formato: Largo máximo de 50 caracteres. Opcional |
| accountingDate | 0226 | Corresponde a la fecha contable del pago con origen en la plataforma de la Pasarela de Pago. Puede contener valor Nulo. Tipo Dato: Alfanumérico. Formato: Largo máximo de 15 caracteres. Opcional |
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 solo 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.
c. Los parámetros que se incluirán en la solicitud GET serán los siguientes:
Parámetros que son incluidos en solicitud GET para el cambio de contexto desde UPAGO a plataforma cliente por finalización de proceso de pago.
| Nombre Parámetro | Valor de Ejemplo | Descripción / Tipo Dato / Formato |
|---|---|---|
| token | 3C469E9D6C5875D37A43F353D4F88E61FCF812C66EEE3457465A40B0DA4153E0 | Corresponde al token que UPAGO asignó para la transacción. Este valor debió haber sido almacenado por la plataforma del cliente al momento de realizar la Solicitud de Transacción (ver 3.1), lo cual permitirá mostrar los datos de la recaudación correspondiente al usuario en su vuelta. Tipo Dato: Alfanumérico. Formato: (ver 3.1). Requerido |
| status | PAID | Estado del pago de la transacción. Posibles valores: ver tabla 9. Tipo Dato: Alfanumérico. Formato: Largo máximo de 50 caracteres. Requerido |
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) solo 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:
Lista todos los estados que puede tener un resultado de pago.
| Estado | Descripción |
|---|---|
| PAID | El pago fue realizado exitosamente en el medio de pago empleado por el usuario. Aunque se notifique un pago exitoso, la plataforma del cliente igualmente debe considerar que una transacción informada como exitosa podría ser reversada en las horas o días siguientes a la transacción por situaciones de fraude bancario y/o financiero. 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). |
| WAITING_PAYMENTPROCESSOR_CONFIRMATION | El pago se encuentra en un estado temporal de: esperando confirmación del estado final del pago desde la pasarela de pago empleada por el usuario en el proceso de pago. Dentro de los minutos y horas siguientes UPAGO notificará a la plataforma cliente el estado final del pago vía comunicación Confirmación de Pago a la plataforma del cliente (ver 3.3). |
| WAITING_PAYMENTINPERSON_CONFIRMATION | El pago se encuentra en un estado temporal de: esperando la realización del pago vía presencial (pago físico/en efectivo) por parte del usuario. Dentro de las siguientes 48 horas hábiles, UPAGO notificará a la plataforma cliente con el estado final del pago vía comunicación Confirmación de Pago a la plataforma del cliente (ver 3.3). |
| REJECTED_BY_PAYMENTPROCESSOR | El pago fue rechazado por la pasarela de pago empleada por el usuario en el proceso de pago. |
| REJECTED_BY_DOUBLEPAYMENT | El pago fue rechazado porque UPAGO identificó un doble pago de la cuenta asociada a la transacción. |
| REVERSED_BY_PAYMENTPROCESSOR | El pago fue reversado por la pasarela de pago empleada por el usuario en el proceso de pago. |
| REVERSED_BY_BUSINESS | El pago fue reversado por solicitud del Negocio asociado al pago (1). |
| CANCELLED_BY_USER | El pago fue cancelado por el pago, es decir, no alcanzó a ser cursado por el usuario. |
| Nota: | (1) Soportado sólo en algunos negocios o rubros comerciales. |
| Fecha | Versión | Descripción breve | Autor | Cargo |
|---|---|---|---|---|
| 09-10-2025 | 1.2 Rev 2 | Se actualizan link de ambientes. | Rodrigo Baeza | Gerente de Operaciones |