Manual Integracion Pagueatiempo V2.2.1

MANUAL DE INTEGRACIÓN
PAGOS CON TARJETA DE CRÉDITO, PSE, EFECTIVO Y LINKS DE PAGO
API RESTful – Versión 2.2.1

Marzo 2023
API RESTful – V2.2.1
CONTENIDO
1. INFORMACIÓN DE VERSIONAMIENTO ........................................................... 3
2. AMBIENTES DE INTEGRACIÓN ....................................................................... 7
3. AUTENTICACIÓN ............................................................................................... 8
4. CAMBIO DE CLAVE DE AUTENTICACIÓN DEL COMERCIO ........................ 9
5. TERMINOS Y CONDICIONES, POLÍTICA DE PRIVACIDAD Y DE
TRATAMIENTO DE DATOS PERSONALES .......................................................... 11
5.1. IMPLEMENTACIÓN OBLIGATORIA POR PARTE DEL COMERCIO .............. 11
6. PAGOS CON TARJETA DE CRÉDITO Y PSE ................................................ 12
6.1. SOLICITUDES DE PROCESAMIENTO DE PAGOS CON TARJETA DE
CRÉDITO Y PSE .............................................................................................................. 12
6.1.1. Información Referente al Hash de la Transacción ..................................... 18
6.1.2. Cálculo de Hash: ............................................................................................ 18
6.2. CONSULTA DE TRANSACCIONES TC-PSE POR NÚMERO DE
TRANSACCIÓN ............................................................................................................... 22
6.3. CONSULTA DE TRANSACCIONES TC-PSE POR PERIODO DE TIEMPO .... 24
7. PAGOS EN EFECTIVO ..................................................................................... 27
7.1. SOLICITUDES DE PROCESAMIENTO DE PAGOS EN EFECTIVO ................ 27
7.1.1. Información Referente al Hash de la Transacción ..................................... 31
7.1.2. Cálculo de Hash: ............................................................................................ 31
7.2. CONSULTA DE TRANSACCIONES EN EFECTIVO POR NÚMERO DE
TRANSACCIÓN ............................................................................................................... 32
7.3. CONSULTA DE TRANSACCIONES EN EFECTIVO POR PERIODO DE
TIEMPO ............................................................................................................................ 34
8. LINKS DE PAGOS ............................................................................................ 37
8.1. CREACIÓN DE UN LINK DE PAGO ................................................................... 37
8.2. RESPUESTA AL PROCESAMIENTO DE UN LINK DE PAGOS ...................... 39
ANEXO 1 – Códigos de Entidades Financieras en Colombia............................................ 40
ANEXO 2 – Códigos de Respuesta para Pagos en Efectivo ............................................. 42
ANEXO 3 – Tarjetas de Crédito de Prueba ..................................................................... 45
ANEXO 4 – Ejemplos Cálculo Hash Transacción ............................................................. 47
ANEXO 5 – Material de Apoyo para Integraciones ........................................................ 51
Página 1
Modelo Respuesta Transacción Pendiente ................................................................. 52
Modelo Respuesta Transacción PSE Aprobada ......................................................... 52
Modelo Respuesta Transacción PSE Fallida .............................................................. 52
Modelo Respuesta Transacción Tarjeta de Crédito Aprobada ................................. 52
Modelo Respuesta Transacción Tarjeta de Crédito Rechazada ............................... 52
Modelo HTML para Solicitud de Procesamiento de Pago TC - PSE......................... 52
Modelo HTML Uso Url de Retono al Comercio ........................................................... 52
Colección de Postman – Modelo de Uso Url Notificación Resultado ...................... 52
Página 2
1. INFORMACIÓN DE VERSIONAMIENTO
Observación general: Los ejemplo de peticiones contenidas en el presente documento, que se
realizan mediante cURL son modelos probados, sin embargo no son regla, tenga en cuenta que de
acuerdo a la librería/versión de cURL que utilice, podrían tener variaciones en su ejecución.
DATOS DE LA VERSIÓN 2.2.1

- Para comercios integrados a partir de la Versión 2, se incluye el header ‘X-pat-signature-
less-params’ el cual contiene el hash calculado a partir de la concatenación de algunos
parámetros recibidos en el request enviado a través de la URL de notificación automática
del comercio. Este nuevo header aplica, por el momento, a las transacciones realizadas con
tarjeta de crédito o PSE. La diferencia entre el hash contenido en el header X-pat-signature
y el hash del header X-pat-signature-less-params es que el primero contempla toda la
información del body del request (en su representación como cadena), y el segundo
concatena solamente algunos de los parámetros recibidos.

- Incluye información sobre ambientes de integración para los comercios (QA y Producción)
- Incluye información sobre la respuesta obtenida al procesar transacciones con las Tarjetas
de Crédito de prueba.
- Incluye anexo con ejemplos para el cálculo del hash de una transacción

- Modifica la consulta de transacciones TC-PSE por número de transacción para que el
parámetro idtr_pagueatiempo no sea obligatorio
- Agrega el parámetro idtr_pagueatiempo (no obligatorio) a la consulta de transacciones en
Efectivo por número de transacción

- Modifica la longitud del parámetro numero_orden en la solicitud de procesamiento de pago
con TC/PSE, anteriormente estaba en 32 y paso a 18 caracteres numéricos

- Incluye información relacionada con el Hash de una transacción cuando la información es
transmitida al comercio a través del parámetro url_retorno_comercio
- Incluye información relacionada con la política de privacidad y de tratamiento de datos
personales de Pagueatiempo.com, y la obligatoriedad de integración del medio técnico para
que los usuarios pagadores la acepten previo a iniciar una transacción (proceso checkout)

- Incluye información de módulo antifraude para los comercios que contraten el servicio. El
módulo antifraude solamente se aplica para transacciones en donde el usuario pagador
decide realizar el pago con tarjeta de crédito. Ajuste realizado sobre los parámetros del
apartado “SOLICITUDES DE PROCESAMIENTO DE PAGOS CON TARJETA DE CRÉDITO
Y PSE”

- Versión mayor del sistema que incluye modificaciones en los procesos de transaciones con
TC, PSE, Efectivo, Links de Pago y consultas
Importante: Los comercios que a la fecha de publicación de la presente versión se encontraban

integrados con Pagueatiempo.com, con la versión anterior 1.X.X, seguirán operando de manera
Página 3
transparente hacia esta versión. No obstante lo anterior, dichos comercios deberán realizar la
actualización de sus integraciones, conforme al actual manual de integración, antes del 31 de
marzo de 2021.

- Incluye información importante sobre los reintentos de notificación de transacción al
comercio a través de la url de retorno automático
- Incluye un nuevo anexo con material de apoyo para las integraciones de los comercios

- Generación de links de pago a través de la api
- En versiones anteriores se mencionó que a partir de la verdsion 1.0.10 se eliminaría el
parámetro de respuesta hashTransaccion, sin embargo el mismo NO será eliminarlo y se
seguirá contando en las respuestas tanto con el parámetro hashTransaccion como con el
header X-pat-signature

- Integra nuevo paramétro llamado ‘clt_payment_method’ NO obligatorio para las
solicitudes de procesamiento de pago con tarjeta de credito o PSE y su único valor debe ser
pse_tc
- Agrega la documentación de métodos para consulta y solicitudes de procesamiento de
pagos en efectivo e incluye el Anexo 1 – Códigos de Respuesta para Pagos en Efectivo.

- Desde la versión 1.0.7 se integraron los parámetros cli_url_retorno_automatico (parámetro
de configuración global del comercio) y clt_url_retorno_automatico (parámetro particular a
una transacción), los cuales son utilizados como webhooks para notificar a los comercios
el resultado obtenido sobre una solicitud de procesamiento de pago, a partir de esta versión
en los encabezados (headers) del request enviado en el webhook, se incluye el header
‘X-pat-signature’ el cual contiene el hash del request.
- Se modifica la respuesta que obtiene un comercio en el proceso de autenticación, de modo
tal que adicionalmente al token, se retorna el índice ‘url_procesamiento’, cuyo valor debe
ser utilizado para iniciar la solicitud de procesamiento de un pago conforme a lo descrito en
el numeral 3 del presente manual.

