Documentación de Interfaces

API 1.0

Histórico de versiones
Versión Fecha Autor Descripción
1.00 14/02/2017 Carlo Macchi Primera versión de la documentación.
Wilson Cruz
1.01 05/03/2017 Carlo Macchi Versión BETA liberada.
Wilson Cruz
1.02 28/08/2017 Wilson Cruz Agregados y correcciones.
1.03 04/09/2017 Carlo Macchi 1ª Versión Release.
1.04 09/10/2017 Wilson Cruz Correcciones y nuevos campos en el objeto
Purchase.
1.05 11/12/2017 Carlo Macchi Detalle de registro de Customers y tarjetas
Wilson Cruz asociadas (CommerceToken).
Detalle de errores.
1.06 19/01/2018 Wilson Cruz Nuevo objeto CommerceAction que puede ser
devuelto como parte del Purchase.
Nuevo objeto Notification y especificación del
servicio WebHook que lo procesa.
1.07 10/02/2018 Wilson Cruz Corrección de detalles.
1.08 29/05/2018 Carlo Macchi Se agregan anexos con información adicional
Valeria Gulovin sobre adquirentes en Uruguay.
Se agregan campos a Customer (datos de
documento).
Corrección de algunos detalles.

1.09 09/07/2018 Wilson Cruz Nuevos campos en entidades y correcciones

varias.

SiemprePago © 2019 Página 1 de 76

 Cambios en el proceso de captura de datos de
tarjeta para generación de CommerceToken.
1.10 6/08/2018 Carlo Macchi Se agregan ejemplos de respuesta de
Valeria Gulovin transacciones.
1.11 30/11/2018 Wilson Cruz Correcciones de detalles.
Valeria Gulovin Se agrega detalle en tabla de Tipo de Medios
de Pago y AddressType.
Se agrega detalle de StepStatus.
Se agrega sección de Nomenclatura de
Operaciones y se especifica en cada operación
la ubicación (URL o Body) de los parámetros de
entrada.
Se agrega detalle del flujo de solicitud de
Código de Verificación (CVV, CVV2, CVC, etc.)
para medios de pago que lo requieran en
todas las transacciones.
1.12 05/15/2018 Gonzalo Pigni Se agrega descripción y ejemplo de invocación
de formulario de captura para bancos y
medios de pago específicos.
1.13 21/01/2019 Wilson Cruz Nuevas operaciones para la modificación y
eliminación de Perfiles de Pago en Customers
registrados.
Customización de Formulario de Checkout.
1.14 16/05/2019 Wilson Cruz Nueva propiedad para ocultar el email en el
formulario de captura.
Se agrega parámetro en el evento “closed” del
formulario de captura para informar el motivo
de cierre del mismo.
Se agrega el método GetCustomToken en la
librería PWCheckout para facilitar la obtención
de un Token de pago para redes físicas.
1.15 28/06/2019 Wilson Cruz Nuevo estado de Transacción para flujos de
Gonzalo Pigni Redes Físicas.
Se agregan medios de pago Abitab, RedPagos
y MasterCard Prepago.
Se agrega Prex en listado de Emisores de
tarjetas.
1.16 12/03/2019 Alan Gonzalez Detalles sobre la implementación del
formulario de captura embebido

SiemprePago © 2019 Página 2 de 76

Contenido
Introducción .................................................................................................................................................. 7
PCI-DSS ...................................................................................................................................................... 7
API SiemprePago ....................................................................................................................................... 7
Conceptos ..................................................................................................................................................... 7
Ambientes ................................................................................................................................................. 7
Versionado ................................................................................................................................................ 8
Comercios y cuentas ................................................................................................................................. 8
Autenticación ............................................................................................................................................ 8
Claves de Cuentas del Comercio ........................................................................................................... 8
PublicAccountKey.................................................................................................................................. 9
PrivateAccountKey ................................................................................................................................ 9
Tokenización ............................................................................................................................................. 9
¿Cuál es la función del token? .............................................................................................................. 9
Formato de Respuesta .............................................................................................................................. 9
Identificador único (UniqueID) ............................................................................................................... 10
Formulario de Checkout ............................................................................................................................. 10
Descripción.............................................................................................................................................. 10
Importación de la Librería Javascript ...................................................................................................... 10
Métodos .................................................................................................................................................. 11
SetProperties....................................................................................................................................... 11
SetStyle ............................................................................................................................................... 13
Bind ..................................................................................................................................................... 14
Unbind................................................................................................................................................. 15
Eventos.................................................................................................................................................... 15
Invocación del formulario ....................................................................................................................... 15
Invocación del formulario con Filtros de Validación............................................................................... 17
Formulario de Checkout embebido ............................................................................................................ 18
Descripción.............................................................................................................................................. 18
Importación de la Librería Javascript ...................................................................................................... 18
Método GetCustomToken .......................................................................................................................... 19
Flujo de una compra ................................................................................................................................... 20
Usuario anónimo..................................................................................................................................... 20

SiemprePago © 2019 Página 3 de 76

 Captura de datos ................................................................................................................................. 20
Librería Javascript ............................................................................................................................... 20
Compra básica ..................................................................................................................................... 20
Diagrama de Secuencia del Flujo de Pagos ......................................................................................... 21
Usuario registrado .................................................................................................................................. 21
Crear Customer ................................................................................................................................... 21
Captura de datos de Medios de Pago asociados al Customer ............................................................ 23
Compra básica ..................................................................................................................................... 26
Compras recurrentes en un solo click ................................................................................................. 27
Flujo de Solicitud de Código de Verificación ....................................................................................... 27
Recursos ...................................................................................................................................................... 33
Objetos y operaciones ............................................................................................................................ 33
Nomenclatura de Objetos ................................................................................................................... 33
Nomenclatura de Operaciones ........................................................................................................... 33
Directivas para las operaciones .......................................................................................................... 34
Purchase.................................................................................................................................................. 35
Objeto Purchase .................................................................................................................................. 35
Crear una nueva compra..................................................................................................................... 38
Obtener información de una compra creada ..................................................................................... 38
Confirmar una compra pre-autorizada ............................................................................................... 39
Anular una compra pre-autorizada ..................................................................................................... 40
Devolver una compra creada y confirmada ........................................................................................ 40
Lista de compras ................................................................................................................................. 41
Ejemplos de Respuestas...................................................................................................................... 43
Customer................................................................................................................................................. 45
Objeto Customer ................................................................................................................................. 45
Crear un nuevo Customer ................................................................................................................... 47
Actualizar un Customer ....................................................................................................................... 48
Obtener datos de un Customer .......................................................................................................... 48
Activar perfil de Pago .......................................................................................................................... 49
Modificar Perfil de Pago ...................................................................................................................... 50
Eliminar Perfil de Pago ........................................................................................................................ 50
Objetos .................................................................................................................................................... 51

SiemprePago © 2019 Página 4 de 76

 Account ............................................................................................................................................... 51
Address ............................................................................................................................................... 52
Commerce ........................................................................................................................................... 52
RefundData ......................................................................................................................................... 53
CountryDataUY (Uruguay) .................................................................................................................. 54
CountryDataDo (Rep. Dominicana) ..................................................................................................... 54
Error .................................................................................................................................................... 55
PaymentProfile.................................................................................................................................... 55
CustomerActivation ............................................................................................................................ 56
Transaction.......................................................................................................................................... 57
TransactionStep .................................................................................................................................. 57
CommerceAction ................................................................................................................................ 58
Notification ......................................................................................................................................... 59
Objetos Javascript ................................................................................................................................... 60
CloseInfo ............................................................................................................................................. 60
TokenInfo ............................................................................................................................................ 61
NotificationInfo ................................................................................................................................... 62
Servicio WebHook de Comercio ................................................................................................................. 62
Especificaciones del servicio WebHook .................................................................................................. 63
Códigos........................................................................................................................................................ 64
Códigos HTTP .......................................................................................................................................... 64
Códigos de error...................................................................................................................................... 64
Tipos de datos ............................................................................................................................................. 70
Básicos..................................................................................................................................................... 70
String ................................................................................................................................................... 70
Numeric............................................................................................................................................... 70
Amount ............................................................................................................................................... 70
TimeStamp .......................................................................................................................................... 70
Date ..................................................................................................................................................... 71
Boolean ............................................................................................................................................... 71
TransactionStatus ............................................................................................................................... 71
StepStatus ........................................................................................................................................... 72
ActionType .......................................................................................................................................... 72

SiemprePago © 2019 Página 5 de 76

 ResourceType ...................................................................................................................................... 73
AddressType........................................................................................................................................ 73
Listas ....................................................................................................................................................... 73
Tablas .......................................................................................................................................................... 74
Medios de pago (PaymentMedia)........................................................................................................... 74
Bancos Emisores ..................................................................................................................................... 74
Tabla de Monedas (ISO-4217)................................................................................................................. 75
Tabla de Países (ISO-3166-1) .................................................................................................................. 75
Tabla de Tipos de documentos ............................................................................................................... 75
Tabla de Tipos de Medios de Pago ......................................................................................................... 76
Anexos......................................................................................................................................................... 76
Anexo 1. Adquirentes de Uruguay .......................................................................................................... 76
Visanet ................................................................................................................................................ 76
FirstData (MasterCard) ....................................................................................................................... 77
Ocacard ............................................................................................................................................... 78
Creditel ................................................................................................................................................ 78
PassCard .............................................................................................................................................. 78
Anexo 2. Invocación al formulario de captura embebido ...................................................................... 78

SiemprePago © 2019 Página 6 de 76

Introducción
Este documento expone las funcionalidades de la API de SiemprePago para la integración segura con
la plataforma. A través de la misma, Ud. le podrá brindar a sus clientes una experiencia de pago
mejorada, pudiendo solicitar los datos de tarjeta “como si estuviera” en su propia página o aplicación
móvil a través de nuestro “Formulario de Checkout”.
También podrá solicitar los datos una única vez y almacenar un “token” asociado a la tarjeta que el
cliente ingresó de forma segura en nuestra plataforma.

PCI-DSS
Nuestra plataforma cuenta con certificación PCI-DSS Nivel 1, la cual nos permite procesar los números
de tarjeta y otros datos sensibles de autenticación del cliente.
A través del “Formulario de Checkout”, especialmente diseñado para poder ser embebido en sus
páginas o aplicaciones móviles, su comercio puede aceptar pagos sin que sus servidores reciban los
datos confidenciales del cliente, dándole seguridad a la operación y facilidad de uso.

API SiemprePago
La API de SiemprePago está implementada a través de operaciones que son expuestas como servicios
REST con intercambio de mensajes en formato JSON (Content-Type: application/json).
Toda llamada a la API deberá ser realizada mediante HTTPS (TLS 1.2) y deberá controlar el código HTTP
de respuesta de cada operación, que determinará el estado del procesamiento de la transacción
enviada.

Conceptos
Ambientes
La plataforma de SiemprePago cuenta con dos ambientes separados:

Testing – Ambiente para realizar tareas de testing, en este ambiente las transacciones nunca alcanzan
los sistemas reales de los proveedores de medios de pago. Es una forma segura de realizar tareas de
prueba.
URL base del testing: https://testapi.siemprepago.com

Producción – Es el ambiente definitivo donde se realizan las transacciones reales contra los medios
de pago.
URL base de producción: https://api.siemprepago.com

NOTA: A lo largo del documento, cuando se hace referencia a las URL donde se encuentran expuestos
los servicios, se menciona como {ambiente_api}/…, lo cual debe ser sustituido por la URL
correspondiente al ambiente en el que se está trabajando.

SiemprePago © 2019 Página 7 de 76

Versionado
Las versiones que se vayan desarrollando de la aplicación, van a estar indicadas dentro de la URL de
la API. Actualmente existe la versión 1 por lo que va a ser así:
{ambiente_api}/v1/api

Ejemplo de la API de compra en producción:

https://api.siemprepago.com/v1/api/purchase

Comercios y cuentas
Todo comercio que contrata la plataforma se le asigna un identificador de comercio y una cuenta
para acceder a la API de integración. Luego, el comercio puede crear múltiples cuentas para poder
operar con la plataforma.
Estas múltiples cuentas pueden ser útiles para segmentar la operativa del comercio.