- A partir de esta versión los comercios podrán informar una URL de Retorno Automático la
cual será configurada de manera global para el comercio, tal cual como se hace con la URL
de Retorno que el comercio informa al momento de su creación en la plataforma, de modo
tal que Pagueatiempo.com le pueda transmitir de manera automática la respuesta al
comercio sin la necesidad de la interacción del usuario pagador en el click al botón ‘Volver
al Comercio’ que se muestra en el Voucher de Pagueatiempo.com. Aquí es importante
aclarar que el proceso de ‘Volver al Comercio’ NO SE ELIMINA, este es un proceso
obligatorio que todo comercio debe implementar a fin de mostrar en pantalla al
usuario su propio Voucher de confirmación de transacción
- Agrega el parámetro ‘clt_url_retorno_automatico’ al procesamiento de una solicitud de pago,
en este campo los comercios podrán enviar una url de retorno de automático para la
transacción y que sea diferente a la configurada de manera global para el comercio
- Agrega el parámetro ‘clt_informacion_adicional’ al procesamiento de una solicitud de pago,
en este campo los comercios podrán enviar hasta 5000 caracteres de información
- Agrega el campo ‘urlRetornoAutomatico’ en la respuesta al procesamiento de una solicitud
de pago y a la consulta de transacciones, su valor corresponde con el valor recibido en el
Página 4
parámetro ‘clt_url_retorno_automatico’ cuando se crea la transacción, si dicho parámetro no
es recibido o se recibe vacío, el valor retornado será la url de retorno automático global
configurada para el comercio
- Agrega campo ‘informacionAdicional’ a la respuesta al procesamiento de una solicitud de
pago y a la consulta de transacciones, la información retornada corresponde con la
información recibida en el parámetro clt_informacion_adicional cuando se crea la
transacción
- Agrega campo ‘pagador’ a la respuesta al procesamiento de una solicitud de pago y a la
consulta de transacciones, este campo contiene un objeto json con información que recibe
Pagueatiempo.com al iniciar una transacción tales como: nombres, apellidos, email,
dirección, teléfono, móvil, país, ciudad y nacionalidad.

- Parámetro ‘clt_purchase_operation_number’ cambió tipo a numérico
- Agrega campo ‘observaciones’ a la respuesta al procesamiento de una solicitud de pago y a
la consulta de transacciones, la información retornada corresponde con la información
recibida en el parámetro clt_additional_observations cuando se crea la transacción
- Agrega el parámetro ‘clt_url_retorno’ al procesamiento de una solicitud de pago, en este
campo los comercios podrán enviar un url de retorno para la transacción que sea diferente
a la configurada de manera global para el comercio
- Agrega el campo ‘urlRetorno’ a la consulta de transacciones, su valor corresponde con el
valor recibido en el parámetro ‘clt_url_retorno’ cuando se crea la transacción, si dicho
parámetro no es recibido o se recibe vacío, el valor retornado será la url de retorno global
configurada para el comercio
- Las anteriores modificaciones no afectan la integración realizada previamente por los
comercios toda vez que se trata de información adicional que se incluye en los Json de
respuesta a transacciones y podrán implementarlas en cualquier momento

- Incluye modificaciones al proceso de interno de procesamiento de solicitudes de pago de
conformidad a ajustes de integración realizados entre ACH - Credibanco - Pagueatiempo.
Verificar información relacionada en el numeral 3- ENVÍO DE SOLICITUDES PARA
PROCESAMIENTO DE PAGOS, apartado Parámetros Retornados en la Respuesta
- Modificaciones en parámetro de retorno xmlResponse
DATOS DE LA VERSIÓN 1.0.4 (Actualización de Seguridad)

- Integra el cálculo del hash de la transacción el cual es incluido como parámetro dentro de la
información que se retorna al comercio (Información registrada en la página 10 de esta
versión).

- Agrega el campo quotaCode en la respuesta a la solicitud de pago
- Actualiza ejemplos del voucher mostrado en pagueatiempo.com al usuario tanto por pagos
procesados mediante TC como para pagos procesados por PSE
- Agrega ejemplo de respuesta enciada a la URL de retorno del comercio cuando el pago es
procesado mediante PSE
- Agrega el apartado Observaciones a Pagos Procesados Mediante PSE en el Numeral 3
(ENVÍO DE SOLICITUDES PARA PROCESAMIENTO DE PAGOS), que incluye dos
observaciones relacionadas con información importante en cuanto al procesamiento de
pagos mediante PSE
Página 5

- Agrega ejemplo de voucher mostrado por pagueatiempo.com al usuario
- Agrega ejemplo de respuesta enviada a la URL de retorno del comercio cuando el pago es
procesado mediante TC
Página 6
2. AMBIENTES DE INTEGRACIÓN
Los comercios cuentan con dos ambientes de integración: QA y Producción
Cuando un comercio es habilitado en Pagueatiempo, solamente tendrá acceso al

ambiente QA o de pruebas con el objetivo de que pueda llevar a cabo su
integración, de modo tal que una vez haya finalizado su proceso deberá reportarlo
a Pagueatiempo y se procederá a la verificación de transacciones de prueba
realizadas por el comercio.
El comercio deberá tener registro, como mínimo, de las siguientes transacciones:

- 10 transacciones aprobadas (TC y PSE)
- 10 transacciones rechazadas (TC y PSE)
Observación: Es importante tener en cuenta que en el servidor QA todas las

transacciones son eliminadas los sábados a las 18 horas. Del mismo modo el
servidor QA se encuentra activo de lunes a sábado entre las 07 y las 19 horas.
Igualmente deberá informar la URL en donde se encuentra el formulario de pago

del comercio (en donde se inicia el proceso para el pago de una transacción) para
verificación de cumplimiento de los TERMINOS Y CONDICIONES, POLÍTICA DE
PRIVACIDAD Y DE TRATAMIENTO DE DATOS PERSONALES, relacionados en
el numeral 5 de este manual.
Una vez realizadas las verificaciones, se procederá con la configuración y activación

del comercio en el ambiente de producción.
URL QA
https://apiqa.pagueatiempo.io
URL Producción
https://api.pagueatiempo.com
Nota 1: El ambiente QA al momento de generación de esta versión del manual de integración,

solamente este habilitado para procesamiento de pagos de pruebas con Tarjeta de Crédito y PSE
Nota 2: El ambiente QA solamente es funcional para integraciones de comercios con la versión 2 o

superior de este manual de integración
Página 7
3. AUTENTICACIÓN
Para iniciar el procesamiento de cualquier tipo de solicitud, por ejemplo: una
solicitud de pago, el comercio deberá autenticarse con el objetivo de obtener el
token de autenticación correspondiente.
Cada token estará vigente para una (1) sola petición independiente del endpoint a
consumir. Del mismo modo, el tiempo máximo de vida de cada token es de una (1)
hora.
Cabe anotar que todos los tokens generados son firmados electrónicamente por la
plataforma y en cada respuesta retornada por el sistema se devolverá un token de
refresco dentro de los encabezados correspondientes a Response Headers, token
que podrá ser utilizado en la siguiente petición conforme a su ciclo de vida.
El esquema de autenticación HTTP utilizado se denomina BEARER TOKEN y se

hace uso del estandar JSON Web Token1.
Al recibir la respuesta del proceso de autenticación, adicional al token, el comercio

recibirá el parámetro ‘url_procesamiento’, que incluye la URL hacia la cual el
comercio debe redirigir al usuario al iniciar una solicitud de procesamiento de
pago con TC, PSE o Efectivo.
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/login
Método HTTP
POST
Parámetros Requeridos
email comercio@dominio.com
password 123456
Tipo de Respuesta
Objeto JSON
Códigos HTTP de Respuesta

200 Autenticación exitosa
401 Autenticación no exitosa
1 https://es.wikipedia.org/wiki/JSON_Web_Token
Página 8
Ejemplo Request
curl --location --request POST 'https://
https://{url_ambiente_pagueatiempo}/api/v2/login?email=comercio@example.com&password=@PassWord' \
--header 'Content-Type: application/json' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Accept: application/json'
Ejemplo de Respuesta Exitosa (Código HTTP 200)

{
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9hcGkucGFndWVhdGllbXBvLmNvbVwvYXBpXC92MVwvbG9naW4iL
CJpYXQiOjE1NjE1Nzg3MTQsImV4cCI6MTU2MTU4MjMxNCwibmJmIjoxNTYxNTc4NzE0LCJqdGkiOiI2QUE5ek9Eb3JoM0p1d2tMIiwic3ViIjox
1LCJwcnYiOiI3YjE0NzQ0ZDczMTcwNGI1YzFiMzExZTY3Y2FlMDgzN2NjY2U4ZThiIiwiaWQiOjEsImVtYWlsIjoiYWJlbHRyYW5AdmVjdG9ybm
FyYW5qYS5jb20iLCJpZGVudGlmaWNhY2lvbiI6Ijc5NjI5MDc5Iiwibm9tYnJlIjoiS2F5Y2VlIEhhcnRtYW5uIiwidGlwbyI6IkFETUlOSVNUUkFET1Iif
Q.VOFWjwilFgbxZRdZsXTQd1wCc6lc9abe0dxNsXnTuDM",
"url_procesamiento": "https://{url_ambiente_pagueatiempo}/api/v2/procesar-pago"
}
Ejemplo de Respuesta No Exitosa (Código HTTP 401)

{
"message": "Error de autenticación",
"errors": [
"No fue posible autenticar al usuario"
]
}
4. CAMBIO DE CLAVE DE AUTENTICACIÓN DEL COMERCIO

Permite al comercio, en cualquier momento, cambiar la clave de autenticación.
Características de composición de la clave de autenticación:

- Tener mínimo 10 caracteres
- Tener por lo menos un caracter en mayúscula
- Tener por lo menos un caracter en minúscula
- Tener por lo menos un dígito entre 0 y 9
- Tener por lo menos un caracter especial entre:
o @#$%&*-_+=~|:;<>,.?
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/cambiar-password
Método HTTP
POST
Página 9
Headers
Content-Type: application/json
X-Requested-With: XMLHttpRequest
Accept: application/json
Authorization: Bearer token_autenticacion (previamente obtenido)
claveActual 123456
claveNueva 654321
Tipo de Respuesta
Objeto JSON

200 Clave modificada
401 No autorizado
422 No procesable
Ejemplo Request
curl --location --request POST 'https://{url_ambiente_pagueatiempo}/api/v2/cambiar-password?claveActual=123456&claveNueva=123456' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N…'

{
"message": "Clave de acceso modificada"
}
Ejemplo de Respuesta No Autorizado (Código HTTP 401)

{
"errors": [
"La clave actual no coincide"
]
}
Ejemplo de Respuesta con Fallo en Autenticación (Código HTTP 401)

{
"errors": [
"Credenciales de acceso no válidas, verifique el token"
]
}
Página 10
Ejemplo de Respuesta No Procesable (Código HTTP 422)
{
"message": "Error en Clave Nueva",
"errors": [
"El formato del campo clave nueva no es válido."
]
}
5. TERMINOS Y CONDICIONES, POLÍTICA DE PRIVACIDAD Y DE

TRATAMIENTO DE DATOS PERSONALES
5.1. IMPLEMENTACIÓN OBLIGATORIA POR PARTE DEL COMERCIO
Para dar cumplimiento a los requerimientos establecidos por la ley 1581 de 2012,
y para obtener la aprobación final del proceso de integración con
Pagueatiempo.com, es obligación del comercio agregar en su proceso de
checkout una casilla de verificación que indique al usuario pagador que debe dar
click y aceptar los “Términos y condiciones de uso y la política de privacidad y
tratamiento de datos personales” de Pagueatiempo.com.
Dicha casilla debe contener el siguiente mensaje: “Acepto los términos y

condiciones de uso y la política de privacidad y tratamiento de datos personales de
Pagueatiempo.com como pasarela para el procesamiento del pago que estoy a
punto de iniciar. Esta política puede ser consultada en
https://pagueatiempo.com/legal”, ejemplo:
Acepto los términos y condiciones de uso y la política de privacidad y de

tratamiento de datos personales de Pagueatiempo.com como pasarela para
el procesamiento del pago estoy a punto de iniciar. Los términos y condiciones
de uso pueden ser consultados en https://pagueatiempo.com/legal
Esta casilla de verificación deberá cumplir dos funciones principales:

• El botón ‘pagar’, ‘comprar’ o ‘procesar pago’ ubicado en el checkout del
comercio, solamente se deberá activar si la casilla de verificación es
marcada.
• El link o vínculo a https://pagueatiempo.com/legal deberá abrir una nueva
pestaña de navegación el sitio web de Pagueatiempo en el apartado
correspondiente del link.
Página 11
6. PAGOS CON TARJETA DE CRÉDITO Y PSE
6.1. SOLICITUDES DE PROCESAMIENTO DE PAGOS CON TARJETA DE

CRÉDITO Y PSE
Proceso que permite la transmisión hacia pagueatiempo.com de los parámetros
requeridos para el inicio del procesamiento de una solicitud de pago con tarjeta de
crédito o PSE.
La redirección hacia esta URL se debe realizar desde la acción de procesamiento

del formulario de carrito de compras o del formulario en donde se indica al usuario
pagador los totales a cancelar.
Observación: Este proceso NO puede ser realizado en background, se recomienda NO

realizar este proceso dentro de un iframe o marco porque el navegador del usuario debe ser
redirigido hacia la URL en donde se realizará el procesamiento del pago correspondiente.
Url de Procesamiento
La URL de procesamiento se obtiene en el momento de la autenticación en el
parámetro url_procesamiento.
Observación: El comercio debe redirigir su proceso de pago a la url de procesamiento

obtenida.
Método HTTP
POST
Ejemplo de definición del formulario de pago en HTML:

<form method="POST" action="{url_procesamiento}">
Parámetro Tipo / Longitud Descripción Obligatorio
metodo_pago Alfanumérico Indica el método de pago, NO
Max 10 para transacciones PSE o TC
el valor enviado debe ser:
pse_tc
token Alfanumérico Token de Autenticación Si
Max N/A
nit_comercio Numérico NIT del Comercio o Si
Max 20 documento registrado en
pagueatiempo.com, NO debe
incluir el dígito de verificación,
ni separadores de miles o
decimales
valor Decimal 15.2 Valor total a pagar o de Si
Max 15 enteros con compra. El valor debe ir sin
2 decimales separadores de miles y usar
punto (.) como separador de
decimales
Página 12
iva Decimal 15.2 Monto del valor IVA, relativo Si
Max 15 enteros con al impuesto asociado a la
2 decimales compra, si la compra NO
tiene IVA el parámetro debe
enviarse en ceros: 0.00
moneda Alfanumérico Código de moneda según Si
Max 3 estándar ISO-4217, ej, Peso
Colombiano COP
numero_orden Numérico Número (identificador) del Si
Max 18 pedido en el sistema del
comercio, debe ser único
para cada transacción del
comercio en el sistema.
nombre_usuario Alfanumérico Nombre del usuario que No
Max 150 realiza el pago
correo_usuario Alfanumérico Correo del usuario que realiza Obligatorio si
Max 100 el pago posee módulo
antifraude
tipo_documento_usuario Alfanumérico Tipo de documento del Obligatorio si
Max 3 usuario que realiza el pago: posee módulo
antifraude
NIT => NIT
CC => CEDULA DE CIUDADANIA
CE => CEDULA EXTRANJERIA
documento_usuario Alfanumérico Número de documento del Obligatorio si

Max 15 usuario que realiza el pago posee módulo
antifraude
direccion_usuario Alfanumérico Dirección de facturación del Obligatorio si
antifraude
direccion_envio_usuario Alfanumérico Dirección de envío del Obligatorio si
antifraude
ciudad_facturacion_usuario Alfanumérico Ciudad de facturación del Obligatorio si
antifraude
departamento_usuario Alfanumérico Departamento o estado de Obligatorio si
Max 50 facturación del usuario que posee módulo
realiza el pago antifraude
pais_facturacion_usuario Alfanumérico País de facturación del Obligatorio si
antifraude
codigo_postal_usuario Alfanumérico Código postal de la dirección Obligatorio si
Max 10 del usuario que realiza el posee módulo
pago, de acuerdo a la antifraude
información proporcionada
por la oficina postal de
Colombia.
telefono_usuario Alfanumérico Teléfono del usuario que Obligatorio si
Max 50 realiza el pago posee módulo
antifraude
Página 13
url_retorno_comercio Alfanumérico URL de retorno al comercio. Si
Max 255
Esta url se utiliza para
redirigir al usuario de vuelta al
comercio, la redirección se
realiza mediante FormData2
url_notificacion_resultado Alfanumérico URL de notificación Si
Max 255 automática del resultado de la
transacción (Webhook3)
La información es enviada
mediante método POST y el
body del request contendrá
un objeto json con los
parámetros retornados.
json_params Json4 Json en donde el comercio No
puede enviar información
relevante para la transacción,
esta información es retornada
al comercio cuando se le
notifica el resultado de la
transacción.
Debe estar compuesto para

pares nombre-valor:
{
"<name1>":"<value1>",
…
"<nameN>":"<valueN>"
}
Cuando se inicia una solicitud de procesamiento de pago con TC o PSE, el estado

inicial de esa solicitud por defecto será ‘Pendiente’.
Una vez se surte todo el ciclo de procesamiento de la solicitud de pago,

pagueatiempo.com retornará al comercio la respuesta con el resultado del
procesamiento. Esta respuesta es enviada al comercio de dos maneras:
• De manera automática a la URL de notificación de resultado, esta respuesta

es intentada por Pagueatiempo.com hasta en 3 ocasiones:
2
https://developer.mozilla.org/es/docs/Learn/HTML/Forms/Sending_and_retrieving_form_data
3
https://es.wikipedia.org/wiki/Webhook
4
https://www.json.org/json-en.html
Página 14
En el primer intento si NO se obtiene respuesta del comercio (timeout) o si el
código HTTP de respuesta del comercio es diferente de 200 se reintenta:
Segundo Reintento 3 segundos después del primer intento

Tercer Reintento 6 segundos después del segundo intento
Si después de los tres reintentos NO se obtiene el código 200 en la respuesta

del comercio, la transmisión finaliza.
Igualmente la transmisión se entiende exitosa si en cualquiera de los tres

intentos se obtiene el código 200.
• De manera manual cuando el usuario pagador hace click en el botón ‘Volver

al Comercio’ que se muestra en el voucher de transacción.
El retorno de la respuesta a la solicitud de procesamiento es realizado mediante el

método HTTP POST y con la misma se incluyen los parámetros que son listados a
continuación. Estos parámetros deberán ser procesados por el comercio y deberá
mostrar en pantalla al usuario el resultado de la transacción (Voucher de Compra)
Método Retorno HTTP

POST
Parámetros Retornados en la Respuesta