Por ejemplo: se puede tener una cuenta para las transacciones que provengan del sitio web y otra
para las originadas en una App móvil.
Otro ejemplo puede ser, que se quiera segmentar la operativa de acuerdo a distintas sucursales o
líneas de negocios que el comercio posea. Inclusive puede segmentar que para algunas líneas de
negocios (cuentas) hay disponibles ciertos medios de pago, y para otras cuentas, otros medios de
pago diferentes.

A través de las cuentas, también es posible diferenciar los datos de autenticación contra el medio de
pago. Por ejemplo: para una tarjeta de crédito que normalmente se debe configurar el código de
comercio asignado por la misma, este código de comercio puede variar entre una cuenta y otra.

A efectos de liquidación y facturación de servicios, SiemprePago tomará en cuenta el total de las

transacciones efectuadas por todas las cuentas de un comercio.

Autenticación

Claves de Cuentas del Comercio

Todo comercio integrado con nuestra plataforma recibirá un par de claves por cada cuenta asociada
(PrivateAccountKey y PublicAccountKey).
Cada una de estas claves identifica al comercio en nuestro sistema en cada llamada que se hace a la
API, de forma de poder establecer si está autorizado para operar y cuáles son las condiciones de dicha
integración (ej. medios de pago habilitados).

Las claves serán utilizadas como forma de autenticación con la API utilizando un método similar al
HTTP Basic Authentication. Es decir que cada llamada a cualquiera de las operaciones expuestas
deberá ser realizada utilizando la API Key correspondiente como clave de Basic Authentication (sin
necesidad de concatenar usuario y password ni codificar, se utiliza directamente la clave
correspondiente).

SiemprePago © 2019 Página 8 de 76

 Ejemplo:
Header Name Header Value
Authorization Basic T9yaPob6Xpda5pzDxqhJyZT95Lgw7i4Y0FJ5zBAKWH5K5MHTVnxMxw__

NOTA: El valor del header Authorization es la concatenación del literal “Basic” y la clave privada
(PrivateAccountKey) con un carácter de espacio entre ambos valores. No es necesario realizar ninguna
codificación extra de dicho valor (no se requiere la codificación Base64 utilizada en Basic
Authentication).

PublicAccountKey
La clave pública de comercio se adjuntará en cada request público (realizado desde la interfaz web)
para las operaciones de consulta o solicitud de captura de datos.
Además esta clave es utilizada al invocar la librería Javascript PWCheckout.

PrivateAccountKey
La clave privada de comercio se adjuntará en cada request privado (server to server) donde estarán
disponibles las operaciones críticas, como iniciar o confirmar una transacción, acceder a información
de transacciones del comercio, crear o eliminar planes de suscripción, etc.

IMPORTANTE: Esta clave privada no debe ser compartida ni expuesta públicamente en ningún
momento para no comprometer la seguridad de la integración. Es responsabilidad del comercio
mantenerla segura.

Tokenización
La Tokenización, cuando se aplica la seguridad de datos, se refiere al proceso de sustitución de un
elemento de datos sensibles con un equivalente no sensible.
Este elemento no sensible (el “token”) generado a través de este proceso carece de significado o valor,
excepto para la entidad a quien fue entregado.
De esta forma, en caso de un compromiso de seguridad que permita robar estos números, no tienen
valor alguno para quien los roba ya que no podrá usarlos para su beneficio propio.

¿Cuál es la función del token?

El token es una referencia (o identificador) que se asigna a la tarjeta de crédito capturada por el
sistema de SiemprePago. El token es único para una misma dupla “comercio/tarjeta”. Es decir que si
un cliente registra su número de tarjeta en dos comercios diferentes, cada comercio recibirá un token
distinto, haciendo imposible que un comercio A opere con los tokens de otro comercio B.

Formato de Respuesta
Cualquier llamada a una operación de la API, va a retornar:
● Un código HTTP que define el estado de la respuesta.
● El objeto de respuesta al request.

SiemprePago © 2019 Página 9 de 76

 ● Una lista de errores que contiene todos los errores que pueden haber ocurrido. En caso de no
haber errores la lista está vacía.

Identificador único (UniqueID)

Es importante que en algunos de los servicios implementados en la API, se evite la duplicación de
transacciones. Por ejemplo cuando se hacen las operaciones de compra.
Si ocurre una falla de conexión de red en el medio de una transacción de compra, la misma pudo
haber sido aprobada pero el comercio no obtuvo la respuesta final.
Con el identificador único, se puede reintentar la operación con la tranquilidad de que en caso de que
la plataforma ya la haya procesado, va a contestar el resultado que ya fue obtenido del medio de
pago, sin duplicar la transacción.

Formulario de Checkout
Descripción
El formulario de Checkout es un formulario de pago embebido en su propia página, que simplifica y
asegura la captura de datos sensibles para el procesamiento de pagos en línea.
La integración de este formulario en su sitio o “app”, proporcionará a sus usuarios una experiencia de
pago simplificada y responsiva apta para web y aplicaciones móviles.

Importación de la Librería Javascript

Las funcionalidades del formulario de Checkout se encuentran en una librería Javascript, que debe ser
importada en la página web del cliente directamente desde una URL pública de nuestra plataforma.
En la llamada a dicha librería se deberá incluir (como parámetro) la clave pública de la cuenta de
comercio (PublicAccountKey) la cual será utilizada para las llamadas hacia la API REST desde esta
librería.

<script src="{ambiente_api}/v1/Scripts/PWCheckout.js?key={PublicAccountKey}"
type="text/javascript"></script>

NOTA: La librería debe ser importada por el comercio a través de la URL pública dispuesta por
SiemprePago. No deberá ser descargada y usada localmente desde un servidor propio del comercio o
desde una URL de un tercero no autorizado por SiemprePago.
Esto es importante por motivos de seguridad y para mantenerse siempre actualizados con las últimas
modificaciones y correcciones realizadas sobre la misma.

SiemprePago © 2019 Página 10 de 76

Métodos

SetProperties
Este método establece las propiedades visuales (textos e imágenes) a utilizarse en la ventana de
Checkout.
Todas las propiedades son opcionales, excepto la propiedad “form_id”. Por lo que la llamada al
método SetProperties es obligatoria por lo menos para establecer esta propiedad y debe ser invocado
previo a la apertura del formulario de Checkout.

Propiedades:

Propiedad Descripción Presencia

name Nombre que aparece como “Título” del Checkout. Opcional
email Email del cliente que se puede precargar. Opcional
image URL absoluta de la imagen a utilizarse dentro del Checkout Opcional
(formato fijo).
Imágenes aceptadas: jpg, jpeg, png
button_label Texto a mostrarse en el botón de pago (el keyword #monto# es Opcional
sustituido por el monto si este es informado).
description Descripción del pago a realizarse. Opcional
currency Moneda del pago (ver tabla de monedas). Opcional
amount Monto del pago (solo para informar al usuario, el monto real se Opcional
informa server to server en la operación Purchase).
lang Lenguaje de la interfaz. Si no se establece se obtiene de la Opcional
configuración del browser.
form_id Identificador del formulario web donde se manejan los datos de Mandatorio
la compra actual. Este dato es requerido ya que se utilizará para
informar el token generado por la aplicación a partir de la tarjeta
o medio de pago ingresado por el usuario.
checkout_card Si se establece, el checkout pasa directamente a la captura de Opcional
tarjeta.
empty Si esta propiedad se establece en “true” la imagen y el título en Opcional
la ventana del formulario se ocultarán. El valor por defecto es
“false”.
autoSubmit Propiedad que permite establecer el comportamiento de la Opcional
librería PWCheckout una vez que se recibe el Token.

SiemprePago © 2019 Página 11 de 76

 Si se establece en “true”, el formulario será enviado
automáticamente (form submit) al recibir el Token
Si se establece en “false” el formulario no será enviado
automáticamente al servidor.
El valor por defecto es “true”.
close_onclick Esta propiedad establece si el Formulario de Captura de tarjetas Opcional
se cerrará automáticamente cuando el usuario haga click fuera
del área del formulario.
Si es establecida en “true”, el formulario se cerrará al hacer click
fuera del mismo.
Si es establecida en “false”, el formulario no se cerrará
automáticamente y será necesario hacer click en el botón de
cierre para que esto suceda.

El valor por defecto es “true”.

email_edit Establece si la dirección de email puede ser modificada por el Opcional
usuario.
Esto se utiliza cuando se establece la propiedad “email” y no se
desea que el usuario modifique este dato en el Formulario de
Checkout.

El valor por defecto es “true”.

email_hide Establece la visibilidad del campo “Email” en el formulario de Opcional
captura.
Esto se utiliza cuando se establece la propiedad “email” y no se
desea que el usuario vea dicho campo.
Si no se establece la propiedad “email” esta propiedad se ignora
y el campo se muestra igualmente.

El valor por defecto es “false”.

Ejemplo:
<script type="text/javascript">

PWCheckout.SetProperties(
{
"name": "Mi tienda",
"email": "cliente@gmail.com",
"image": "http://mitienda.com/images/logocheckout.png",
"button_label": "Pagar #monto#",
"description": "Checkout de Mi tienda",
"currency": "USD",
"amount": "1843.21",
"lang": "ESP",
"form_id": "commerce_form",
"checkout_card": "1",
"autoSubmit": "true",

SiemprePago © 2019 Página 12 de 76

 "email_edit": "false"
}
);
</script>

SetStyle
Este método establece los colores a utilizarse en la ventana de Checkout.
Todas las propiedades son opcionales por lo que la llamada al método SetStyle es también opcional,
en caso de que no se realice dicha llamada, el formulario de Checkout utilizará los colores
predeterminados.
Este método debe ser invocado previo a la apertura del formulario de Checkout, de forma de que se
establezcan dichas propiedades.

Estilos disponibles:

Propiedad Descripción Predeterminado

backgroundColor Establece el color de fondo de la ventana. FFFFFF
buttonColor Establece el color de fondo del botón de 286090
acciones en la ventana.
buttonHoverColor Establece el color de fondo del botón de 204d74
acciones en la ventana cuando se pasa el
mouse por sobre el mismo.
buttonTextColor Color del texto en el botón de acciones en la FFFFFF
ventana.
buttonTextHoverColor Color del texto en el botón de acciones en la FFFFFF
ventana cuando se pasa el mouse por sobre
el mismo.
inputBackgroundColor Color de fondo de los campos de texto. FFFFFF
inputTextColor Color de texto en los campos de texto. 555555
inputErrorColor Color de borde en los campos de texto FF0000
cuando el mismo contiene un error.
inputAddonBackgroundColor Color de fondo de la iconografía de los EEEEEE
campos de texto.
labelColor Color de texto en las etiquetas y título de la 337AB7
ventana.

Ejemplo:

<script type="text/javascript">

SiemprePago © 2019 Página 13 de 76

 PWCheckout.SetStyle(
{
"backgroundColor": "f2f2f2",
"buttonColor": "555555",
"buttonHoverColor": "777777",
"buttonTextColor": "ffffff",
"buttonTextHoverColor": "ffffff",
"inputBackgroundColor": "ffffff",
"inputTextColor": "767676",
"inputErrorColor": "ff0000",
"inputAddonBackgroundColor": "ffffff",
"labelColor": "494949"
}
);
</script>

NOTA: Los colores deben ser establecidos en formato RGB hexadecimal.

Bind
Este método es utilizado para suscribirse a los distintos eventos que pueden ser disparados desde la
librería PWCheckout.
Este método debe ser invocado previo a la apertura de la ventana del formulario de Checkout, de
forma de poder recibir los distintos eventos que este formulario genera.

Propiedad Descripción Presencia

eventName Nombre del evento al que se quiere suscribir (ver eventos Mandatorio
string más adelante).
callbackName Función javascript que se encargará de procesar el evento Mandatorio
Javascript Function una vez que este sea disparado.

Nota: La función javascript que procesará el evento (en caso de requerirlo) debe ser implementada
por el Comercio.

Ejemplo:

<script type="text/javascript">
function WindowIsOpen(){
console.log(“Checkout Window is Open”);
}

PWCheckout.Bind(“opened”, WindowIsOpen);

</script>

SiemprePago © 2019 Página 14 de 76

 Unbind
Este método es utilizado para eliminar la suscripción a un evento realizada previamente mediante el
método Bind.

Propiedad Descripción Presencia

eventName Nombre del evento cuya suscripción se desea eliminar. Mandatorio
string

Ejemplo:

<script type="text/javascript">

PWCheckout.Unbind(“opened”);

</script>

Eventos
La librería PWCheckout expone los siguientes eventos javascript a los cuales el comercio puede
suscribirse mediante la utilización del método “Bind”.

Evento Descripción Parámetros

opened Evento que se dispara cuando se abre la ventana N/A
que contiene el formulario de captura de la tarjeta
de pago.
closed Evento que se dispara cuando se cierra la ventana CloseInfo
que contiene el formulario de captura de la tarjeta
de pago.
tokenCreated Evento que se dispara cuando se recibe el Token TokenInfo
creado para la tarjeta de pago capturada.
notificationReceived Evento que informa la finalización del Flujo de NotificationInfo
Solicitud de Código de Verificación.

Invocación del formulario

La página web del comercio desde la que se realizará la invocación al Formulario de Checkout deberá
contener un campo de tipo oculto (input “hidden”) con identificador “PWToken”, cuyo valor será
seteado desde la librería javascript una vez obtenido el valor de dicho Token.
El campo deberá ser creado de la siguiente forma:

SiemprePago © 2019 Página 15 de 76

 <input type="hidden" name="PWToken" id="PWToken" />

Para comenzar el proceso de pago, se debe asociar cual es el elemento de la página que realizará la
llamada al formulario de captura de la tarjeta de pago. Este elemento puede ser un botón, imagen o
cualquier elemento activo que se desee asociar.
Para realizar la asociación, se deberá llamar al método AddActionButton de la librería PWCheckout
de la siguiente manera:

<script type="text/javascript">

PWCheckout.AddActionButton("buttonId");

</script>

Donde el parámetro “buttonId” se refiere al identificador del elemento elegido para desencadenar el
proceso de pagos.
En caso necesario, se pueden asociar múltiples elementos en la misma llamada, identificando cada
uno de ellos mediante su ID, separando cada uno de los identificadores mediante coma.

<script type="text/javascript">

PWCheckout.AddActionButton("buttonId1", "buttonId2", "buttonId3");

</script>

Luego de realizar este paso, al presionar el elemento asociado, se invoca el proceso de pago.

Una vez realizada esta invocación, el proceso es administrado por la librería javascript, la cual
presentará al usuario el formulario donde se le solicitarán los datos de la tarjeta de pago.
Luego, cuando el usuario ingresa los datos de su tarjeta y confirma, dicha información es tokenizada
por nuestros servidores y el Token es enviado a la librería PWCheckout.
El valor del token generado, es insertado automáticamente en el campo oculto “PWToken”, y
finalmente la librería javascript PWCheckout realiza las siguientes acciones:
- Dispara el evento “tokenCreated”
- Realiza el “submit” del formulario, si la propiedad autoSubmit está en “true”

El comercio deberá procesar los datos del formulario de pago, incluyendo el valor que recibirá en el
campo “PWToken” y enviará dicha información tal como se describe en la sección Purchase de la API.

SiemprePago © 2019 Página 16 de 76

Invocación del formulario con Filtros de Validación
Si se desea validar el ingreso de una cierta tarjeta, ya sea por la marca de la misma como el banco
emisor, se deberá proceder a la apertura personalizada del Formulario de Captura de tarjetas.
Para esto se utiliza un método distinto, el cual deberá ser llamado de forma explícita desde la página
del comercio informando que datos deben ser validados.
El método a utilizarse es el OpenIframeWithPaymentMediaOptions, el cual recibe los siguientes
parámetros:

● PaymentMediaId. Identificador del medio de pago en la pasarela (ver tabla de Medios de pago
- Payment Medias).

● BankId. Identificador del Banco en la pasarela (ver tabla de Emisores - Issuer Bank).

Ejemplo de invocación de OpenIframeWithPaymentMediaOptions:

<script type="text/javascript">

PWCheckout.Iframe.OpenIframeWithPaymentMediaOptions(paymentMediaId, bankId);

</script>

SiemprePago © 2019 Página 17 de 76

Formulario de Checkout embebido
Descripción
El formulario de Checkout es un formulario de pago que simplifica y asegura la captura de datos
sensibles para el procesamiento de pagos en línea.
A diferencia del formulario mencionado en la sección anterior, el formulario de Checkout “embebido”
se debe invocar desde una página diseñada por el comercio (recordando que el formulario
mencionado anteriormente funciona como popUp)
La integración de este formulario en su sitio o “app”, proporcionará a sus usuarios una experiencia de
pago simplificada y responsiva apta para web y aplicaciones móviles.

Importación de la Librería Javascript

Las funcionalidades del formulario de Checkout se encuentran en una librería Javascript, que debe ser
importada en la página web del cliente directamente desde una URL pública de nuestra plataforma.
En la llamada a dicha librería se deberá incluir (como parámetro) la clave pública de la cuenta de
comercio (PublicAccountKey) la cual será utilizada para las llamadas hacia la API REST desde esta
librería.

<script src="{ambiente_api}/v1/Scripts/PWCheckoutNoModal.js?key={PublicAccountKey}"
type="text/javascript"></script>

NOTA: La librería debe ser importada por el comercio a través de la URL pública dispuesta por
SiemprePago. No deberá ser descargada y usada localmente desde un servidor propio del comercio o
desde una URL de un tercero no autorizado por SiemprePago.
Esto es importante por motivos de seguridad y para mantenerse siempre actualizados con las últimas
modificaciones y correcciones realizadas sobre la misma.

Se debe definir un Iframe dentro de la web del comercio, sobre el cual será renderizado el formulario
de captura, como en el siguiente ejemplo.

<div id="iframeDiv" style="height: 410px; width: 300px; margin: auto;"></div>

Se debe setear el identificador del iframe en el método “SetProperties”, como en el siguiente ejemplo:

PWCheckout.SetProperties(
{
"iframeId": "custom_iframe",

}
);
FInalmente, se debe invocar al método que obtiene y renderiza el formulario de captura en el iframe
generado.
Dicho método se denomina “LoadIframe()”, el cual se invoca de la siguiente manera:

PWCheckout.LoadIFrame();

SiemprePago © 2019 Página 18 de 76

 En la última sección del presente documento, se brindará un ejemplo de página html en la cual se
importa el formularo de captura “embebido”.

Método GetCustomToken
Este método es utilizado para obtener un Token para realizar transacciones (solo disponible para
Redes Físicas) sin necesidad de presentar al cliente el formulario de selección de Medios de Pago
disponibles para el comercio.

Propiedad Descripción Presencia

paymentMediaId Identificador del medio de pago (red física) para el que se Mandatorio
numeric requiere el Token de pago.
Valores posibles:
● 5 – Abitab
● 10 – Redpagos
email Dirección de correo electrónico del Customer para el que se Mandatorio
string creará el Token de pago.
documentNumber Número de documento del Customer para el que se creará Mandatorio
string el Token de pago.
documentType Tipo de document del Customer para el que se creará el Opcional
numeric Token de pago.
En caso de no ser informado, se asumirá el tipo “Cédula”.
Valores posibles:
● 1 – RUT
● 2 – Cédula de identidad
● 3 - Extranjero

Ejemplo:

<script type="text/javascript">

PWCheckout.GetCustomToken(5, “email@domain.com”, “12345672”);

</script>

NOTA: El Token de pago será entregado de la misma forma que los otros métodos, es decir que se
incluirá en el campo de texto hidden “PWToken” y además se disparará el evento “tokenCreated” al
igual que los otros métodos de obtención del Token.

SiemprePago © 2019 Página 19 de 76

Flujo de una compra
A continuación, se describen los flujos para autorizar una compra a través de la plataforma.
Hay 2 flujos posibles de compras:
- Usuarios anónimos, que no están registrados en el sitio y hacen una compra por única vez. En
este caso se debe pedir siempre los datos de tarjetas para poder realizar la transacción.
- Usuarios registrados, para clientes que sí tienen un registro dentro del sitio web, se pueden
identificar y por lo tanto se pueden asociar los datos de tarjeta que se ingresan una vez para luego
realizar otras compras sin necesidad de ingresar nuevamente los datos.

Usuario anónimo
A continuación, se describen los pasos que se deben efectuar para realizar una compra con un usuario
anónimo (no registrado en el sitio web).

Captura de datos
En el sitio web, en el último paso de checkout del carrito de compras, se invoca el “Formulario de
Checkout” a través de la librería javascript de SiemprePago. Este formulario se muestra dentro de un
iframe de su propia página y solicita los datos de tarjeta.

Librería Javascript
La librería Javascript PWCheckout tiene propiedades para personalizar su apariencia de acuerdo a lo
que el comercio requiera. Una vez que se invoca el formulario de checkout, y el cliente llena los datos,
el comercio podrá obtener el “token” asociado a la tarjeta del cliente.
Este token es un “OneTime Token” y tiene validez por una única vez y está vigente durante 10 minutos.

Compra básica
El token obtenido debe ser enviado, desde el navegador o la app móvil, al servidor de la aplicación
para que éste haga la transacción de compra.
Desde el servidor se llama por HTTP POST a: {ambiente_api}/v1/api/purchase adjuntando el objeto
Purchase que contendrá el token y otros datos de la transacción.

{
'TrxToken':'OT_01_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_',
'Order':'17030613595101621fb',
'Amount': 123456,
'Currency':'UYU',
'Capture':true
}

SiemprePago © 2019 Página 20 de 76

 Diagrama de Secuencia del Flujo de Pagos
A continuación, se adjunta un diagrama de secuencia (simplificado) que enumera los distintos pasos
del proceso de pagos.

Usuario registrado
A continuación, se describen los pasos que se deben efectuar para realizar una compra con un usuario
registrado en el sitio web.
Los usuarios registrados del comercio deben darse de alta en el sistema de SiemprePago, para asociar
las tarjetas que desee utilizar. A las tarjetas registradas por el cliente se les asignará un
“CommerceToken”, el cual luego podrá ser utilizado en futuras transacciones.

Crear Customer
El primer paso es crear el customer en SiemprePago, para esto se realiza una llamada HTTP/POST a:
{ambiente_api}/v1/api/customer

SiemprePago © 2019 Página 21 de 76

 Como respuesta a esta llamada, se obtendrá un objeto de tipo Customer que tiene los elementos
necesarios para hacer la captura segura de los datos sensibles.
● CustomerId. Es el identificador del cliente dentro de la pasarela de pagos. Asocie este ID con
su cliente en sus estructuras de datos internas.
● CaptureURL. Es la URL a donde debe dirigir a su cliente para capturar los datos sensibles de
tarjeta.
● UniqueID. Es un identificador único creado para reconocer que la captura se está haciendo
desde un comercio válido que conoce al cliente (es suyo).

NOTA: Como el objeto Customer va a ser utilizado para realizar transacciones con distintos medios de
pago, algunos datos del cliente deben incluirse de forma mandatoria (documento, dirección, teléfono,
etc.) dependiendo de los requisitos específicos de cada medio de pago.
Referirse al Anexo 1. Adquirentes de Uruguay como referencia.

SiemprePago © 2019 Página 22 de 76

Captura de datos de Medios de Pago asociados al Customer

Diagrama de secuencia del Flujo de Enrolamiento de Tarjeta

Con la información obtenida en el paso anterior, se puede invocar el método OpenIframeCustom o

OpenIframeCustomWithPaymentMediaOptions (ver detalles más abajo) de la librería JavaScript
PWCheckout , el cual se encargará de gestionar la captura de la tarjeta.

El método OpenIframeCustom recibe dos parámetros:

SiemprePago © 2019 Página 23 de 76

 ● URL. Se especifica la dirección que se cargará en la ventana (iFrame) donde se solicitará al
cliente los datos de su tarjeta.
La URL se crea concatenando los datos recibidos de la siguiente forma:

{CaptureURL}?key={publicKey}&session_id={UniqueID}

● UniqueID. Identificador único con el que se identifica la sesión de captura de datos.

Ejemplo de llamada del método OpenIframeCustom:

<script type="text/javascript">

PWCheckout.OpenIframeCustom(url, UniqueID);

</script>

El método OpenIframeCustomWithPaymentMediaOptions recibe 4 parámetros:

● URL. Igual que en OpenIframeCustom.

● UniqueID. Igual que en OpenIframeCustom.

● PaymentMediaId. Identificador del medio de pago en la pasarela (ver tabla de Medios de pago
- Payment Medias).

● BankId. Identificador del Banco en la pasarela (ver tabla de Emisores - Issuer Bank).

Los dos parámetros son opcionales y se puede establecer uno solo o los dos. Si se establecen
los dos, el Formulario de Captura aceptará tarjetas del medio de pago y el banco especificados.

Ejemplos de llamada del método OpenIframeCustomWithPaymentMediaOptions:

1. Llamada con PaymentMediaId y BankId especificados:

<script type="text/javascript">

PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url,
UniqueID, paymentMediaId, bankId);

</script>

2. Llamada con BankId especificado y PaymentMediaId en nulo.

<script type="text/javascript">

PWCheckout.Iframe.OpenIframeCustomWithPaymentMediaOptions(url,
UniqueID, null, bankId);

</script>

SiemprePago © 2019 Página 24 de 76

El cliente ingresa los datos de su tarjeta y cuando confirma, la librería PWCheckout recibe la
notificación de que la tarjeta fue capturada correctamente.
El comercio puede suscribirse al evento “tokenCreated” que será disparado al recibir la notificación
de que la información de la tarjeta fue capturada.
El comercio también puede establecer la propiedad “form_id” (usando el método SetProperties) para
indicar el identificador de un formulario de la página que será controlado por la librería PWCheckout.
Una vez se haya capturado la información de la tarjeta, la librería realizará un “submit” de dicho
formulario.

Como respuesta a la notificación recibida (por “evento javascript” o por “submit” del formulario), la
página del comercio deberá volver a solicitar la información del Customer actualizada realizando la
siguiente llamada HTTP/GET (server to server):
{ambiente_api}/v1/api/customer/{customer-id}

El objeto Customer devuelto contiene el (o los) “PaymentProfiles” del cliente. Estos objetos contienen
información de los medios de pago asociados al cliente, donde en el campo “Token” se observa el
“CommerceToken” generado que representa a esa tarjeta de pago.

A continuación, se muestra un ejemplo de respuesta que incluye un PaymentProfile:

SiemprePago © 2019 Página 25 de 76

NOTA: La información de un “CommerceToken” no debe ser expuesta públicamente ya que representa la
tarjeta capturada y puede ser utilizada múltiples veces para realizar transacciones.

Compra básica
Para realizar la compra, desde el servidor se ejecuta una llamada HTTP POST a la URL:
{ambiente_api}/v1/api/purchase

En dicha llamada se debe adjuntar el objeto Purchase que contendrá el token y los otros datos de la
transacción.
Ejemplo:

{
'TrxToken':'CT_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_',
'Order':'17030613',
'Amount': 123456,
'Currency':'UYU',
'Capture':true
}

SiemprePago © 2019 Página 26 de 76

Compras recurrentes en un solo click
Luego que los clientes son registrados correctamente a través del método descripto, algunas tarjetas
de Pago admiten que las siguientes transacciones puedan realizarse sin necesidad de informar el
Código de Verificación (CVV), lo que permite una experiencia de usuario más ágil (pagos en un solo
click). En estos casos las compras pueden ser enviadas directamente sin solicitar más datos al cliente
como se explica en el punto anterior (Compra básica)

Para los casos en que la Tarjeta de Pago no admita esta modalidad, el Código de Verificación deberá
ser solicitado en todas las transacciones, ya que este dato no puede ser almacenado en nuestros
servidores.

Flujo de Solicitud de Código de Verificación

Para las Tarjeta de Pago que exigen el ingreso del Código de Verificación en todas las transacciones,
se diseñó el siguiente flujo de trabajo:

1. El Cliente, debidamente identificado en la página web del Comercio, inicia el proceso de pago
de una compra, utilizando para ello un Medio de Pago (tarjeta) previamente registrada y
asociada a su cuenta.

SiemprePago © 2019 Página 27 de 76

 2. La página web del Comercio, envía los datos al servidor para que se prepare la información a
ser enviada a SiemprePago.
3. El Web Server del comercio envia la compra (Purchase) a través de la API de SiemprePago,
identificando como forma de pago el Commerce Token asociado al Medio de Pago
seleccionado por el Cliente.
4. SiemprePago realizará una serie de validaciones, en este caso verificará si el Medio de Pago
elegido permite la ejecución de transacciones sin Código de Verificación.
En el caso de este flujo, el Medio de Pago seleccionado no admite esta funcionalidad, por lo
que la transacción no podrá completarse hasta haber obtenido el Código de Verificación de la
Tarjeta.
5. SiemprePago retorna como respuesta el objeto Purchase en estado Pending (pendiente) lo
que indica que se necesita alguna acción para poder completar el proceso.
El objeto Purchase devuelto, también contendrá el objeto CommerceAction que describe las
acciones necesarias a ser realizadas por el Comercio.
Ejemplo:

SiemprePago © 2019 Página 28 de 76

 El Comercio deberá almacenar la información de la compra pendiente (como mínimo el
PurchaseId para futuras validaciones) y procesar la información del CommerceAction para
determinar la acción requerida. En este caso, se tendrán en cuenta las propiedades siguientes:
a. ActionReason – Tendrá el valor “VERIFICATION_CODE_NEEDED”, debido a que la
compra requiere este Código de Verificación.
b. ActionType – Este campo tendrá el valor “2” que corresponde a la acción PWCapture,
que es una función propia del componente javascript PWCheckout que permite
procesar este tipo de acciones.
c. ActionURL – Este campo especifica la URL que deberá pasarse como parámetro al
método PWCapture del componente PWCheckout.
6. El Comercio deberá presentar al cliente el formulario de solicitud de Código de Verificación,
utilizando el método PWCapture de la siguiente forma:

<script type="text/javascript">
PWCheckout.PWCapture(url);
</script>

Donde el valor del parámetro “url” se corresponde con el campo ActionURL del objeto
CommerceAction recibido.
7. El cliente verá el iframe con el Formulario de Captura, que en este caso se presentará
mostrando el número de tarjeta enmascarado (solo los últimos 4 dígitos) y un campo de texto
para el ingreso del Código de Verificación.

8. El Cliente deberá ingresar el Código de Verificación de la tarjeta utilizada para realizar la

compra.
9. Este código de Verificación ingresado por el Cliente será enviado directamente a los
servidores de SiemprePago, donde será utilizado para crear el mensaje de autorización.
10. SiemprePago envía el mensaje de autorización hacia el Adquirente correspondiente con los
datos completos.

SiemprePago © 2019 Página 29 de 76

 11. La respuesta del Adquirente será procesada por SiemprePago y se actualizará el estado de la
compra según esta respuesta.
12. SiemprePago generará una notificación hacia el Comercio, informándole el objeto Purchase
con el estado final determinado luego del proceso de autorización.
La Purchase enviada será la misma previamente respondida en el paso 5, deberá validarse la
información de la misma (como mínimo que el PurchaseId coincida con el esperado).
Esta notificación será enviada hacia el servicio WebHook1 que el comercio deberá
implementar para recibir las distintas notificaciones generadas por SiemprePago.

Alternativa de Notificación
Además de la opción de recibir una notificación desde SiemprePago al finalizar el proceso de compra
(paso 12 del flujo normal), puede ejecutarse un flujo alternativo para consultar de forma explícita el
resultado de la compra una vez que se detecte que culminó el proceso que había quedado pendiente
(luego del paso 5).

1
Referirse al capítulo Servicio WebHook de Comercio.

SiemprePago © 2019 Página 30 de 76

 Este flujo utiliza las funcionalidades implementadas en la librería javascript PWCheckout para
informar la finalización del proceso pendiente de compra.
A continuación, se enumeran y explican los pasos relativos a este flujo, los pasos iniciales previos
al 12 son los mismos del flujo anteriormente explicado.

12. Una vez finalizado el proceso pendiente, la librería PWCheckout recibe la notificación del
estado de dicho proceso.
13. La librería PWCheckout dispara el evento “notificationReceived”.
El Comercio debe suscribirse previamente a dicho evento a través del método Bind, de la
siguiente manera:

<script type="text/javascript">
PWCheckout.Bind("notificationReceived", NotificationHandler);
</script>

SiemprePago © 2019 Página 31 de 76

 Donde la función NotificationHandler (el nombre es solo a modo de ejemplo) debe ser
implementada por el Comercio y será la que reciba la información del estado final del proceso.
Ejemplo de la función para manejo de notificaciones:

<script type="text/javascript">
function NotificationHandler(notification){
if(notification.ProcessStatus == 1){
//Proceso OK
}
else
{
//Proceso con error
}
}
</script>

El campo ProcessStatus de la notificación recibida determinará el estado final del proceso.

Los valores posibles son:
● OK (valor 1) – El proceso terminó exitosamente.
● Pending (valor 2) – El proceso aún está pendiente.
● Error (valor 3) – El proceso terminó con error.

14. Una vez que el Comercio recibe el evento “notificationReceived”, podrá continuar con el flujo.
15. El Comercio deberá realizar una llamada GET a la API de Purchase de SiemprePago
informándole el PurchaseId (que debió haber almacenado luego del paso 5).
16. La respuesta de SiemprePago contendrá el objeto Purchase con un estado distinto a Pending
(dependiendo del resultado de la transacción), por lo que podrá ser procesado como una
respuesta normal de compra.

SiemprePago © 2019 Página 32 de 76

Recursos
Los recursos son los ítems con los que se va a operar contra la API de integración.
Estos recursos están compuestos de un objeto y una serie de operaciones que se pueden realizar
sobre los mismos.

Objetos y operaciones

Nomenclatura de Objetos
Todos los objetos están descriptos en tablas con el siguiente formato:
Campo Descripción Presencia
Tipo Default

Campo - Es el nombre del campo en el objeto JSON.

Tipo - Es el tipo de datos del campo (ver en Tipos de datos la descripción de cada uno).
Descripción - Descripción del campo indicado, con comentarios de ayuda.
Presencia - Define si el campo es mandatorio, opcional o solo lectura.
Default - Para los campos opcionales, se indica el valor que se toma por default.

Nomenclatura de Operaciones
Todas las operaciones están descriptas en tablas con el siguiente formato:

URL: Url de ambiente

Tipo API: Visibilidad

Method: Método

Autenticación: Tipo de clave.

Parámetros: Objeto Descripción

Tipo
Ubicación

Respuesta: HTTP Code Código HTTP.

Response Descripción.
Tipo

SiemprePago © 2019 Página 33 de 76

 Errors Lista de errores que se pueden haber generado.
List<Error>

URL - URL de acceso a la operación, integrada por la determinación del ambiente y la API
específica.
Tipo API - Determina si se trata de una API Pública o Privada.
Method - Método HTTP (POST o GET)
Autenticación - Determina si se debe utilizar la clave pública o privada para la autenticación.
Parámetros - Listado de parámetros, incluyendo tipo de datos y ubicación (URL o Body).
Respuesta - Listado de datos de respuesta, incluyendo tipo de datos, errores y códigos HTTP.

Directivas para las operaciones

Cada objeto tiene operaciones que permiten crear, consultar o actualizar.

Creación de Objetos.
La creación de objetos se hace a través de un método POST a la URL de formato:
{ambiente_api}/v1/api/{object-name}

Actualización de Objetos
Cada objeto puede tener distintas operaciones de actualización.
La llamada básica se hace a través de un método POST a la URL de formato:
{ambiente_api}/v1/api/{object-name }/{object-id}/{operation}

Consulta de Objetos
Hay 2 tipos de consultas sobre los objetos:
a. La consulta que devuelve un objeto a través de su ID.
Se hace a través de un método GET a la URL de formato:
{ambiente_api}/v1/api/{object-name }/{object-id}

b. La consulta que devuelve una lista de objetos de acuerdo a diversos parámetros.

Se hace a través de un método GET a la URL de formato:
{ambiente_api}/v1/api/{object-name}?{query-parameters}