Parámetro Tipo / Longitud Descripción
comercio Alfanumérico Nombre del comercio
Max 255
identificacion_comercio Alfanumérico NIT del Comercio que incluye el dígito de
Max 20 verificación o documento de identidad con el
que se registro en pagueatiempo.com, sin
separadores de miles ni decimales
codigo_unico Alfanumérico Código único del comercio
Max 20
terminal Alfanumérico Código de terminal del comercio
Max 20
fecha_hora_inicio Alfanumérico Fecha y hora de inicio de la transacción en
Max 20 formato:
YYYY-MM-DD HH:MM:SS
fecha_hora_final Alfanumérico Fecha y hora de respuesta de la transacción
Max 20 en formato:
YYYY-MM-DD HH:MM:SS
tipo_pago Alfanumerico Tipo de Pago, puede contener tres posibles
Max 10 valores:
TC para pagos con Tarjeta de Crédito

PSE para pagos por PSE
Vacio o null cuando no se logra identificar el
tipo de pago, por ejemplo cuando la
Página 15
transacción es abandonada antes de realizar
el pago
numero_orden Numérico Número (identificador) del pedido en el
Max 32 sistema del comercio es único para cada
idtr_pagueatiempo Numérico Número (identificador) de la transacción en
Max 32 pagueatiempo.com
valor Decimal 15.2 Valor total de pago o compra.
Max 15 enteros con
2 decimales
iva Decimal 15.2 Monto del valor IVA, relativo al impuesto
Max 15 enteros con asociado a la compra, si la compra NO tiene
2 decimales IVA el parámetro se retornará en ceros: 0.00
moneda Alfanumérico Código de moneda según estándar ISO-4217,
Max 3 ej, Peso Colombiano COP
autorizacion Alfanumérico En caso que la transacción haya sido
Max 20 autorizada/rechazada/negada/fallida, este
parámetro podrá contener el código de la
transacción.
error_code Alfanumérico Código de resultado de procesamiento de la
Max 4 transacción:
0 = Rechazada
2 = Aprobada
4 = Anulada
6 = Rechazada
7 = Pendiente
8 = Fallida o Abandonada
error_message Alfanumérico Mensaje complementario al parámetro
Max 100 error_code
estado Alfanumerico Estado de procesamiento de la transacción:
Max 50
Aprobada
Anulada
Rechazada
Pendiente
Fallida o Abandonada
detalle_pse Json Json conteniendo información relacionada con
el procesamiento de la transacción cuando el
pago es realizado mediante PSE:
{
"docType": "CC",
"userType": "0",
"docNumber": "1010123456",
"finalizeStatus": "SUCCESS",
"traceabilityCode": "1874622",
"financialInstitutionCode": "1022"
}
Página 16
detalle_tc Json Json conteniendo información relacionada con
el procesamiento de la transacción cuando el
pago es realizado mediante Tarjeta de Crédito:
{
"pan": "456396**1999",
"maskedPan": "456396**1999",
"expiration": "202412",
"approvalCode": "097295",
"paymentSystem": "VISA",
"cardholderName": "Pedro Perez"
}
numero_tarjeta Alfanumérico Número de tarjeta ingresada por el

Max 40 tarjetahabiente para pagos con Tarjeta de
Crédito, el dato es enmascarado, ej:
456396**1999
numero_cuotas Numérico Numero de cuotas cuando el pago es
realizado con Tarjeta de Crédito
ip Alfanumérico Dirección IP desde donde se realizó el pago
Max 15
json_params Json Json enviado por el comercio al inicio de la
transacción, si el comercio NO envió el
parámetro, de todas maneras es retornado
con valores agregados por
pagueatiempo.com:
{
"IVA.amount": "1900000",
"installments": 1,
}
IVA.amount corresponde al valor del IVA de la

transacción, no incluye separadores de miles
ni seprador de decimales, los dos últimos
caracteres corresponden a posiciones
decimales, en el ejemeplo, 1900000 deberá
ser tenido en cuenta como 19000.00
url_retorno_comercio Alfanumérico URL de retorno al comercio.
Max 255
url_notificacion_resultado Alfanumérico URL de notificación automática del resultado
Max 255 de la transacción (Webhook)
usuario Json Json conteniendo informacion del usuario que

realizó el pago, contendrá valores siempre que
el comercio halla enviado los parámetros
correspondientes al inicio de la transacción:
Página 17
"nombres" : "",
"email" : "",
"tipo_documento": "",
"documento" : "",
"direccion" : "",
"telefono" : ""
}
hash_transaccion Alfanumérico Hash calculado para la transacción, éste

Max 100 parámetro solamente es retornado mediante la
url_retorno_comercio (En el caso de la
notificación al comercio mediante el parámetro
url_notificacion_resultado)
6.1.1. Información Referente al Hash de la Transacción

El hash de la transacción es un dato único para cada transacción y permite verificar
que la data transmitida desde pagueatiempo.com NO ha sido modificada antes de
ser recibida por el comercio (Integridad de la Información).
Por lo anterior, cuando el comercio recibe la respuesta de una solicitud de

procesamiento de pago, debe realizar el cálculo del hash conforme al estándar
indicado, para compararlo con el hash recibido de modo tal que se pueda verificar
si son iguales o diferentes. Se recomienda revisar el ANEXO 4 – Ejemplos Cálculo
Hash Transacción
6.1.2. Cálculo de Hash:

El hash es calculado mediante el método HMAC (Soportado para todos los
lenguajes de programación) con algoritmo de encriptación SHA256, el cual se
encarga de cifrar una cadena de información mediante una llave criptográfica
secreta (única para cada comercio).
En el caso de los parámetros retornados mediante el parámetro

url_retorno_comercio, la cadena de información requerida para generar el hash
deberá estar compuesta por la concatenación de los siguientes parámetros
retornados:
● identificacion_comercio (numérico, sin puntos, ni guion, ni dígito de verificación)

● fecha_hora_final
● numero_orden
● moneda
● valor
● autorizacion
● error_code
● error_message
Página 18
● estado
● ip
Es de suma importancia que la concatenación de los campos conserve el orden

indicado y no se agregue ningún carácter de concatenación entre ellos. El hash
calculado por el comercio deberá ser comparado con el hash retornado por
Pagueatiempo.com en el parámetro hash_transaccion.
En el caso de la notificación al comercio mediante el parámetro

url_notificacion_resultado, en los encabezados (headers) del request enviado, se
incluyen dos encabezados:
- Header ‘X-pat-signature’: contiene el hash del request completo, este hash

es calculado teniendo en cuenta que la cadena a cifrar es precisamente el
request de la petición, es decir, la representación como string del JSON
o body del request.
- Header ‘X-pat-signature-less-params’: contiene el hash calculado a partir

de la concatenación de los siguientes parámetros recibidos en el request:
o identificacion_comercio
o fecha_hora_final
o numero_orden
o moneda
o valor
o autorizacion
o error_code
o error_message
o estado
o ip
Una vez el hash es calculado por el comercio deberá compararlo contra el hash
retornado por pagueatiempo.com, dicha comparación derivará en dos posibles
opciones:
1. Los hash son iguales, en cuyo caso la transacción es válida y puede ser
procesada por el comercio.
2. Los hash son diferentes, lo que implica que la data transmitida por
pagueatiempo.com fue modificada en algún punto antes de ser recibida
por el comercio y dicha data NO puede ser utilizada por el comercio. En
este caso se sugiere que el comercio consulte la transacción a través del
endpoint de Consulta de Transacciones Por Número de Transacción
y que utilice como válidos los valores retornados por dicha consulta.
Documentación Relacionada:
Página 19
https://es.wikipedia.org/wiki/HMAC
Observaciones:
● Adicionalmente a la integración del cálculo del hash, es muy

importante que la URL de retorno del comercio y URL de notificación
de resultado operen sobre HTTPS.
● Si su comercio no cuenta con la llave criptográfica para el cálculo del
hash, debe solicitarla a pagueatiempo.com
Con el retorno de la información finaliza el ciclo de vida de una solicitud de

procesamiento de pago con tárjeta de crédito o PSE.
Observaciones a Pagos Procesados Mediante PSE

Observación 1: Los pagos procesados mediante PSE, cuando son
Rechazados, pueden retornar una valor de autorización aún cuando la
transacción sea rechazada, información que corresponde al código asignado
por PSE a la transacción el cual es conocido como CUS (Código Único de
Seguimiento), sin embargo los códigos de error y mensaje son los que indican
en la presente documentación.
Ejemplo de voucher mostrado al usuario que realiza la transacción cuando el pago

es realizado mediante TC:
Página 20
Ejemplo de voucher mostrado por pagueatiempo.com al usuario que realiza la

transacción cuando el pago es realizado mediante PSE:
Página 21
6.2. CONSULTA DE TRANSACCIONES TC-PSE POR NÚMERO DE

TRANSACCIÓN
Permite consultar la información correspondiente a transacciones con TC o PSE
que previamente han sido enviadas para su procesamiento.
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/consultar-transaccion
Método HTTP
POST
API Rate Limit

Máximo 12 consultas por hora por comercio
Observación: La tasa límite de consultas obedece a que pagueatiempo.com siempre
comunica el resultado de las transacciones a través de los parámetros
url_retorno_comercio y url_notificacion_resultado
Headers
Página 22
nit_comercio NIT del Comercio o documento de identidad con el que se registró
en pagueatiempo.com, NO debe incluir el dígito de verificación, ni
separadores de miles o decimales (Solo números)
numero_orden 123456 (Identificador de la orden en el comercio)
idtr_pagueatiempo 654321 (Identificador de la orden en pagueatiempo – no
obligatorio)
Tipo de Respuesta
Objeto JSON

200 Consulta realizada con éxito
401 No autorizado
404 No existe
429 Too Many Requests
Ejemplo Request
curl --location --request POST 'https://{url_ambiente_pagueatiempo}/api/v2/consultar-transaccion' \
--header 'Content-Type: application/application-json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N…' \
--form 'numero_orden=123456' \
--form 'idtr_pagueatiempo=654321' \
--form 'nit_comercio=900123456'
Ejemplo de Respuesta Exitosa – Transacción encontrada (Código HTTP 200)

En este caso el objeto Json de respuesta contendrá los parámetros relacionados en
Parámetros Retornados
{
"data": {
"comercio": "",
"identificacion_comercio": "",
"codigo_unico": "",
"terminal": "",
"fecha_hora_inicio": "",
"fecha_hora_final": "",
"tipo_pago": "",
"numero_orden": "",
"idtr_pagueatiempo": "",
"moneda": "",
Página 23
"valor": "",
"iva": "",
"autorizacion": "",
"error_code": "",
"error_message": "",
"estado": "",
"detalle_pse": "",
"detalle_tc": "",
"numero_tarjeta": "",
"numero_cuotas": "",
"ip": "",
"json_params": {},
"url_retorno_comercio": "",
"url_notificacion_resultado": "",
"usuario": {}
}
}

{
"errors": [
]
}
Ejemplo de Respuesta No Existe (Código HTTP 404)

{
"message": "Error en Consulta",
"errors": [
"La transacción XXXXXX que intenta consultar no existe."
]
}
6.3. CONSULTA DE TRANSACCIONES TC-PSE POR PERIODO DE TIEMPO

Permite consultar, en un rango de fechas, la información correspondiente a
transacciones realizadas mediante TC o PSE que previamente han sido enviadas
para su procesamiento.
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/consulta-transacciones
Método HTTP
Página 24
POST
API Rate Limit

Máximo 1 consulta por hora por comercio
Rango máximo de consulta un (1) mes calendario
Headers
nit_comercio NIT del Comercio o documento de identidad con el que se registro
fecha_inicial 2020-05-01 (Fecha en formato YYYY-MM-DD)
fecha_final 2020-05-31 (Fecha en formato YYYY-MM-DD)
Tipo de Respuesta
Objeto JSON

401 No autorizado
404 No se encontraron transacciones
En la respuesta exitosa se retornará una colección de objetos Json (uno por cada
transacción encontrada), en donde cada objeto Json contendrá los parámetros
relacionados en el Numeral 3 - Parámetros Retornados
Ejemplo Request
curl --location --request POST 'https://{url_ambiente_pagueatiempo}/api/v2/consulta-transacciones' \
--form 'nit_comercio=900123456' \
--form 'fecha_inicial=2020-09-01' \
--form 'fecha_final=2020-09-30'

{
Página 25
"data": [
{
"comercio": "",
"codigo_unico": "",
"terminal": "",
"tipo_pago": "",
"numero_orden": "",
"moneda": "",
"valor": "",
"iva": "",
"autorizacion": "",
"error_code": "",
"estado": "",
"detalle_pse": "",
"detalle_tc": "",
"ip": "",
"json_params": {},
"usuario": {}
},
{
"comercio": "",
"codigo_unico": "",
"terminal": "",
"tipo_pago": "",
"numero_orden": "",
"moneda": "",
"valor": "",
"iva": "",
"autorizacion": "",
"error_code": "",
"estado": "",
"detalle_pse": "",
Página 26
"detalle_tc": "",
"ip": "",
"json_params": {},
"usuario": {}
}
]
}

{
"errors": [
]
}
Ejemplo de Respuesta Sin Transacciones (Código HTTP 404)

{
"data":[]
}
7. PAGOS EN EFECTIVO
7.1. SOLICITUDES DE PROCESAMIENTO DE PAGOS EN EFECTIVO

Proceso que permite la transmisión hacia pagueatiempo.com de los parámetros
requeridos para el inicio del procesamiento de una solicitud de pago en efectivo.
Este servicio NO se encuentra activado por defecto para los comercios y debe ser
habilitado previa solicitud.
Generalmente la redirección hacia esta URL se debe realizar desde la acción de

procesamiento del formulario de carrito de compras o del formulario en donde se
indica al usuario pagador los totales a cancelar.
Observación: Este proceso NO puede ser realizado en background, se recomienda NO

realizar este proceso dentro de un iframe o marco porque el navegador del usuario debe ser
redirigido hacia la URL en donde se realizará el pago correspondiente.
Página 27
Url de Procesamiento
La URL de procesamiento se obtiene en el momento de la autenticación en el
parámetro url_procesamiento.
Observación1: El comercio debe redirigir su proceso de pago a la url de procesamiento obtenida.
Método HTTP
POST
Ejemplo de definición del formulario de pago en HTML:

<form method="POST" action="{url_procesamiento}">
token Alfanumérico Token de Autenticación Si
Max N/A
nit_comercio Numérico NIT del Comercio o Si
Max 20 documento registrado en
pagueatiempo.com, NO debe
incluir el dígito de verificación,
ni separadores de miles o
decimales
metodo_pago Alfanumérico Indica el método de pago, Si
Max 10 único valor aceptado:
efectivo
medio_pago_efectivo Alfanumérico Indica el medio de pago, su Si
Max 25 valor debe ser alguno de los
siguientes:
efecty apostar
gana sured
baloto susuerte
puntored
valor Numérico Valor total a pagar o de Si
compra. El valor debe ser un
valor entero positivo, no
puede tener decimales, si se
envían decimales
pagueatiempo.com
redondeará el valor hacia
arriba, ej, 500.58 sera
procesado como 501
iva Decimal 1.3 Monto porcentual Si
Max 1 entero con 3 correspondiente al IVA de la
decimales orden, ej, para IVA del 19% el
valor a enviar debe ser 0.19
Si la transacción NO tiene
IVA deberá enviarse el valor
en ceros: 0.00
Página 28
descripcion Alfanumerico Descripción de la transacción Si
Max 250
moneda Alfanumérico Código de moneda según Si
Max 3 estándar ISO-4217, ej, Peso
Colombiano COP
numero_orden Numérico Número (identificador) del Si
Max 16 pedido en el sistema del
comercio es único para cada
nombre_usuario Alfanumérico Nombre del usuario que No
correo_usuario Alfanumérico Correo del usuario que realiza No
Max 100 el pago
tipo_documento_usuario Alfanumérico Tipo de documento del No
Max 3 usuario que realiza el pago:
NIT => NIT

CC => CEDULA DE CIUDADANIA
CE => CEDULA EXTRANJERIA
documento_usuario Alfanumérico Número de documento del No
Max 15 usuario que realiza el pago
direccion_usuario Alfanumérico Dirección del usuario que No
telefono_usuario Alfanumérico Teléfono del usuario que No
url_notificacion_resultado Alfanumérico URL de notificación SI
Max 255 automática del resultado de la
transacción (Webhook5)
La información es enviada
mediante método POST y el
body del request contendrá
un objeto json con los
parámetros retornados.
Cuando se inicia una solicitud de procesamiento de pago, el estado inicial de esa

solicitud por defecto será ‘Pendiente’ (código 9999).
Una vez el adquirente (comprador) realiza el pago, Pagueatiempo notificará al

comercio mediante la url de notificación de resultado, el cambio de estado de la
transacción.
Se debe tener en cuenta, cuando se habilita el servicio de pagos en efectivo para

un comercio, se configura un tiempo máximo de vigencia para los pagos, por lo que
la respuesta automática se realizará máximo en dicho límite, y si el usuario no
realiza el pago durante dicha vigencia el estado de la transacción cambiará a
Vencida (código 9998)
5
https://es.wikipedia.org/wiki/Webhook
Página 29
La respuesta automática es realizada mediante el método HTTP POST y con la

misma se incluyen los parámetros que son listados a continuación para que el
comercio pueda avanzar con sus procesos internos.
Método Retorno HTTP

POST
Parámetros Retornados en la Respuesta