SiemprePago © 2019 Página 34 de 76

Purchase
Los servicios expuestos en la interfaz “purchase” responden a las distintas acciones de autorización,
reversa, cancelación y consulta de compras.

Objeto Purchase
El objeto Purchase se utiliza para informar los datos de una compra, sea esta una compra directa
como una compra recurrente.

Campo Descripción Presencia

Tipo Default

PurchaseId Identificador de la compra. Solo Lectura

Numeric

Created Fecha y hora del momento de la creación de la Solo Lectura

TimeStamp compra.
Este campo está presente en la respuesta a
consultas.
No se incluye o valida en la creación o actualizaciones
del objeto.

TrxToken Token que identifica la tarjeta del cliente. Condicional

string (Mandatorio en la
operación de
compra)

Order Número de orden, generado por el comercio. Mandatorio

string

Transaction Contiene la información que resulta de la transacción Solo Lectura

Transaction realizada contra el medio de pago (por ej: código de
respuesta, número de autorización). Ver objeto
Transaction.

Capture Establece si la compra se debe realizar en uno o dos Opcional

boolean pasos.
true
Es de tipo booleano cuyo valor por defecto es “true”.
Si es false, solo se procesa la autorización y la compra
queda pre-autorizada a la espera de la confirmación

SiemprePago © 2019 Página 35 de 76

 final a través de las llamadas commit (confirmar) y
rollback (anular).
Si es true, la transacción queda autorizada y
capturada (confirmada).
La pre-autorización es una funcionalidad que puede
no ser soportada por todos los medios de pago.
Revisar la tabla de medios de pago para verificar
disponibilidad.

Amount Monto total de la compra. Mandatorio

Amount
El valor debe ser mayor a cero.

Currency Moneda de la compra, de acuerdo a ISO-4217 Mandatorio

String[3] (códigos alfanuméricos).

Tip Propina. Opcional

Amount

Installments Cantidad de cuotas de la compra. Opcional

Numeric[3]
1

Description Descripción opcional de la compra. Opcional

String[50]

Customer Información del cliente que realiza el pago. Opcional

Customer
Algunos medios de pago pueden requerir
información adicional del cliente para poder tramitar
la autorización.

RefundList Lista de devoluciones realizadas a la compra. Solo Lectura

List<RefundData>

PlanID Reservado.

UniqueID Identificador único de la compra. Opcional

String[50]
Este valor opcional permite identificar una compra
única y evitar la duplicación de transacciones en caso
de errores de comunicación (ver más en Conceptos /
Identificador único).

SiemprePago © 2019 Página 36 de 76

AdditionalData Información adicional que el comercio puede agregar Opcional
String[300] a la transacción (ej: lista de datos de tipo
“Clave:Valor”).
Dicha información será devuelta al procesar la
compra y cada vez que dicha compra sea consultada.

CustomerUserAgent User Agent del cliente que utiliza el servicio, en la Opcional

String Web debería ser el UserAgent reportado por el
navegdor, en el caso de móviles información acerca
del dispositivo, S.O. utilizado, nombre de la App.

CustomerIP IP del cliente que utiliza el servicio. Opcional

String

DataUY Datos específicos para el país Uruguay. Opcional

CountryDataUY
Ver en la definición del objeto CountryDataUY.

CommerceAction Utilizado para indicar al comercio una acción que Solo Lectura
CommerceAction deba ser realizada por él o por el customer para
completar el proceso de la compra actual.
Si la transacción se devolvió en estado Pending, se
deberá revisar este objeto para determinar las
acciones siguientes.

PurchasePaymentProfileI Indica que perfil de pago fue utilizado para la compra

d actual.
Numeric Referencia al listado de PaymentProfiles dentro del
objeto Customer.

URL URL donde se puede acceder a la información de la Solo Lectura

String Compra.
Ej: {ambiente_api}/v1/api/purchase/{purchase-id}).

SiemprePago © 2019 Página 37 de 76

Crear una nueva compra

URL: {ambiente_api}/v1/api/purchase

Tipo API: Pública

Method: POST

Autenticación: PrivateAccountKey

Parámetros: Purchase Objeto que contiene la información de la compra a realizarse.

Purchase
Body

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información actualizada de la compra

Purchase realizada.
Se le asigna el PurchaseID que será utilizado como identificador de la
compra a partir de este momento.

Errors Lista de errores que se pueden haber generado.

List<Error>

Obtener información de una compra creada

URL: {ambiente_api}/v1/api/purchase/{purchase-id}

Tipo API: Pública

Método: GET

Autenticación PrivateAccountKey
:

Parámetros PurchaseID Identificador de la Compra

Numeric

SiemprePago © 2019 Página 38 de 76

 URL

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información de la compra solicitada.

Purchase

Errors Lista de errores que se pueden haber generado.

List<Error>

Confirmar una compra pre-autorizada

URL: {ambiente_api}/v1/api/purchase/{purchase-id}/commit

Tipo API: Pública

Método: POST

Autenticación PrivateAccountKey
:

Parámetros: PurchaseID Identificador de la Compra

Numeric
URL

Purchase Objeto que contiene la información de la compra a confirmar.

Purchase El monto de la compra puede variar respecto a la que se envió en el
proceso de Purchase inicial.
Body
El monto nuevo no puede ser superior al monto original.

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información de la compra actualizada.

Purchase

Errors Lista de errores que se pueden haber generado.

List<Error>

SiemprePago © 2019 Página 39 de 76

Anular una compra pre-autorizada

URL: {ambiente_api}/v1/api/purchase/{purchase-id}/rollback

Tipo API: Pública

Método: POST

Autenticación PrivateAccountKey
:

Parámetros PurchaseID Identificador de la Compra

Numeric
URL

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información de la compra actualizada.

Purchase

Errors Lista de errores que se pueden haber generado.

List<Error>

Devolver una compra creada y confirmada

URL: {ambiente_api}/v1/api/purchase/{purchase-id}/refund

Tipo API: Pública

Método: POST

Autenticación PrivateAccountKey
:

Parámetros: PurchaseID Identificador de la Compra

Numeric
URL

SiemprePago © 2019 Página 40 de 76

 Purchase [Opcional] Objeto que contiene la información de la compra a
Purchase devolver.
El monto de la Compra a devolver, puede ser total o parcial (a
Body determinar en cada caso dependiendo de las reglas establecidas por
los adquirentes y medios de pago).

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información actualizada de la compra.

Purchase

Errors Lista de errores que se pueden haber generado.

List<Error>

Lista de compras

Con este método se obtiene una lista de compras de acuerdo a los filtros que se pueden establecer
en los parámetros.
Los parámetros son todos opcionales. En caso de no haber ninguno se obtienen todas las compras
efectuadas en el día de hoy.

URL: {ambiente_api}/v1/api/purchase

Tipo API: Pública

Método: GET

Autenticación PrivateAccountKey
:

Parámetros: Nombre Descripción Valor por def.

CustomerID Identificador del cliente que realizó la Ninguno

Numeric compra.
URL

From Fecha inicial del filtro La fecha de hoy

Date Formato: yyyyMMdd
URL

SiemprePago © 2019 Página 41 de 76

 To Fecha final del filtro La fecha de hoy
Date Formato: yyyyMMdd
URL

PaymentMediaId Identificador del Medio de Pago con el que Ninguno

Numeric se realizaron las compras.

URL

Authorized Si el valor es true devuelve solo las compras false

que hayan finalizado exitosamente
Boolean
URL

OrderNumber Número de orden del comercio. Ninguno

String
URL

Respuesta: HTTP Code Código HTTP.

Response Lista de Compras que coinciden con los filtros de búsqueda.

List<Purchase>

Errors Lista de errores que se pueden haber generado.

List<Error>

SiemprePago © 2019 Página 42 de 76

Ejemplos de Respuestas

Compra Aprobada

Para validar cualquier operación sobre una compra, se debe validar en la respuesta que la misma
contenga:
- HTTP Code 200
- No contenga errores en “Errors”
- Y el el TransactionStatusID sea igual a 1

Compra Rechazada

Se recibe
- HTTP Code 200
- TransactionStatusID = 4
- Errors Vacío

SiemprePago © 2019 Página 43 de 76

Transacción con Error

En este ejemplo se intenta hacer un Commit de una transacción ya aprobada.

Se recibe
- HTTP Code 200
- Tiene Lista de Errores

SiemprePago © 2019 Página 44 de 76

Customer
Los servicios expuestos en la interfaz Customer cubren las acciones de creación y mantenimiento de
los clientes.

Objeto Customer
El objeto Customer se utiliza para informar los datos de un cliente.

Campo Descripción Presencia

Tipo Default

CustomerId Identificador del cliente. Solo Lectura

Numeric

CommerceCustomerI Identificador del cliente en el comercio. Opcional

d
Este valor es generado y utilizado internamente por el
String
comercio para identificar al cliente dentro de la
plataforma de SiemprePago.

Created Fecha y hora del momento de la creación del cliente. Solo Lectura
TimeStamp
Este campo está presente en la respuesta a consultas.
No se incluye o valida en la creación o actualizaciones
del objeto.

Owner Determina si el usuario fue registrado por el comercio, Solo Lectura

String a través de SiemprePago o anónimo.
Valores posibles: “Our”, “Commerce”, “Anonymous”.
Este campo está presente en la respuesta a consultas.
No se incluye o valida en la creación o actualizaciones
del objeto.

SiemprePago © 2019 Página 45 de 76

FirstName Nombre del cliente Opcional
String

LastName Apellido del cliente Opcional

String

Email Email del cliente Mandatorio

String

PhoneNumber Teléfono de contacto del cliente. Opcional

String

Enabled Indica si el usuario está habilitado o no a operar. Opcional

Boolean true

ShippingAddress Información de dirección de entrega (si está Opcional

Address disponible).

BillingAddress Información de dirección de facturación (si está Opcional

Address disponible y el usuario habilitó que se compartiera esa
información).

Plans Reservado

AdditionalData Lista de datos de tipo “Clave:Valor” para almacenar Opcional

información extra.

PaymentProfiles Lista de objetos PaymentProfile con información de los Solo Lectura

medios de pago registrados por el Customer.
List<PaymentProfile>

CaptureURL URL de captura de datos de tarjeta (es la URL que se Opcional

String debe abrir en un iframe para iniciar el proceso de
captura de datos sensibles).
Solo es válida para Customers de tipo “Commerce”.

UniqueID Identificador único temporal utilizado para registrar Solo Lectura

String medios de pago externos. Cada vez que se solicita la
información del Customer se genera un identificador
nuevo.

SiemprePago © 2019 Página 46 de 76

 URL URL donde se puede acceder a la información del Solo Lectura
String Cliente (ej. /v1/customer/{customer-id}).

DocumentTypeId Tipo de documento del cliente Opcional

Numeric

DocNumber Documento del cliente Opcional

String

Crear un nuevo Customer

URL: {ambiente_api}/v1/api/customer

Tipo API: Pública

Method: POST

Autenticación PrivateAccountKey
:

Parámetros: Customer Objeto que contiene la información del cliente

Customer
Body

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información del Cliente actualizada.

Customer Se asigna el valor de CustomerID.

Errors Lista de errores que se pueden haber generado.

List<Error>

SiemprePago © 2019 Página 47 de 76

Actualizar un Customer

URL: {ambiente_api}/v1/api/customer/{customer-id}/update

Tipo API: Pública

Método: POST

Autenticación PrivateAccountKey
:

Parámetros: CustomerID Identificador del Cliente a modificar.

Numeric
URL

Customer Objeto que contiene la información del cliente

Customer
Body

Respuesta: HTTP Code Código HTTP

Response Objeto que contiene la información actualizada del cliente.

Customer

Errors Lista de errores que se pueden haber generado.

List<Error>

Obtener datos de un Customer

URL: {ambiente_api}/v1/api/customer/{customer-id}

Tipo API: Pública

Método: GET

Autenticación: PrivateAccountKey

SiemprePago © 2019 Página 48 de 76

 Parámetros: CustomerID Identificador del cliente.
Numeric
URL

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información del cliente.

Customer

Errors Lista de errores que se pueden haber generado.

List<Error>

Activar perfil de Pago

URL: {ambiente_api}/v1/api/customer/{customer-id}/activate

Tipo API: Pública

Método: POST

Autenticación: PrivateAccountKey

Parámetros: CustomerID Identificador del cliente.

Numeric
URL

Activation Objeto que contiene la información relativa al perfil que se

CustomerActivatio desea activar y el código de activación relacionado.
n
Body

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información del cliente.

Customer

Errors Lista de errores que se pueden haber generado.

List<Error>

SiemprePago © 2019 Página 49 de 76

Modificar Perfil de Pago

URL: {ambiente_api}/v1/api/customer/{customer-id}/PaymentProfileUpdate

Tipo API: Pública

Método: POST

Autenticación PrivateAccountKey
:

Parámetros: CustomerID Identificador del cliente.

Numeric
URL

PaymentProfil Objeto que contiene la información relativa al Perfil de Pago que

e se desea modificar.
PaymentProfil
Nota: Los datos modificables se establecen en la descripción del
e
objeto PaymentProfile.
Body

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información del cliente, con los medios de
Customer pago actualizados.

Errors Lista de errores que se pueden haber generado.

List<Error>

Eliminar Perfil de Pago

URL: {ambiente_api}/v1/api/customer/{customer-id}/PaymentProfileDelete

Tipo API: Pública

Método: POST

SiemprePago © 2019 Página 50 de 76

 Autenticación PrivateAccountKey
:

Parámetros: PaymentProfil Identificador del perfil de pago que se desea eliminar.

eId
long
Body

Respuesta: HTTP Code Código HTTP.

Response Objeto que contiene la información del cliente, con los medios de
Customer pago actualizados.

Errors Lista de errores que se pueden haber generado.

List<Error>

Objetos

Account
El objeto Account se utiliza para informar los datos de Cuentas de Comercio.

Campo Descripción Presencia

Tipo Default
AccountID Identificador de la Cuenta de Comercio Mandatorio
Numeric
Name Nombre de la cuenta de comercio
String
Phone Teléfono asociado a la cuenta de comercio
String
Address Objeto con la información de la dirección
Address asociada a la cuenta de comercio
Created Fecha y hora de creación de la cuenta de
TimeStamp comercio
Commerce Objeto con la información del comercio al que
Commerce pertenece esta cuenta.
PrivateAccountKey Clave privada asignada al comercio para las
String operaciones mediante la API

SiemprePago © 2019 Página 51 de 76

 PublicAccountKey Clave pública asignada al comercio para las
String operaciones mendiante la API

Address
El objeto Address se utiliza para informar datos de dirección de un cliente.
Puede referirse a la dirección de facturación asociada a una tarjeta, así como una dirección de entrega.

Campo Descripción Presencia

Tipo Default
AddressID Identificador de la Dirección Mandatorio
Numeric
AddressType Tipo de Dirección. Opcional
AddressType
Country País Opcional *
String
State Estado / Departamento / Provincia Opcional **
String
City Ciudad Opcional **
String
AddressDetail Calle, número, etc. Mandatorio
String
PostalCode Código postal Opcional **
String
* Algunos adquirentes pueden requerir este campo.
** Estos campos podrían ser mandatorios para direcciones de USA y Canadá.

Commerce
El objeto Commerce se utiliza para informar los datos de un Comercio en el sistema.

Campo Descripción Presencia

Tipo Default
CommerceID Identificador del Comercio Mandatorio
Numeric
Created Fecha y hora de la creación del comercio Mandatorio
TimeStamp
Name Nombre del comercio Mandatorio
String

SiemprePago © 2019 Página 52 de 76

 LegalName Razón social del comercio Mandatorio
String
Address Dirección del comercio Mandatorio
String
Document Número de documento fiscal del comercio Mandatorio
String
DocumentType Tipo de documento Mandatorio
DocType

RefundData
Datos de las devoluciones realizadas sobre la compra.
Puede tratarse de una devolución total o una serie de devoluciones parciales que decrementan el
monto efectivo de la compra.
Campo Descripción Presencia
Tipo Default
PurchaseRefundId Identificador asociado a la devolución. Opcional
Numeric False
Created Fecha y hora del momento en que se realizó la Solo Lectura
TimeStamp devolución.

UniqueID Identificador único de la transacción. Solo Lectura

String[50]
Este valor opcional permite identificar una
devolución en la lista de todas las posibles
devoluciones realizadas.
Amount Monto total de la devolución. El valor debe ser Solo Lectura
Amount mayor a cero.
Currency Moneda de la compra, de acuerdo a ISO-4217 Solo Lectura
String[3] (códigos alfanuméricos).
Status Estado de la devolución. Solo Lectura
TransactionStatus

SiemprePago © 2019 Página 53 de 76

CountryDataUY (Uruguay)
Datos específicos para el país Uruguay (Código ISO-3166 = UY).
En Uruguay rigen leyes que benefician el uso de medios electrónicos mediante la devolución de
puntos de IVA a dichas transacciones.
La ley 19.210 (ley de inclusión financiera) y la 17.934 (para servicios gastronómicos y afines) rigen
estos beneficios y los datos que se presentan a continuación son necesarios para su correcto uso.

Campo Descripción Presencia

Tipo Default
IsFinalConsumer Indica si la venta es realizada a un consumidor Opcional
Boolean final False
Invoice Número de factura asociado a la venta Opcional, mandatorio si
String IsFinalConsumer = true
TaxableAmount Importe gravado por IVA. Opcional, mandatorio si
Amount IsFinalConsumer = true
Default : 0

CountryDataDo (Rep. Dominicana)

Datos específicos para la República Dominicana (Código ISO-3166 = DO)

Campo Descripción Presencia

Tipo Default
Invoice Número de factura asociado a la venta Opcional
String
Tax Monto de impuestos pagados Opcional
Amount

SiemprePago © 2019 Página 54 de 76

Error
El objeto Error se utiliza para intercambiar información de errores que pueden haberse generado en
el procesamiento de cada request.

Campo Descripción Presencia

Tipo Default
ErrorCode Código de error preestablecido Solo Lectura
Numeric
Created Fecha y hora del momento de generación del error Solo Lectura
TimeStamp
Message Texto descriptivo del error Solo Lectura
String
Detail Detalle del error Solo Lectura
String

PaymentProfile
El objeto PaymentProfile se utiliza para informar los datos de un medio de pago registrado por el
Customer al que está asociado.

Campo Descripción Presencia

Tipo Default
PaymentProfileI Identificador del perfil de pago registrado para el Solo Lectura
d Customer.
Numeric
PaymentMediaI Identificador del medio de pago asociado al perfil. Solo Lectura
d
Numeric
Created Fecha y hora de creación del Perfil de Pago. Solo Lectura
TimeStamp
LastUpdate Fecha y hora de la última actualización del Perfil de Solo Lectura
TimeStamp Pago.
BIN Dato que corresponde con los primeros 6 dígitos de Solo Lectura
String la tarjeta de pago.

Nota: Este dato no es devuelto en todos los casos,

consulte al momento de la integración.
Brand Nombre asociado a la marca de la tarjeta de pago, Solo Lectura
String por ejemplo “VISA”.

SiemprePago © 2019 Página 55 de 76

 CardOwner Nombre del Tarjetahabiente (informado por el Opcional
String cliente durante el proceso de captura de datos de
(Puede modificarse en la
tarjeta). operación
PaymentProfileUpdate)

IssuerBank Identificador del Banco Emisor. Solo Lectura

String (en caso que pueda ser determinado)
Type Tipo de medio de pago, por ejemplo “CreditCard” Solo Lectura
String
Token Dato que representa al medio de pago registrado Solo Lectura
String sin exponer los datos sensibles del mismo.
Este dato será utilizado para realizar transacciones
de pago mediante el medio de pago registrado.
Expiration Fecha de expiración del medio de pago (si Opcional
String corresponde).
(Puede modificarse en la
Formato: yyyyMM operación
PaymentProfileUpdate)

Last4 Últimos 4 dígitos de la tarjeta de pago (si Solo Lectura

Numeric corresponde).
Enabled Determina si el perfil se encuentra habilitado para Opcional
Boolean realizar pagos.
(Puede modificarse en la
operación
PaymentProfileUpdate)

CustomerActivation
El objeto CustomerActivation se utiliza para informar los datos de activación de un perfil de pagos
registrado por el Customer.

Campo Descripción Presencia

Tipo Default
Token Identificador del Token asociado al perfil que se Mandatorio
String desea activar.
ActivationCode Código de activación recibido por el cliente, Mandatorio
String asociado al perfil que se desea activar.

SiemprePago © 2019 Página 56 de 76

Transaction
El objeto Transaction está asociado a un objeto Purchase y contiene la información de requerimiento
enviado y la respuesta obtenida del medio de pago correspondiente.
Tiene asociado una lista de pasos (o estados intermedios) por los que puede pasar una transacción
(pre-autorización, captura, anulación, etc.).

Campo Descripción Presencia

Tipo Default
TransactionID Identificador de la Transacción Solo Lectura
Numeric
Created Fecha y hora del momento de creación de la Solo Lectura
TimeStamp transacción.
TransactionStatusId Identificador del Status de la transacción al Solo Lectura
Numeric momento de la consulta.
Status Estado de la transacción al momento de la Solo Lectura
TransactionStatus consulta
Description Descripción del resultado de la transacción Solo Lectura
String
ApprovalCode Código de aprobación devuelto por el medio de Solo Lectura
String pago.
Steps Lista de los estados intermedios desde que se Solo Lectura
List<TransactionStep creó la transacción.
>

TransactionStep
El objeto TransactionStep se utiliza para informar los datos de los distintos estados por los que paso
la Transacción hasta su estado actual.

Campo Descripción Presencia

Tipo Default
Step Nombre del paso ejecutado. Solo Lectura
String
Created Fecha y hora del momento de ejecución del paso. Solo Lectura
TimeStamp
Status Estado final luego de la ejecución del paso. Solo Lectura
StepStatus

SiemprePago © 2019 Página 57 de 76

 ResponseCode Código de respuesta obtenido luego de la Solo Lectura
String ejecución del paso actual.
Contiene por ejemplo el código de respuesta del
medio de pago.
ResponseMessage Mensaje de respuesta asociado al ResponseCode. Solo Lectura
String
Error Código de error generado (si corresponde) en la Condicional
String ejecución del paso.
AuthorizationCod Código de aprobación devuelto por el medio de Solo Lectura
e pago.
String
UniqueId Identificador único de la llamada (request) que Solo Lectura
String desencadenó la ejecución de este paso.
Utilizado para relacionar operaciones Refund y
Rollback.

CommerceAction
El objeto CommerceAction se utiliza para informar al comercio las distintas acciones que deben ser
realizadas por él o por el cliente para completar el proceso de la compra actual.
Por ejemplo algunos medios de pago pueden solicitar una confirmación adicional al tarjetahabiente
(por ej. Verified By Visa, MasterCard SecureCode, etc.).

Campo Descripción Presencia

Tipo Default
ActionType Tipo de acción requerida Solo Lectura
ActionType
ActionReason Texto que determina la razón por la que se debe Solo Lectura
String ejecutar dicha acción.
ActionURL En caso de que la acción necesaria implique la Solo Lectura
String interacción del usuario mediante redirección o
popup en este campo se encontrará la URL que se
debe presentar al cliente para confirmar y/o
procesar algún dato personal.

Nota: Si se abre en una ventana de navegación

nueva, se debe tener en cuenta que el browser
puede bloquear las ventanas emergentes.

SiemprePago © 2019 Página 58 de 76

Notification
El objeto Notification se utiliza para enviar actualizaciones de estado u otras notificaciones hacia el
comercio sin esperar que este lo solicite. Por ejemplo en flujos de transacciones donde la misma
queda en estado Pendiente y se requieren otras acciones para terminar su procesamiento.
Estas notificaciones serán entregadas al servicio WebHook que debe ser implementado por el
comercio de forma de poder procesar estas llamadas.

Campo Descripción Presencia