comercio Alfanumérico Nombre del comercio
Max 255
identificacion_comercio Alfanumérico NIT del Comercio que incluye el dígito de
Max 20 verificación o documento de identidad con el
que se registro en pagueatiempo.com, sin
separadores de miles ni decimales
fecha_hora_respuesta Alfanumérico Fecha y hora de respuesta en formato:
Max 20 YYYY-MM-DD HH:MM:SS
numero_orden Numérico Identificador único por cada transacción
Max 16
idtr_pagueatiempo Numérico Número (identificador) de la transacción en
Max 16 pagueatiempo.com
moneda Alfanumérico Código de moneda según estándar ISO-4217,
Max 3 ej, Peso Colombiano COP
valor Número entero Valor total a pagar o de compra
iva Decimal 1.3 Monto porcentual correspondiente al IVA de la
Max 1 entero con 3 orden, ej, para IVA del 19% el valor a enviar
decimales debe ser 0.19
autorizacion Alfanumérico Verificar el Anexo 1 – Códigos de Respuesta
Max 4 para Pagos en Efectivo
mensaje_autorizacion Alfanumérico Mensaje del resultado
Max 250
metodo_pago Alfanumérico Indica el método de pago, único valor
Max 10 retornado:
efectivo
medio_pago_efectivo Alfanumérico Indica el medio de pago utilizado
Max 25
descripcion Alfanumérico Descripción de la transacción
Max 250
url_notificacion_resultado Alfanumérico URL de retorno automático para la transacción
Max 255 (webhook). La información de la respuesta es
enviada a esta URL mediante método POST y
el body del request contendrá un objeto json
con los parámetros.
usuario Json Json conteniendo informacion del usuario que
realizó el pago, contendrá valores siempre que
el comercio halla enviado los parámetros
correspondientes al inicio de la transacción:
Página 30
"nombres" : "",
"email" : "",
"tipo_documento": "",
"documento" : "",
"direccion" : "",
"telefono" : ""
}
La respuesta con el estado de la transacción es transmitida al comercio de manera

automática a la URL de notificacion de resultado informada para la transacción, esta
respuesta es intentada por Pagueatiempo.com en 3 ocasiones:
En el primer intento si NO se obtiene respuesta del comercio (timeout) o si el código

de respuesta del comercio es diferente de 200 se reintenta:
Segundo Reintento 3 segundos después del primer intento

Tercer Reintento 6 segundos después del segundo intento
Si después de los tres reintentos NO se obtiene el código 200 en la respuesta del

comercio, la transmisión finaliza.
Igualmente la transmisión se entiende exitosa si en cualquiera de los tres intentos

se obtiene el código 200.
7.1.1. Información Referente al Hash de la Transacción

El hash de la transacción es un dato único para cada transacción y permite verificar
que la data transmitida desde pagueatiempo.com NO ha sido modificada antes de
ser recibida por el comercio (Integridad de la Información).
Por lo anterior, cuando el comercio recibe la respuesta de una solicitud de

procesamiento de pago, debe realizar el cálculo del hash conforme al estándar
indicado, para compararlo con el hash recibido de modo tal que se pueda verificar
si son iguales o diferentes.
7.1.2. Cálculo de Hash:

El hash es calculado mediante el método HMAC (Soportado para todos los
lenguajes de programación) con algoritmo de encriptación SHA256, el cual se
encarga de cifrar una cadena de información mediante una llave criptográfica
secreta (única para cada comercio).
En los encabezados (headers) del request enviado en el webhook (url de

notificación de resultado), se incluye el header ‘X-pat-signature’ el cual contiene el
Página 31
hash del request, este hash es calculado teniendo en cuenta que la cadena a cifrar
es precisamente el request de la petición, el cual es un objeto json (body del
request).
Una vez el hash es calculado por el comercio deberá compararlo contra el hash
retornado por pagueatiempo.com, dicha comparación derivará en dos posibles
opciones:
1. Los hash son iguales, en cuyo caso la transacción es válida y puede ser
procesada por el comercio.
2. Los hash son diferentes, lo que implica que la data transmitida por
pagueatiempo.com fue modificada en algún punto antes de ser recibida
por el comercio y dicha data NO puede ser utilizada por el comercio. En
este caso se sugiere que el comercio consulte la transacción haciendo
uso del endpoint de consulta de transacciones en efectivo por numero de
transacción de la presente documentación y que utilice como válidos los
valores retornados por dicha consulta.
Documentación Relacionada:
https://es.wikipedia.org/wiki/HMAC
Observaciones:
● Adicionalmente a la integración del cálculo del hash, es muy

importante que la URL de notificacion de resultado opere sobre
HTTPS.
● Si su comercio no cuenta con la llave criptográfica para el cálculo del
hash, debe solicitarla a pagueatiempo.com
Con el retorno de la información finaliza el ciclo de vida de una solicitud de

procesamiento de pago en efectivo.
7.2. CONSULTA DE TRANSACCIONES EN EFECTIVO POR NÚMERO DE

TRANSACCIÓN
Permite consultar la información correspondiente a transacciones en efectivo que
previamente han sido enviadas para su procesamiento.
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/consultar-transaccion-efectivo
Método HTTP
POST
Página 32
API Rate Limit
Máximo 12 consultas por hora por comercio
Observación: La tasa límite de de consultas obedece a que pagueatiempo.com siempre

comunica el resultado de las transacciones a través del parámetro
url_notificacion_resultado
Headers
nit_comercio NIT del Comercio o documento de identidad con el que se registró en
pagueatiempo.com, NO debe incluir el dígito de verificación, ni
numero_orden 123456 (Identificador único de la transacción)
idtr_pagueatiempo 654321 (Identificador de la orden en pagueatiempo – no obligatorio)
Tipo de Respuesta
Objeto JSON

401 No autorizado
404 No existe
Ejemplo Request
curl --location --request POST 'https://{url_ambiente_pagueatiempo}/api/v2/consultar-transaccion-efectivo' \
--header 'Content-Type: application/application-json' \
--form 'numero_orden =123456' \
--form 'idtr_pagueatiempo=654321'
Ejemplo de Respuesta Exitosa – Transacción encontrada (Código HTTP 200)

En este caso el objeto Json de respuesta contendrá los parámetros relacionados en
los Parámetros Retornados
{
"data": {
"comercio": "",
Página 33
"fecha_hora_respuesta": "",
"numero_orden": "",
"moneda": "",
"valor": "",
"iva": "",
"autorizacion": "",
"mensaje_autorizacion": "",
"metodo_pago": "",
"medio_pago_efectivo": "",
"descripcion": "",
"usuario": {}
}
}

{
"errors": [
]
}
Ejemplo de Respuesta No Existe (Código HTTP 404)

{
"message": "Error en Consulta",
"errors": [
"La transacción XXXXXX que intenta consultar no existe."
]
}
7.3. CONSULTA DE TRANSACCIONES EN EFECTIVO POR PERIODO DE

TIEMPO
Permite consultar, en un rango de fechas, la información correspondiente a
transacciones en efectivo que previamente han sido enviadas para su
procesamiento.
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/consulta-transacciones-efectivo
Método HTTP
POST
Página 34
API Rate Limit
Máximo 1 consulta por hora por comercio
Rango máximo de consulta un (1) mes calendario
Headers
nit_comercio NIT del Comercio o documento de identidad con el que se registro
clt_start_date 2019-05-01 (Fecha en formato YYYY-MM-DD)
clt_end_date 2019-05-31 (Fecha en formato YYYY-MM-DD)
Tipo de Respuesta
Objeto JSON

401 No autorizado
404 No se encontraron transacciones
En la respuesta exitosa se retornará una colección de objetos Json (uno por cada
transacción encontrada), en donde cada objeto Json contendrá los parámetros
relacionados en los Parámetros Retornados
Ejemplo Request
curl --location --request POST 'https://{url_ambiente_pagueatiempo}/api/v2/consulta-transacciones-efectivo' \
--form 'clt_start_date=2019-09-01' \
--form 'clt_end_date=2019-09-30'

{
"data": [
{
Página 35
"comercio": "",
"numero_orden": "",
"moneda": "",
"valor": "",
"iva": "",
"autorizacion": "",
"metodo_pago": "",
"descripcion": "",
"usuario": {}
},
{
"comercio": "",
"numero_orden": "",
"moneda": "",
"valor": "",
"iva": "",
"autorizacion": "",
"metodo_pago": "",
"descripcion": "",
"usuario": {}
}
]
}

{
"errors": [
]
}
Ejemplo de Respuesta Sin Transacciones (Código HTTP 404)
Página 36
{
"data":[]
}
8. LINKS DE PAGOS
8.1. CREACIÓN DE UN LINK DE PAGO

Esta funcionalidad de la API le permitirá crear links de pagos, los cuales podrá
compartir por redes sociales, correo, aplicaciones de mensajería, etc.
Cada link de pago corresponderá a una única transacción en Pagueatiempo.com

y pueden ser utilizados por una única vez, esto quiere decir que, una vez un link de
pagos inicie su procesamiento en la pasarela, NO podrá volver a ser utilizado y se
deberá generar uno nuevo si se requiere volver a realizar el proceso.
Los links de pagos generados por un comercio pueden ser administrados (crear,
modificar, activar/inactivar) a través del panel de control del comercio en
pagueatiempo.com, este método le facilita al comercio el proceso de
automatización en la creación de los mismos.
Los links de pagos generados se crearán haciendo uso de la url https://patco.link la

cual corresponde al servicio de link de pagos de Pagueatiempo.com
Endpoint
https://{url_ambiente_pagueatiempo}/api/v2/sistema/transacciones/links-de-
pagos/crear
Método HTTP
POST
Parámetros Requeridos (Query Params)