Tipo Default
NotificationId Identificador de la notificación. Solo Lectura
Numeric
Created Fecha y hora de creación de la notificación. Solo Lectura
TimeStamp
ResourceType Tipo de Recurso informado. Solo Lectura
ResourceType Por ejemplo “Purchase” para informar el estado
final de la compra realizada.
ResourceUrl URL donde se puede consultar el recurso Solo Lectura
String informado.
ResourceObject Objeto devuelto. Solo Lectura
String Puede contener cualquier tipo de objeto, como un
Purchase o un Customer, dependiendo del tipo de
notificación y el proceso que la desencadenó.

Un ejemplo de notificación que se puede recibir es la siguiente:

{
"NotificationId":3270,
"Created":"2019-10-15T16:58:41.410",
"ResourceType":"1",
"ResourceUrl":"https://url.com/v1/api/Purchase/1111",
"ResourceObject":{
"PurchaseId":1111,
"Created":"2019-10-15T13:58:36.070",
"TrxToken":null,
"Order":"67",
"Transaction":{ },
"Capture":true,
"Amount":3600,
"OriginalAmount":3600,

SiemprePago © 2019 Página 59 de 76

 "Tip":0,
"Installments":1,
"Currency":"UYU",
"Description":null,
"Customer":{ },
"RefundList":null,
"PlanID":null,
"UniqueID":null,
"AdditionalData":null,
"CustomerUserAgent":null,
"CustomerIP":null,
"URL":"Purchase/1111",
"DataUY":{ },
"Acquirer":{ }
}
}

Objetos Javascript

CloseInfo
El objeto CloseInfo es devuelto en el evento “closed”, el cual es disparado como respuesta al cierre
de la ventana del formulario de captura de datos de tarjetas.

Campo Descripción
Reason Descripción de la razón por la cual se cerró la ventana.
string Las posibles razones son las siguientes:
● ESCAPE – Se presionó el botón “Esc”.
● CLOSE_BUTTON – Se presionó el botón de cierre de la ventana.
● TIMEOUT – Se excedió el tiempo máximo de espera para que el
usuario ingrese los datos.
● COMMERCE_ACTION – Se necesita ejecutar una acción por parte del
Comercio.
● ERROR – Ocurrió un error.
● TOKEN_RECEIVED – Se recibió el token generado a partir de los datos
ingresados por el usuario.
● NOTIFICATION_RECEIVED – Se recibió una notificación.
● PAGE_CLICK – Se hizo click en la página (fuera del formulario de
captura) y se estableció la Property “close_onclick” en “true”.

SiemprePago © 2019 Página 60 de 76

TokenInfo
El objeto TokenInfo es devuelto en el evento “tokenCreated”, el cual es disparado cuando se recibe
el Token creado a partir de los datos informados por el usuario en el formulario de captura de datos
de tarjetas.

Campo Descripción
Tipo

TokenId Es el token generado.

string

Created Fecha y hora de creación del token

TimeStamp

Type Tipo de token generado, valores posibles:

string - “OneTime”
- “Commerce”

Brand Marca de la tarjeta o medio de pago utilizado

string

IssuerBank Banco emisor de la tarjeta (en caso que pueda ser determinado).
string

Owner Nombre del tarjetahabiente

string

Last4 Últimos cuatro dígitos de la tarjeta.

Numeric[4]

CardType Tipo de tarjeta o medio de pago, valores posibles:

string
“CreditCard”
“DebitCard”
“PhysicalNetwork”
“PrePaid”

CardExpMonth Mes de expiración de la tarjeta

Numeric[2]

SiemprePago © 2019 Página 61 de 76

 CardExpYear Año de expiración de la tarjeta
Numeric[2]

NotificationInfo
El objeto NotificationInfo es devuelto en el evento “notificationReceived”, el cual es disparado cuando
se finaliza el Flujo de Solicitud de Código de Verificación..

Campo Descripción
Tipo

ProcessType Define para que tipo de proceso se está emitiendo esta notificación.
string Los valores posibles de ProcessType son:
● PURCHASE_PENDING – proceso de autorización de una
compra pendiente.

ProcessStatus Enumerado que define el estado del proceso.

Numeric[1] Los valores de ProcessStatus son:
● 1 – OK (el proceso se completó exitosamente)
● 2 – PENDING (el proceso continúa pendiente)
● 3 – ERROR (el proceso finalizó de forma errónea)

Servicio WebHook de Comercio

El comercio podrá implementar un servicio de forma de poder recibir y procesar notificaciones
enviadas desde los sistemas de SiemprePago.
Este servicio es necesario en algunos de los flujos de transacciones donde el proceso no puede ser
completado en forma sincrónica, por lo que el estado final de la transacción será informado
asincrónicamente una vez que se haya podido obtener.
El comercio deberá publicar un servicio HTTP/REST al cual serán enviadas las notificaciones que se
generen.

SiemprePago © 2019 Página 62 de 76

Especificaciones del servicio WebHook
El servicio WebHook se trata de un Servicio REST que deberá procesar un request con las siguientes
características:

URL: <A determinar por el Comercio>

Tipo API: Pública

Method: POST

Autenticación PrivateAccountKey
:

Parámetros: Notification Objeto que contiene la información de notificación enviada.

Notification
Formato: JSON
Body

Respuesta: HTTP Code Código HTTP.

La implementación de este servicio depende de la plataforma y lenguaje elegidos por el comercio.

Los únicos requisitos técnicos son:
● Deberá aceptar mensajes en formato JSON (application/json)
● Deberá validar la clave privada (PrivateAccountKey) enviada en el header de autenticación en
el mismo formato que se envían los mensajes a SiemprePago.
● Deberá responder solo un código HTTP, donde:
o Si se responde el código 200 (OK), SiemprePago asumirá que el procesamiento de la
notificación fue exitoso.
o Si se responde cualquier otro código distinto a 200, SiemprePago asumirá que el
procesamiento fue fallido, por lo que la notificación se reintentará.
La propiedad ResourceObject del objeto Notification recibido puede contener uno de varios tipos
de objetos. Se deberá validar la propiedad ResourceType para saber cómo tratar el
ResourceObject.
Por ejemplo, si se envía una notificación relacionada al cambio de estado de una compra, el
ResourceType corresponderá a Purchase y el ResourceObject se deberá tratar según la definición
de dicho tipo de datos.

SiemprePago © 2019 Página 63 de 76

Códigos
Códigos HTTP

Código Descripción Uso

200 Ok La solicitud fue procesada correctamente.

400 Bad Request La solicitud está mal formada o falta algún parámetro obligatorio.

401 Unauthorized Fallo de autenticación.

403 Forbidden No tiene permisos para realizar la operación solicitada.

404 Not Found El recurso solicitado no fue encontrado.

405 Method not Request por método incorrecto (ej. GET en lugar de POST).
Allowed

408 Request No se pudo completar el pedido en el tiempo máximo configurado.

Timeout

500 Internal Ocurrió un error en el servicio.

Server Error

503 Service El servicio está en mantenimiento o experimentando problemas de

Unavailable acceso.

Códigos de error

Código Mensaje Descripción

TK… Errores servicio de Tokenización
TK001 INVALID_CAR El número de tarjeta ingresado es incorrecto.
D_PAN
TK002 INVALID_CVV El número de CVV ingresado es incorrecto.
TK003 INVLALID_EXPI La fecha de vencimiento de la tarjeta es incorrecta.
RATION_DATE

SiemprePago © 2019 Página 64 de 76

TK004 INVALID_SESSI Se envió un identificador de sesión inválido en una solicitud de
ON_IDENTIFIE token.
R
TK005 INVALID_EMAI Se ingresó un email con formato incorrecto.
L
TK006 EXPIRED_TOK El token (de tipo One-Time) ya fue utilizado o está expirado.
EN
TK007 INVALID_PAY Medio de pago no coincide con el esperado.
MENT_MEDIA
TK008 ISSUER_BANK Banco emisor no coincide con el esperado.
_NOT_MATCH
TK009 INVALID_ACTI Código de activación de Token inválido.
VATION_CODE
TK010 INVALID_COM Token de Comercio inválido.
MERCE_TOKE
N
TK011 CUSTOMER_N El Cliente especificado no es válido.
OT_FOUND
TK012 TOKEN_ACTIV Error al activar el Token.
ATION_ERROR
TK013 TOKEN_REGIS Error en proceso de registro.
TRY_VOID_ER
ROR
TK014 TOKEN_PAYM Medio de pago deshabilitado.
ENT_MEDIA_D
ISABLED
TK015 TOKEN_PAYM Medio de pago no disponible para el Comercio.
ENT_MEDIA_U
NAVAILABLE
TK016 PAYMENT_ME Ocurrió un error en el proceso de registro del medio de pago.
DIA_REGISTRY
_FAILS
TK999 UNKNOWN_E Error desconocido, el detalle puede especificar el error real.
RROR
PR… Errores servicio de Purchase
PR001 INVALID_TOKE El token informado es inválido, está vencido o no corresponde al
N comercio.

SiemprePago © 2019 Página 65 de 76

PR002 INVALID_ORD El número de órden es inválido.
ER
PR003 INVALID_AMO El monto informado es inválido.
UNT
PR004 INVALID_CUR La moneda informada es inválida.
RENCY
PR005 INVALID_INVO El número de factura es inválido (debe ser numérico).
ICE
PR006 INVALID_PUR El identificador de la compra es inválido.
CHASE_IDENTI
FIER
PR007 - Reservado.
PR008 PURCHASE_N No pudo encontrarse la compra solicitada.
OT_FOUND
PR009 INVALID_PUR El estado actual de la compra no permite realizar la acción
CHASE_STATE solicitada.
PR010 TAXABLE_AM Debe especificar el campo TaxableAmount.
OUNT_REQUI
RED
PR011 INVOICE_REQ Debe especificar el campo Invoice.
UIRED
PR012 - Reservado.
PR013 INVALID_INST El plan de cuotas seleccionado no es válido para la tarjeta
ALLMENTS ingresada por el cliente.
PR014 - Reservado.
PR015 - Reservado.
PR016 - Reservado.
PR017 TAXABLE_AM El campo TaxableAmount (monto imponible) no puede ser
OUNT_GREAT superior al monto total de la compra.
ER_THAN_AM
OUNT

CS… Errores servicio Customers.

CS001 INVALID_EMAI El email informado es inválido.
L

SiemprePago © 2019 Página 66 de 76

CS002 INVALID_ADD Tipo de direccion invalida.
RESS_TYPE
CS003 INVALID_CUST Identificador de cliente inválido.
OMER_IDENTI
FIER
CS004 TOKEN_CREAT Error en la creación del Token.
ION_FAILED
CS005 EMAIL_ALREA Email ya registrado.
DY_EXISTS
CS006 INVALID_ADDI AdditionalData mal formado, debe ser clave:valor separados por
TIONAL_DATA ;
CS007 INVALID_CUST El Documento especificado es inválido.
OMER_DOCU
MENT
CS008 INVALID_CUST El Tipo Documento especificado es inválido.
OMER_DOCU
MENT_TYPE
CS009 TOKEN_ALREA Ya existía un CommerceToken para la tarjeta informada.
DY_EXISTS
CS010 INVALID_PAY El Perfil de Pago informado es inválido.
MENT_PROFIL
E
CS011 INVALID_PAY El Identificador del Perfil de Pago es inválido.
MENT_PROFIL
E_IDENTIFIER
TR… Errores servicio Transactions
TR001 COMMUNICAT Error de comunicación con el servicio adquirente.
ION_ERROR
TR002 INVALID_TRA La transacción asociada a la compra se encuentra en un estado
NSACTION_ST que no permite la ejecución de la operación actual.
ATE Esto sucede por ejemplo cuando se quiere realizar una operación
“Commit” sobre una Purchase que ya se encuentra autorizada o
que fue rechazada.
TR003 ACQUIRER_AC Problemas con la cuenta de comercio en el Adquirente.
COUNT_PROB
LEM
TR004 ACQUIRER_PR Error el enviar transacción al Adquirente mediante Proxy.
OXY_ERROR

SiemprePago © 2019 Página 67 de 76

TR005 ACQUIRER_PR Error interno del Adquirente.
OBLEM
TR006 ACQUIRER_DU Número de orden duplicada en el Adquirente.
PLICATED_OR
DER
TR007 INVALID_PAY Error con algún dato del medio de pago (número de tarjeta,
MENT_MEDIA código de verificación y/o fecha de expiración).
TR008 COMMIT_AM El monto que se intenta confirmar es superior al autorizado
OUNT_GREAT previamente.
ER_THAN_AU
THORIZED
TR009 ACQUIRER_UN Error desconocido de Adquirente.
KNOWN_ERR
OR
TR010 ACQUIRER_IN Documento de identidad inválido.
VALID_DOCU
MENT
TR011 BLOCKED_OR_ Tarjeta perdida o bloqueada.
LOST_CARD
TR012 ACQUIRER_LI Límite de crédito excedido.
MIT_EXCEEDE
D
TR013 ACQUIRER_DE El emisor o el adquirente rechazó la transacción.
NIED_TRANSA
CTION
TR014 ACQUIRER_PO El Adquirente denegó la transacción por posible fraude.
SSIBLE_FRAUD
TR015 ACQUIRER_RE El Adquirente sugiere la revisión manual de la transacción.
VIEW_NEEDED Por ejemplo por sospecha de fraude.
TR016 ACQUIRER_IN Error en los parámetros informados al adquirente.
VALID_PARAM
ETER
TR017 INVALID_TRA Tipo de transacción inválida.
NSACTION_TY
PE
TR018 REGISTRATION El Adquirente denegó el registro.
_DENIED

SiemprePago © 2019 Página 68 de 76

TR997 TRANSACTION Ocurrió un error al ejecutar el proceso actual.
_STEP_ERROR
TR999 UNKNOWN Error no determinado al ejecutar la transacción.
ER… Errores genéricos.

ER999 UNKNOWN No determinado.

SiemprePago © 2019 Página 69 de 76

Tipos de datos
Básicos

String
Es una cadena de caracteres que puede contener cualquier caracter Unicode.
Puede definirse un largo máximo que está expresado entre corchetes, por ejemplo string[30] significa
que el string puede contener como máximo 30 caracteres.
Salvo que en la documentación del dato se especifique lo contrario, si un string tiene más caracteres
que el máximo definido se truncará y se continuará el procesamiento.

Numeric
Campo numérico de valor entero.
Puede definirse un largo máximo que está expresado entre corchetes, por ejemplo Numeric[3]
significa que el número puede ser de 3 cifras como máximo.
Si el dato posee un valor mayor a la especificación, se devolverá un error.

Amount
Campo numérico que incluye decimales, para expresar los montos relacionados a una transacción.
Estos campos son siempre expresados con la parte entera más 2 decimales sin signos de puntuación
entre ambos.
A continuación se plantean ejemplos de cómo deben codificarse los valores:
Valor Codificación
100 10000
1.237,52 123752
3.200,5 320050
0,01 1

TimeStamp
Campo que contiene un valor fecha/hora que debe ser expresado en el siguiente formato:
"YYYY-MM-DDTHH:mm:ss.ttt" donde:
● YYYY indica el año
● MM indica el mes
● DD indica el día
● T indica el inicio de la sección de tiempo requerida
● hh indica la hora (de 0 a 23)
● mm indica los minutos
● ss indica los segundos

SiemprePago © 2019 Página 70 de 76

 ● ttt indica los milisegundos

A continuación se plantean ejemplos de cómo deben codificarse los valores:

Valor Codificación
2016/01/12 13:21:48.354 2016-01-12T13:21:48.354
2016/03/31 05:17:00.000 2016-03-31T05:17:00.000
2016/11/28 22:59:59.970 2016-11-28T22:59:59.970

Date
Campo que contiene una fecha exacta, sin horas. Debe ser expresado en el siguiente formato:
yyyyMMdd

Boolean
Campo que determina si un elemento se encuentra habilitado o no.
Valores:
● true
● false

TransactionStatus
Indica el estado final de una transacción.

Valores posibles:
TransactionStatusId TransactionStatus

1 Approved

2 Pending

3 Preauthorized

4 Rejected

5 Paid

6 Cancelled

SiemprePago © 2019 Página 71 de 76

StepStatus
Indica el estado final de la ejecución de cada “paso”.
Este estado es utilizado para procesos internos de la plataforma, puede ser procesado, pero se sugiere
siempre atenerse al TransactionStatusId (y su correspondiente Status) informado dentro del objeto
Transaction.

Valores posibles:
TransactionStatusId TransactionStatus

1 Created

2 Finished

3 Authorization OK

4 Authorization Fail

5 Pre-authorization OK

6 Pre-authorization Fail

7 Rollback OK

8 Rollback Fail

9 Authorization OK - Step 1

10 Refund OK

11 Refund Fail

ActionType
Indica el tipo de acción a realizarse por parte del comercio (parte del CommerceAction).

Valores posibles:

ActionType Acción

SiemprePago © 2019 Página 72 de 76

 1 Redirect

2 PWCapture

ResourceType
Indica el tipo de recurso informado en una notificación.

Valores posibles:

ResourceType Resource

1 Purchase

2 Customer

AddressType
Indica el tipo de dirección registrada de un cliente (Customer).
Valores posibles:

AddressType Tipo

1 Billing

2 Shipping

Listas
Los campos definidos como List<objeto> son listas en formato JSON que contienen elementos del tipo
‘objeto’.
El siguiente es un ejemplo de presentación de una lista de errores:

"Errors": [
{
"ErrorCode": "PR002",
"Created": "170305032423042",
"Message": "INVALID_ORDER",
"Detail": "El Token informado es inválido"
},
{
"ErrorCode": "PR003",

SiemprePago © 2019 Página 73 de 76

 "Created": "170305032423042",
"Message": "INVALID_AMOUNT",
"Detail": "El Monto informado es inválido"
}
]

Tablas
Medios de pago (PaymentMedia)
La siguiente tabla identifica los medios de pago aceptados, incluyendo las funcionalidades soportadas
por cada uno.

Payment Medio Compra Pre- Devolución Devolución

Media Id de Pago autorización total parcial
1 VISA Sí Sí Sí Sí
2 MasterCard Sí Sí Sí Sí
4 OCA Sí No Sí No
5 Abitab Sí No No No
6 Visa Débito Sí No Sí Sí
7 Visa Prepago Sí No Sí Sí
8 Creditel Sí No Sí No
9 Créditos Directos Sí No Sí No
10 RedPagos Sí No No No
11 PassCard Sí No Sí Si
14 MasterCard Prepago Si No Sí Si

Bancos Emisores
La siguiente tabla identifica los Bancos Emisores que pueden ser detectados e informados.
IssuerBankId Banco Emisor País
1 Santander Uruguay
2 BBVA Uruguay
3 Itaú Uruguay
4 HSBC Uruguay

SiemprePago © 2019 Página 74 de 76

 5 Scotiabank Uruguay
6 OCA Uruguay
7 VISA Uruguay
8 MasterCard Uruguay
9 BROU Uruguay
10 Prex Uruguay
11 Pronto Uruguay
12 Midinero Uruguay

Tabla de Monedas (ISO-4217)

Esta tabla es parcial, indicando las monedas disponibles en la plataforma.
Para mayor información: https://es.wikipedia.org/wiki/ISO_4217

Código Divisa País que usa

UYU Peso uruguayo Uruguay
USD Dólar estadounidense Uruguay
PYG Guaraní Paraguay
DOP Peso dominicano Rep. Dominicana

Tabla de Países (ISO-3166-1)

Esta tabla es parcial, indicando los países disponibles en la plataforma.
Para mayor información: https://es.wikipedia.org/wiki/ISO_3166-1

Código País
UY Uruguay
PY Paraguay
DO República Dominicana

Tabla de Tipos de documentos

Código Documento
1 RUT
2 Cédula de Identidad

SiemprePago © 2019 Página 75 de 76

 3 Extranjero

Tabla de Tipos de Medios de Pago

Tipo Descripción
CreditCard Tarjeta de Crédito.
DebitCard Tarjeta de Débito.
PhysicalNetwork Red física de pagos.
PrePaid Tarjeta de Prepago.

Anexos
Anexo 1. Adquirentes de Uruguay
En los siguientes puntos se describen algunas particularidades y/o exigencias de los adquirentes en
Uruguay.

Visanet
Visanet exige que en el mensaje de compra se ingresen los datos de la dirección de facturación del
cliente. Los datos deben incluir como mínimo la calle, ciudad y país, los cuales deben ser enviados en
el campo BillingAddress del campo Customer, dentro del objeto Purchase.
Además, se debe enviar información de facturación que incluya al menos un número de factura dentro
del objeto DataUy.

Ejemplo de Purchase:

SiemprePago © 2019 Página 76 de 76

 Manejo del CVV.
Visanet exige la inclusión del CVV en la primera compra del cliente o en el registro del mismo.
Una vez hecho el registro y obtenido el Commerce Token, no es necesario solicitar el CVV en próximas
transacciones.

Notas:
o Se puede realizar compras en cuotas, siempre y cuando el Banco Emisor lo tenga
habilitado.
o Se puede realizar compras con Tarjetas de Débito, siempre y cuando el Banco Emisor lo
tenga habilitado

FirstData (MasterCard)
FirstData es el adquirente de MasterCard, Diners y Líder en Uruguay.

Manejo del CVV

FirstData exige que siempre se ingrese el CVV, aun cuando se tenga el Commerce Token, por lo tanto
se debe ejecutar el Flujo de Solicitud de Código de Verificación. Esta modalidad está marcada por
defecto, en caso de querer eliminarla, el comercio deberá negociarlo con First Data e informarnos.

Notas:
o Se puede realizar compras con Tarjetas de Débito, siempre y cuando el Banco Emisor lo
tenga habilitado

SiemprePago © 2019 Página 77 de 76

 Ocacard
Ocacard exige que en el mensaje de compra se incluya documento y tipo de documento del titular de
la tarjeta y teléfono.

Manejo del CVV

Ocacard exige que siempre se ingrese el CVV, aun cuando se tenga el Commerce Token, por lo tanto
se debe ejecutar el Flujo de Solicitud de Código de Verificación.

Creditel
Creditel exige que en el mensaje de compra se incluya documento y tipo de documento del titular de
la tarjeta.

PassCard
PassCard exige que en el mensaje de compra se incluya documento y tipo de documento del titular
de la tarjeta.

Manejo del CVV

PassCard exige que siempre se ingrese el CVV, aun cuando se tenga el Commerce Token, por lo tanto
se debe ejecutar el Flujo de Solicitud de Código de Verificación.

Anexo 2. Invocación al formulario de captura embebido

SiemprePago © 2019 Página 78 de 76

A continuación, se brinda una página HTML de prueba, la cual contiene la importación del formulario
de captura embebido

<!doctype html>
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<title></title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">

<script src="https://api.siemprepago.com/v1/Scripts/PWCheckoutNoModal.js?key={publicKey}"
type="text/javascript"></script>

</head>

<body>
<div id="iframeDiv" style="height: 410px; width: 300px; margin: auto;"></div>
<form id="commerce_form">
<input id="PWToken" type="hidden" />
</form>
</body>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script type="text/javascript">
PWCheckout.SetProperties(
{
"name": "Example S.A.",
"email": "test@test.com",
"button_label": "Pay #amount#",
"description": "",
"currency": "UYU",
"amount": "1",
"lang": "ESP",
"form_id": "commerce_form",
"checkout_card": "0",
"autoSubmit": "false",
"iframeId": "custom_iframe"
}
);

PWCheckout.Bind("tokenCreated", onTokenCreated);
OpenIframe();

SiemprePago © 2019 Página 79 de 76

 function onTokenCreated(token){
console.log(JSON.stringify(token));
}

function OpenIframe() {
var main_iframe = document.createElement("iframe");
var iframeDiv = $("#iframeDiv");
main_iframe.id = "custom_iframe";

// Append iframe to div

iframeDiv.append(main_iframe);

// iframe styles
main_iframe.setAttribute("frameborder", "0");
main_iframe.style.borderRadius = "10px";
main_iframe.style.height = "100%";
main_iframe.style.width = "100%";
main_iframe.style.zIndex = "9999";
main_iframe.style.display = "block";
main_iframe.scrolling = "no";

//Openl Iframe for Visa

PWCheckout.LoadIframe(1);
}
</script>
</html>

SiemprePago © 2019 Página 80 de 76