cli_identificacion Numérico NIT del Comercio o documento Si
Max 20 de identidad con el que se
registro en pagueatiempo.com,
NO debe incluir el dígito de
verificación, ni separadores de
miles o decimales
clp_concepto Alfanumérico Concepto de pago SI
Max 100
clp_descripcion Alfanumérico Descripción relacionada con el SI
Max 255 pago
clp_factura_orden Numérico Número de factura o de orden, SI
Max 9 dato con el cual el comercio
puede identificar el pago
cuando es realizado
Página 37
clp_moneda_id Alfanumérico Código de moneda según SI
Max 3 estándar ISO-4217
correspondiente a la moneda
de Colombia, único valor
válido: COP
clp_valor Decimal 15.2 Valor total a pagar o de SI
Max 15 enteros con compra. El valor debe ir sin
decimales. Este valor debe
incluir el valor del IVA
clp_iva_porcentaje Decimal 3.2 Procentaje correspondiente al SI
Max 3 enteros con 2 IVA. El valor debe ir sin
decimales separadores de miles y usar
decimales, ej 19.00.
Si la transacción NO tiene IVA

se debe enviar el valor 0.00
clp_iva_valor Decimal 15.2 Valor del IVA relativo al valor a SI
Max 15 enteros con pagar. El valor debe ir sin
decimales
Si la transacción NO tiene IVA

se debe enviar el valor 0.00
Headers
Authorization: Bearer token_autenticacion
Tipo de Respuesta
Objeto JSON

201 Autenticación exitosa
401 Autenticación no exitosa
409 Errores de validación
Ejemplo Request
curl --location --request POST \
'https://{url_ambiente_pagueatiempo}/api/v2/sistema/transacciones/links-de-pagos/crear' \
--form 'cli_identificacion=900123456' \
Página 38
--form 'clp_concepto=Link de pago de prueba' \
--form 'clp_descripcion=Generación de un link de pago de prueba' \
--form 'clp_factura_orden=123456' \
--form 'clp_moneda_id=COP' \
--form 'clp_valor=119000.00' \
--form 'clp_iva_porcentaje=19.00' \
--form 'clp_iva_valor=19000.00'

{
"message":" Link de pago creado",
"link_generado":"https://patco.link/35a913298@c798fed105f923a5bfa106"
}

{
"errors": [
"No fue posible autenticar al usuario"
]
}

{
"message": "Error en la Creación del Link de Pago",
"errors": [
"Ya existe un link de pago para el concepto, valor y comercio"
]
}
8.2. RESPUESTA AL PROCESAMIENTO DE UN LINK DE PAGOS

Cuando un adquirente (comprador) hace uso del link de pagos, dicha persona podrá
realizar el pago correspondiente haciendo uso de los métodos de pagos que se
encuentren configurados para el comercio:
• Tarjeta de Crédito
• PSE
• Efectivo
La URL de notificación de resultado que utilizará el proceso será la URL de retorno

automático configurada para el comercio en Pagueatiempo.com y los parámetros
de respuesta corresponderán con el método de pago utilizado (referirse a la sección
correspondiente en el presente documento).
Página 39
ANEXO 1 – Códigos de Entidades Financieras en Colombia
Página 40
ENTIDAD CODIGO ENTIDAD

BANCO DE BOGOTA 1001
BANCO POPULAR 1002
ITAU antes Corpbanca 1006
BANCOLOMBIA 1007
CITIBANK 1009
BANCO GNB SUDAMERIS 1012
BBVA COLOMBIA 1013
ITAU 1014
SCOTIABANK COLPATRIA S.A 1019
BANCO DE OCCIDENTE 1023
BANCOLDEX S.A. 1031
BANCO CAJA SOCIAL BCSC SA 1032
BANCO AGRARIO 1040
BANCO MUNDO MUJER 1047
BANCO DAVIVIENDA SA 1051
BANCO AV VILLAS 1052
BANCO W S.A. 1053
BANCO PROCREDIT COLOMBIA 1058
BANCAMIA S.A. 1059
BANCO PICHINCHA 1060
BANCOOMEVA 1061
BANCO FALABELLA S.A. 1062
BANCO FINANDINA S.A. 1063
BANCO MULTIBANK S.A. 1064
BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A 1065
BANCO COOPERATIVO COOPCENTRAL 1066
BANCO COMPARTIR S.A 1067
BANCO SERFINANZA S.A 1069
FINANCIERA JURISCOOP S.A. COMPAÑIA DE
1121
FINANCIAMIENTO
COOPERATIVA FINANCIERA DE ANTIOQUIA 1283
COOTRAFA COOPERATIVA FINANCIERA 1289
CONFIAR COOPERATIVA FINANCIERA 1292
COLTEFINANCIERA S.A 1370
NEQUI 1507
DAVIPLATA 1551
Página 41
ANEXO 2 – Códigos de Respuesta para Pagos en Efectivo
Página 42
CÓDIGO DESCRIPCIÓN
0000 Aprobada
0001 El id de Cliente no es válido
0002 El código no es válido
0003 El password indicado no es válido
0004 Aliado no registrado en Pagueatiempo
0005 Aliado no autorizado
0006 Password incorrecto
0007 La Referencia no esta registrada o no es válida
0008 Cliente inactivo
0009 Error en procesamiento:
0010 ID de transacción no valido
0011 ID de transacción ya existe
0012 Imposible completar el registro
0013 ID de transacción no existe
0014 La transacción ya fue anulada
0015 La transacción no puede ser anulada. Comuníquese con atención al cliente de
Pagueatiempo
0016 Los datos del cliente no corresponden con nuestros registros. Comuníquese
Pagueatiempo
0017 El merchantID no es válido
0018 Comercio no registrado en Pagueatiempo
0019 Comercio no autorizado
0020 La orden de compra ya se encuentra registrada
0021 El monto no es válido
0022 Código del país no es válido
0023 La moneda no es válida
0024 El tiempo máximo de la orden debe estar entre 30m y 30d
0025 El checksum no es válido
0026 No puede crear una orden de compra en la moneda especificada para el país
indicado
0027 El método de pago no es valido
0028 Ha ocurrido un error en la transacción, espere unos minutos e intente de nuevo
0029 La descripción no puede estar vacía
0030 Ocurrió un error al registrar la orden. Intente de nuevo en unos minutos. Si el
persiste el error comuníquese con Pagueatiempo
Página 43
CÓDIGO DESCRIPCIÓN
0031 La fecha de expiración no es valida. Debe indicar DDMMAAAA
0032 La fecha de expiración debe ser mayor a la fecha de hoy
0033 La fecha de expiración debe ser mayor a 24 horas
0034 La cantidad de pagos debe ser mayor a 1
0035 La frecuencia de pagos debe ser mayor a un día
0036 Imposible registrar la compra con los datos proporcionados. Comuniquese con
Pagueatiempo
0037 Merchant no autorizado
0038 El cliente ya se encuentra vinculado
0039 Las cuentas no están vinculadas
0040 Los datos no coinciden
0041 La orden no se encuentra registrada o se encuentra APROBADA, VENCIDA o
CANCELADA
0042 Ya existe una orden con el mismo PO_ID
0043 Ya existe una orden activa con la misma referencia de pago
0044 El tiempo de vida no es valido. Debe tener formato NNNX, donde NNN es un
número entero y X una letra (m, h o d)
0045 Debe indicar una referencia de pago
0046 La orden indicada no pertenece al comercio indicado
0047 Debe indicar el email
0050 Operación no definida
0051 Falta o no es valido el lifetime
0052 Falta o no es valido el lifetime
0053 Tiene una operación en proceso de pago
0060 Ha superado el limite de transacciones permitidas, por favor contáctenos para
completar su proceso de inscripción
0061 El código de comercio no existe
0062 Debe indicar true o false en confirm
0063 La fecha de vencimiento no es valida
9996 Fallida
9997 No Definido
9998 Vencida
9999 Pendiente
Página 44
ANEXO 3 – Tarjetas de Crédito de Prueba
Página 45
NUMERO DE TARJETA CVC VENCE Respuesta

4444444444446666 123 2024/12 Rechazada
Operación rechazada. Verifique los datos
y el saldo disponible de la cuenta.
4111111111111111 123 2024/12 Aprobada
4563960122001999 347 2024/12 Aprobada
5555555555555557 123 2024/12 Aprobada
5555555555555599 123 2024/12 Aprobada
6390020000000003 123 2024/12 Aprobada
4444444444444422 123 2024/12 Rechazada
Pago rechazado. Por favor, contáctese con
su banco.
4444444411111111 123 2024/12 Rechazada
su banco.
4444444499999999 123 2024/12 Rechazada
el comerciante.
Página 46
ANEXO 4 – Ejemplos Cálculo Hash Transacción
Página 47
Cuando Pagueatiempo va a transmitir el resultado de una transacción a un

comercio, lo hace a través de dos vías:
1. url_retorno_comercio, es la URL que se utiliza cuando el usuario pagador da

clic en el botón ‘Retornar al Comercio’, los parámetros de respuesta son retornados
mediante método POST (básicamente es una redirección de URL del navegador
mediante un formulario oculto hacia la url_retorno_comercio) y dentro de los
parámetros retornados se incluye uno llamado hash_transaccion, y como se indica
en esta documentación, hash_transaccion solo es enviado como parámetro
mediante url_retorno_comercio
En este caso se debe calcular el hash concatenando los siguientes parámetros:
• identificacion_comercio (numérico, sin puntos, ni guion, ni dígito de

verificación)
• fecha_hora_final
• numero_orden
• moneda
• valor
• autorización
• error_code
• error_message
• estado
• ip
Ejemplo del cálculo haciendo uso de PHP:
<?php
$coincide = 'NO';
if(isset($_POST['hash_transaccion'])) {
$hash = hash_hmac(
'sha256',
'900280984' . // Nit del comercio sin dígito de verificación
$_POST['fecha_hora_final'] .
$_POST['numero_orden'] .
$_POST['moneda'] .
$_POST['valor'] .
$_POST['autorizacion'] .
$_POST['error_code'] .
$_POST['error_message'] .
$_POST['estado'] .
$_POST['ip'],
'bdULe11sJQ01zOh1E6Xj9ERPWSPo3BhCgz61nzyprVAblVIbWolKir4+Xh+RkR6f6Ut6wf7afEU8gFqHXxyqKA=='
// Hash Key del comercio
);
if ($_POST['hash_transaccion'] == $hash) { $coincide = 'SI'; }
}
Página 48
2. url_notificacion_resultado, es la URL que se utiliza como webhook o endpoint
del comercio para enviarle un request o petición automática mediante método
POST, y en los headers del request se incluye el header X-PAT-SIGNATURE el
cual contiene el hash de la transacción (tener en cuenta que el hash no se envía
como parámetro sino como header). En este caso el hash debe ser calculado
teniendo en cuenta que los parámetros retornados de la transacción son un json
que componen el body de la petición, y se debe tener en cuenta ese json como
string para el cálculo.
Ejemplo del contenido del body del request:

{"comercio":"Comercio de Prueba","identificacion_comercio":"900XXXXXX-
7","codigo_unico":"012345678","terminal":"00012345","fecha_hora_inicio":"2022-08-22
13:15:57","fecha_hora_final":"2022-08-22
13:16:22","tipo_pago":"TC","numero_orden":"123456789","idtr_pagueatiempo":"1","moneda":"COP","valor":"50
0.00","iva":"0.00","autorizacion":null,"error_code":6,"error_message":"Pago rechazado. Por favor, contáctese
con su
banco.","estado":"Rechazada","detalle_pse":[],"detalle_tc":[{"bankInfo":{"bankCountryCode":"UNKNOWN","ban
kCountryName":"&ltUnknown&gt"},"cardAuthInfo":{"maskedPan":"411111**1111","expiration":"202412","cardh
olderName":"PEDRO
PEREZ","paymentSystem":"VISA","pan":"411111**1111"}}],"numero_tarjeta":"411111**1111","numero_cuotas"
:1,"ip":"123.123.123.123","json_params":[{"installments":1,"IVA.amount":"000","demo":"Hola
mundo"}],"url_retorno_comercio":"https://comercio.com/url-retorno-
comercio","url_notificacion_resultado":"https://comercio.com/url-notificacion-
resultado","usuario":{"nombres":"Pedro
Perez","email":"pperez@example.com","tipo_documento":"CC","documento":"10123456789","direccion":"Calle
12 # 34-56","telefono":"3002300400"}}
Ejemplo del cálculo con PHP:

<?php
$coincide = 'NO';
$body = file_get_contents("php://input");
$hash = hash_hmac(
'sha256',
$body,
'bdULe11sJQ01zOh1E6Xj9ERPWSPo3BhCgz61nzyprVAblVIbWolKir4+Xh+RkR6f6Ut6wf7afEU8gFqHXxyqKA=='
// Hash Key del comercio
);
$bodyHash = '';
foreach($_SERVER as $index => $value) {
if($index == 'HTTP_X_PAT_SIGNATURE')
$bodyHash = $value;
}
if ($bodyHash == $hash) { $coincide = 'SI'; }
Página 49
Página 50
ANEXO 5 – Material de Apoyo para Integraciones
Página 51
El siguiente material puede ser descargado desde las url indicadas y sirve como
material de apoyo técnico a los comercios en su labor de integración:
Modelo Respuesta Transacción Pendiente

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/rpta_transaccion_pendiente.json
Modelo Respuesta Transacción PSE Aprobada

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/rpta_pse_aprobada.json
Modelo Respuesta Transacción PSE Fallida

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/rpta_pse_fallida.json
Modelo Respuesta Transacción Tarjeta de Crédito Aprobada

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/rpta_tc_aprobada.json
Modelo Respuesta Transacción Tarjeta de Crédito Rechazada

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/rpta_tc_rechazada.json
Modelo HTML para Solicitud de Procesamiento de Pago TC - PSE

https://pagueatiempo.com/material_apoyo_integraciones/API-
V2/ejemplo_html_solicitud_pago.html.txt
Modelo HTML Uso Url de Retono al Comercio

https://pagueatiempo.com/material_apoyo_integraciones/API-V2/ejemplo_html_url_retorno.html.txt
Colección de Postman – Modelo de Uso Url Notificación Resultado

https://pagueatiempo.com/material_apoyo_integraciones/API-
V2/postman_url_notificacion_resultado.json
Página 52

Manual Integracion Pagueatiempo V2.2.1

Cargado por

Información del documento

Descripción original:

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Manual Integracion Pagueatiempo V2.2.1

Cargado por

Copyright:

Formatos disponibles

MANUAL DE INTEGRACIÓN

PAGOS CON TARJETA DE CRÉDITO, PSE, EFECTIVO Y LINKS DE PAGO

API RESTful – Versión 2.2.1

DATOS DE LA VERSIÓN 2.2.1

DATOS DE LA VERSIÓN 2.2.0

DATOS DE LA VERSIÓN 2.1.3

DATOS DE LA VERSIÓN 2.1.2

DATOS DE LA VERSIÓN 2.1.1

DATOS DE LA VERSIÓN 2.1.0

DATOS DE LA VERSIÓN 2.0.0

Importante: Los comercios que a la fecha de publicación de la presente versión se encontraban

DATOS DE LA VERSIÓN 1.0.11

DATOS DE LA VERSIÓN 1.0.10

DATOS DE LA VERSIÓN 1.0.9

DATOS DE LA VERSIÓN 1.0.8

DATOS DE LA VERSIÓN 1.0.7

DATOS DE LA VERSIÓN 1.0.6

DATOS DE LA VERSIÓN 1.0.5

DATOS DE LA VERSIÓN 1.0.4 (Actualización de Seguridad)

DATOS DE LA VERSIÓN 1.0.3

DATOS DE LA VERSIÓN 1.0.2

Cuando un comercio es habilitado en Pagueatiempo, solamente tendrá acceso al

El comercio deberá tener registro, como mínimo, de las siguientes transacciones:

Observación: Es importante tener en cuenta que en el servidor QA todas las

Igualmente deberá informar la URL en donde se encuentra el formulario de pago

Una vez realizadas las verificaciones, se procederá con la configuración y activación

Nota 1: El ambiente QA al momento de generación de esta versión del manual de integración,

Nota 2: El ambiente QA solamente es funcional para integraciones de comercios con la versión 2 o

El esquema de autenticación HTTP utilizado se denomina BEARER TOKEN y se

Al recibir la respuesta del proceso de autenticación, adicional al token, el comercio

Códigos HTTP de Respuesta

Ejemplo de Respuesta Exitosa (Código HTTP 200)

Ejemplo de Respuesta No Exitosa (Código HTTP 401)

4. CAMBIO DE CLAVE DE AUTENTICACIÓN DEL COMERCIO

Características de composición de la clave de autenticación:

Códigos HTTP de Respuesta

Ejemplo de Respuesta Exitosa (Código HTTP 200)

Ejemplo de Respuesta No Autorizado (Código HTTP 401)

Ejemplo de Respuesta con Fallo en Autenticación (Código HTTP 401)

5. TERMINOS Y CONDICIONES, POLÍTICA DE PRIVACIDAD Y DE

5.1. IMPLEMENTACIÓN OBLIGATORIA POR PARTE DEL COMERCIO

Dicha casilla debe contener el siguiente mensaje: “Acepto los términos y

Acepto los términos y condiciones de uso y la política de privacidad y de

Esta casilla de verificación deberá cumplir dos funciones principales:

6.1. SOLICITUDES DE PROCESAMIENTO DE PAGOS CON TARJETA DE

La redirección hacia esta URL se debe realizar desde la acción de procesamiento

Observación: Este proceso NO puede ser realizado en background, se recomienda NO

Observación: El comercio debe redirigir su proceso de pago a la url de procesamiento

Ejemplo de definición del formulario de pago en HTML:

documento_usuario Alfanumérico Número de documento del Obligatorio si

Debe estar compuesto para

Cuando se inicia una solicitud de procesamiento de pago con TC o PSE, el estado

Una vez se surte todo el ciclo de procesamiento de la solicitud de pago,

• De manera automática a la URL de notificación de resultado, esta respuesta

Segundo Reintento 3 segundos después del primer intento

Si después de los tres reintentos NO se obtiene el código 200 en la respuesta

Igualmente la transmisión se entiende exitosa si en cualquiera de los tres

• De manera manual cuando el usuario pagador hace click en el botón ‘Volver

El retorno de la respuesta a la solicitud de procesamiento es realizado mediante el

Método Retorno HTTP

Parámetros Retornados en la Respuesta

TC para pagos con Tarjeta de Crédito