Tokenización & Autenticación

Preambulo

Esta guía describe los métodos y parámetros disponibles para la integración segura con la plataforma de “Card On File”, utilizada para procesar transacciones de comercio electrónico brindando una experiencia de pago mejorada, permitiendo solicitar los datos de la tarjeta, como si estuviera en su carrito de compra o aplicación móvil.

Además, solicitar los datos de tarjeta de sus clientes por medio de un registro y guardar únicamente un “token” el cual estará asociado a la tarjeta ingresada de forma segura en el formulario de check-out alojado en nuestra plataforma.

Conceptos

Api

La API 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.

URLBASE (Url Base)

El url base se refiere a la url donde se encuentra publicado el servicio, se menciona como ambiente a la ruta completa donde se referencia el url base y el api a utilizar, teniendo en cuenta que el url base puede cambiar de acuerdo al tipo de ambiente, producción o Certificacion. Ejemplo: ambiente/v1/nombreservicios

Versiones de API

Las versiones del servicio seran identificadas en la url especificada de cada ambiente, para consumir el servicio con cada nueva version, se debera referenciar la version de la siguiente manera.

Ejemplo: ambiente/v1 > Version 1.0

Autenticación

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 mediante el método HTTP Basic Authentication. Es decir que cada llamada a cualquiera de las operaciones expuestas deberá ser realizada utilizando la API Key correspondiente como el dato de “username” de Basic Authentication (sin necesidad de informar “password”).

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.

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

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.

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.
Una lista de errores que contiene todos los errores que pueden haber ocurrido. En caso de no haber errores la lista está vacía.
El codigo de respuesta del banco emisor.

Identificador Único

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

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 Librería

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 la 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.

Ejemplo:

html

<script
  src="{URLBASE}/v1/Scripts/Capture.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 alojada en CARDNET. No deberá ser descargada y usada localmente desde un servidor propio del comercio o desde una URL de un tercero no autorizado por CARDNET. Esto es importante por motivos de seguridad y para mantenerse siempre actualizados con las últimas modificaciones y correcciones realizadas sobre la misma.

Métodos Disponibles

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.

Propiedades:

name [Opcional, Longitud: Variable] - Nombre que aparece como título del Checkout.
email [Opcional, Longitud: Variable] - Email del cliente que se puede precargar.
image [Opcional, Longitud: Variable] - URL absoluta de la imagen a utilizarse dentro del Checkout. Imágenes aceptadas: jpg, jpeg, png.
button_label [Opcional, Longitud: Variable] - Texto a mostrarse en el botón de pago. El keyword #monto# es sustituido por el monto si este es informado.
description [Opcional, Longitud: Variable] - Descripción del pago a realizarse.
currency [Opcional, Longitud: 3] - Moneda del pago en formato ISO 4217 (Ejemplo: DOP).
amount [Opcional, Longitud: Variable] - Monto del pago (solo para informar al usuario, el monto real se informa server to server en la operación Purchase).
lang [Opcional, Longitud: 3] - Lenguaje de la interfaz (Ejemplo: ESP para Español).
form_id [Mandatorio, Longitud: Variable] - Identificador del formulario web donde se manejan los datos de la compra actual. Este dato es requerido ya que se utilizará para informar el token generado a partir de la tarjeta o medio de pago ingresado por el usuario.
checkout_card [Opcional, Boolean] - Si se establece en true, el Checkout pasa directamente a la captura de tarjeta.
empty [Opcional, Boolean] - Si esta propiedad se establece en true, la imagen y el título en la ventana del formulario se ocultarán.
autoSubmit [Opcional, Boolean] - Determina si el formulario se envía automáticamente al recibir el token del medio de pago. Valor por defecto es true.

Ejemplo

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: "DOP",
  amount: "1.00",
  lang: "ESP",
  form_id: "commerce_form",
  checkout_card: "1",
  autoSubmit: "true",
});

Proceso de Invocación Formulario Checkout

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á sesteado desde la librería JavaScript luego de obtener el valor del token.
html
```
<input type="hidden" name="PWToken" id="PWToken" />
```
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:
js
```
PWCheckout.AddActionButton("buttonId1", "buttonId2", "buttonId3");
```
Donde el parámetro buttonId se refiere al identificador del elemento elegido para desencadenar el proceso de pago. Ademas, se pueden asosciar multiples elementos en la misma llamaa, identificando cada de uno mediante su ID separados por coma. Al presionar el elemento asociado, se invocará el proceso de pago.
Luego la librería JavaScript se encargará de administrar el proceso de pago, mostrando al usuario el formulario donde se le solicitarán los datos de la tarjeta para realizar el pago. Una vez ingresados los datos, dicha información será tokenizada y obtenida por la librería PWCheckout. El valor del token generado, será insertado automáticamente en el campo oculto “PWToken”, y finalmente la librería JavaScript PWCheckout realizará el “submit” del formulario de pago.
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.

Ejemplo completo

html

<html>
  <head>
    <script
      type="text/javascript"
      src="https://labservicios.cardnet.com.do/servicios/tokens/v1/Scripts/PWCheckout.js?key=mfH9CqiAFjFQh_gQR_1TQG_I56ONV7HQ"
    ></script>
  </head>
  <body>
    <form id="shoppingcart_form">
      <p><button id="btnCheckout">ABRIR IFRAME DE CAPTURA</button></p>
      <p>
        <span class="itemName"
          >OTT TOKEN: <input type="text" id="PWTokenAux" name="PWTokenAux"
        /></span>
      </p>
    </form>
    <script>
      function OnTokenReceived(token) {
        // Validar si el token no es nulo o indefinido
        if (token && token.TokenId) {
          alert(token.TokenId);
          document.getElementById("PWTokenAux").value = token.TokenId;
        } else {
          console.error("Token no válido recibido.");
        }
      }

      function myCheckoutFunction(event) {
        event.preventDefault();

        try {
          // PublicAccountKey del comercio
          const myPublicKey = "mfH9CqiAFjFQh_gQR_1TQG_I56ONV7HQ";

          // Validar que myPublicKey no esté vacío
          if (!myPublicKey) {
            throw new Error("PublicAccountKey no puede estar vacío.");
          }

          // Este dato se obtiene haciendo un get del Customer.
          // Debe tener en cuenta que esto puede cambiar de acuerdo al ambiente.
          const customerUniqueId = "XXXXXXXXXXXXXXXXXXXX";

          // Validar que customerUniqueId no esté vacío
          if (!customerUniqueId) {
            throw new Error("CustomerUniqueId no puede estar vacío.");
          }

          // URL para capturas en ambiente de pruebas
          const captureUrl =
            "https://labservicios.cardnet.com.do/servicios/tokens/v1/Capture/";

          // Abrir el iframe de captura
          PWCheckout.OpenIframeCustom(
            `${captureUrl}?key=${myPublicKey}&session_id=${customerUniqueId}`,
            customerUniqueId,
          );
        } catch (error) {
          console.error("Error al abrir el Iframe:", error.message);
          alert(
            "Ha ocurrido un error al iniciar el Checkout. Por favor, intente nuevamente.",
          );
        }
      }

      // Vincular evento tokenCreated con la función OnTokenReceived
      PWCheckout.Bind("tokenCreated", OnTokenReceived);

      // Establecer propiedades del Checkout
      PWCheckout.SetProperties({
        name: "Demo Test.",
        email: "gpigni@pagosweb.com.uy",
        //"image": "http://mywebsitedomain.com/images/logocheckout.png",
        "button-label": "Pagar #monto#",
        description: "Checkout Creditel Test.",
        currency: "$",
        amount: "100",
        lang: "ESP",
        form_id: "shoppingcart_form",
        checkout_card: 1,
        autoSubmit: "false",
        empty: "true",
      });

      // Agregar evento al botón de Checkout
      const btnCheckout = document.getElementById("btnCheckout");
      btnCheckout.addEventListener("click", myCheckoutFunction);
    </script>
  </body>
</html>

Flujos Transaccionales

A continuación, se describen los flujos para autorizar una compra a través de la plataforma.

Existen 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.

Usuarios Anónimos

Proceso de Transacción para Usuarios Anónimos

Desde el carrito de compra del comercio invocar el “Formulario de Checkout” a través de la librería JavaScript de la plataforma de CARDNET. Este formulario se muestra dentro de un iFrame de su propia página y solicita los datos de tarjeta.
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 “One Time Token” y tiene validez por una única vez y está vigente durante 10 minutos.
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: {URLBASE}/v1/api/purchase adjuntando el objeto Purchase que contendrá el token y otros datos de la transacción.

json

{
  "TrxToken": "OT_01_kYv0qTHckRiZ4wjCz5NguZRuwFLSIrQc4jiYpVJ8SzQ_",
  "Order": "17030613595101621fb",
  "Amount": 123456,
  "Currency": "DOP",
  "Capture": true
}

Flujo De Transacción Con Usuarios Anónimos

Usuarios Registrados

Proceso de Transacción para Usuarios Registrados

Registro de Usuarios:

Para poder operar con usuarios registrados, se debe primero registrar dicho usuario en el Sistema de Pagos, para ello se deberá llamar a la interfaz de Customers informando los datos del usuario que se desea registrar. Ver Referencia Customers.
Como resultado del registro de dicho usuario, se recibirá como respuesta un objeto Customer, el cual se deberá procesar y almacenar como mínimo el CustomerId, con el cual se podrán realizar otras operaciones sobre dicho Customer registrado.

Registro de Medios de Pago para un Usuario Registrado:

El usuario (debidamente autenticado en la web del comercio) solicita el registro de un medio de pago nuevo en su cuenta dentro del comercio.
El Browser navega hacia la página de registro de medios de pago del comercio.
El comercio, debe acceder a la cuenta del usuario realizando la llamada (GET) al servicio de Customer, informando el CustomerId que debió previamente haber almacenado (tal cual lo indica el flujo de Registro de Usuarios).
El objeto Customer devuelto, contendrá la información conocida del usuario, incluyendo los Medios de Pago que pueden haber sido registrados previamente. Además, este objeto Customer informa un "CaptureURL" y un "UniqueID" que debe ser utilizado luego para mostrarle al usuario la interfaz de captura de datos de la tarjeta de pago.
El comercio, deberá presentar al usuario la pantalla de registro de Medios de Pago, donde por ejemplo podrá disponer un botón de tipo "Agregar nuevo Medio de Pago" el cual iniciará el proceso de registro.
El cliente presiona este botón (o el método elegido por el comercio) para iniciar el método de captura de la tarjeta de pago.
La interfaz del sitio del comercio deberá abrir y mostrar al usuario la página de captura de tarjetas. Para esto puede por ejemplo utilizar el método OpenIframeCustom de la librería javascript PWCheckout, a la cual le deberá informar 2 parámetros:
- URL: donde deberá concatenar el dato CaptureURL obtenido en el paso 4, con la clave pública del comercio y el UniqueID (también obtenido en el paso). El formato del parámetro URL es el siguiente: {CaptureURL}?key={publicKey}&session_id={UniqueID}
- UniqueID: como segundo parámetro de la función, se deberá informar nuevamente el UniqueID obtenido en el paso 4.
El cliente en este paso deberá interactuar con la interfaz de captura de tarjeta, ingresando los datos de la misma.
El formulario de captura enviará la información ingresada por el usuario directamente a los sistemas de tokenización del Sistema de Pagos, donde se almacenarán dichos datos y se generará un Token para representar dicha tarjeta.
Una vez que el proceso de capturar la tarjeta del usuario haya finalizado, la librería PWCheckout recibirá una notificación, la cual puede ser manejada por la web del comercio, suscribiéndose al evento "tokenCreated", el cual se desencadenará en el momento de que el token esté listo.
Cuando el comercio recibe la notificación de que el Medio de Pago ha sido correctamente registrado, deberá volver a llamar (GET) al servicio de Customer de la API para obtener una versión actualizada de la información del dicho usuario.

Como respuesta, el objeto Customer devuelto tendrá todos los medios de pago del usuario, incluyendo el nuevo recién registrado. Con esta información el comercio deberá actualizar el perfil del usuario en su sistema, almacenando el Token registrado y los datos asociados al mismo. (Ej.: PaymentProfileId, Brand, Expiration, Last4, etc.).

Además, deberá verificar que el objeto PaymentProfile (dentro del Customer recibido) podrá estar marcado como deshabilitado (Enabled=false) por lo que para que dicho perfil (Token) pueda ser utilizado, deberá ser activado.

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

json

{
  "Response": {
    "CustomerId": 50329,
    "Created": "2018-01-24T12:41:35.503",
    "CommerceCustomerId": "test@email.com",
    "Owner": "Commerce",
    "Email": "test@email.com",
    "Enabled": true,
    "ShippingAddress": null,
    "BillingAddress": null,
    "Plans": null,
    "AdditionalDate": null,
    "PaymentProfiles": [
      {
        "PaymentProfileId": 50330,
        "PaymentMediaId": 2,
        "Brand": "MasterCard",
        "IssuerBank": null,
        "Type": "CreditCard",
        "Token": "CT__3RIuqDhQmyeg7RUCF_xdtZe1Y5Ua2zXniwnDMVFoTWs_",
        "Expiration": "202211",
        "Last4": "0001",
        "Enabled": false
      }
    ],
    "CaptureURL": "http://api.localsiemprepago.com/Capture",
    "UniqueID": "UI_4e9ab4f2-d007-4663-815a-6a78962238e3",
    "FirstName": "Test",
    "LastName": "Account",
    "DocNumber": "12345678",
    "DocumentTypeId": 2,
    "PhoneNumber": null
  },
  "Errors": []
}

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

Proceso de Activación de Medio de Pago

El comercio deberá mostrarle al usuario los distintos Medios de Pago registrados por él, indicando en los casos que corresponda que dicho medio de pago está deshabilitado y que se necesita "Activar".
El usuario selecciona la opción de activar este Medio de Pago.
El comercio deberá presentarle al usuario un campo donde el mismo pueda ingresar el código de activación que oportunamente recibió (el método de entrega de dicho código queda fuera de este alcance).
Una vez que el comercio obtuvo el código ingresado por el usuario, se deberá realizar una llamara a la operación "Activate" de la API de Customer del Sistema de Pago, informando el CustomerId del usuario registrado, y enviando la información del Token que se desea activar junto con el código de activación que fue obtenido.
Como respuesta a este proceso de activación, la API retornará nuevamente el objeto Customer completo, con los datos actualizados, incluyendo el perfil de pago habilitado en caso de que el proceso haya sido exitoso. Tener en cuenta que en caso de errores, estos se informarán como parte de la respuesta del servicio.

Flujo de Clientes Registrados

Proceso de registro de Token

Flujo de Tokenización Directa

Este flujo aplica para cliente que poseen una base de datos de usuarios con tarjetas registradas que ya fueron autenticados, sin embargo, los números de tarjetas se encuentran almacenados en sus bases de datos. Además, el comercio no desea realizar nuevamente un proceso de autenticación de tarjeta para no afectar su experiencia de usuario. Por lo tanto, para estos casos, los comercios podrán tokenizar sus tarjetas enviando la información a través de un API de forma directa sin necesidad de interactuar con el tarjetahabiente. A continuación, se describe el flujo.

Diagrama de Secuencia de Tokenización Directa

Proceso de registro de Token

Proceso de Registro de Medio de Pago vía API

El Comercio envía los datos del Customer a través de la API ya existente y recibe como respuesta los datos del Customer persistido en el card on file.
Una vez que el Customer es creado, debe guardar el valor de CustomerId de forma tal que pueda utilizarlo en los siguientes pasos.
Luego, para cada medio de pago que se desea registrar, se deberán ejecutar los siguientes pasos:
- a. El Comercio envía la información del medio de pago a través de la API de Tokenización Directa, incluyendo en esa información el CustomerId obtenido en el paso 2.
- b. El Sistema procesa y almacena los datos de forma segura, asociando estos datos al Customer generado en el paso 1.
El Sistema responde un identificador (Token) que puede ser utilizado por el Comercio para generar transacciones sin necesidad de conocer los datos de la tarjeta.

Api de servicio tokenización directa

URL: {URLBASE}/secure/api/Token?commerceKey={PrivateAccountKey}

Método	Tipo de API	Autenticación
`POST`	`Pública`	`N/A`

QueryParam: PrivateAccountKey (String) - Clave privada de la Cuenta de Comercio, utilizada para la autenticación de la solicitud.

Body: TokenRequest (Objeto) - Objeto que contiene la información sensible de la tarjeta de pago del cliente.

Parametros de respuesta:

Token - Objeto que contiene la información del Token generado.
Errors - Lista de errores que se pueden haber generado.

Ejemplo de mensajeria de Tokenización

A continuación, se ejemplifica la llamada al Servicio de Tokenización y la correspondiente respuesta.

bash

curl -X POST {URLBASE}/secure/api/Token?commerceKey={PrivateAccountKey} \
-H "Content-Type: application/json" \
-d '{
  "Email": "email@domain.com",
  "Pan": "4111********1111",
  "CVV": "123",
  "Expiration": "11/19",
  "Titular": "Nombre Titular",
  "CustomerId": 123456
}'

Operaciones Permitidas

La plataforma de Card On File permitirá a los comercios realizar diferentes tipos de operaciones que pueden ser realizadas durante todo el proceso de compra.

Listado de objetos y posibles operaciones:

Customer
- Create Customer (POST) - Registro de Cliente
- Consultar (GET)
- Actualizar (POST)- Activar perfile de pago
Purchase
- Crear (POST) - Realizar compra
- Consultar (GET) - Consulta de compra
- Lista (GET) - Listar Compras
- Actualizar (POST) - Anular compra
Customer Activation
- Actualizar (POST) - Activar medio de pago
PaymentProfile
- Actualizar (POST) - Permite activar o desactivar un medio de pago
- Remover (POST) - Permite borrar medio de pago

Directivas de 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: {URLBASE}/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: {URLBASE}/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: {URLBASE}/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 {URLBASE}/v1/api/{object-name}?{query-parameters}

Nomenclatura de Objetos

Todos los objetos están descriptos en tablas con el siguiente formato:

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

Objeto Token

El objeto Token es utilizado para informar el token generado junto con otra información relativa al medio de pago utilizado por el cliente.

TokenId (String) [Solo Lectura] - Es el token generado.
Created (TimeStamp) [Solo Lectura] - Fecha y hora de creación del token
Type (String) [Solo Lectura] - Tipo de token generado, valores posibles: “OneTime” “Commerce”
Brand (String) [Solo Lectura] - Marca de la tarjeta o medio de pago utilizado
IssuerBank (String) [Solo Lectura] - Banco emisor de la tarjeta (en caso que pueda ser determinado).
Owner (String) [Solo Lectura] - Nombre del tarjetahabiente
Last4 (Numeric[4]) [Solo Lectura] - Últimos cuatro dígitos de la tarjeta.
CardExpMonth (Numeric[2]) [Solo Lectura] - Mes de expiración de la tarjeta
CardExpYear (Numeric[2]) [Solo Lectura] - Año de expiración de la tarjeta
URL (String) [Solo Lectura] - URL donde se puede acceder a la información del Token (ej. {URLBASE}/v1/api/token/{token-id}).

Objeto Purchase

El objeto Purchase es utilizada para la acción de autorización, anulación o consulta de compras.

PurchaseId (Numeric) [Solo Lectura] - Identificador de la compra.
Created (TimeStamp) [Solo Lectura] - Fecha y hora del momento de la creación de la 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) [Mandatorio] - Token que identifica la tarjeta del cliente
Order (String) [Mandatorio] - Número de orden, generado por el comercio.
Transaction (Transaction) [Solo Lectura] - Contiene la información que resulta de la transacción realizada contra el medio de pago (por ej: código de respuesta, número de autorización). Ver objeto Transaction.
Capture (Boolean) [Opcional, TRUE] - Establece si la compra se debe realizar en uno o dos pasos. 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 final a través de las llamadas commit (confirmar) y rollback (anular). Si es true, la transacción queda autorizada y capturada (confirmada).
Amount (Amount) [Mandatorio] - Monto total de la compra. El valor debe ser mayor a cero.
Currency (String[3]) [Mandatorio] - Moneda de la compra, de acuerdo a ISO-4217 (códigos alfanuméricos). Este parametro tambien es utilizado para el envio de transacciones de puntos agregando las iniciales (PTS) como valor de moneda.
Tip (Amount) [Opcional] - Propina.
Installments (Numeric[3]) [Opcional, 1] - Cantidad de cuotas de la compra.
Description (String[50]) [Opcional] - Descripción opcional de la compra.
Customer (<Customer>) [Opcional] - Información del cliente que realiza el pago. Algunos medios de pago pueden requerir información adicional del cliente para poder tramitar la autorización.
RefundList (List <RefundData>) [Solo Lectura] - Lista de devoluciones realizadas a la compra.
PlanID (String[50]) - Reservado.
UniqueID [Opcional] - Identificador único de la compra. 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).
AdditionalData (String[300]) [Opcional] - Información adicional que el comercio puede agregar 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 (String) [Opcional] - User Agent del cliente que utiliza el servicio, en la 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 (String) [Opcional] - IP del cliente que utiliza el servicio.
DataDo (CountryDataDo) [Mandatorio] - Datos específicos para la Rep. Dominicana. Ver la definición del objeto CountryDataDo. CountryDataDo.
CommerceAction (CommerceAction) [Solo Lectura] - Utilizado para indicar al comercio una acción que 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.
URL (String) [Solo Lectura] - URL donde se puede acceder a la información de la Compra. Ej: {URLBASE}/v1/api/purchase/{PurchaseID}.

API Purchase

Crear nueva compra

URL: {URLBASE}/v1/api/purchase

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Body Params:

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

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (Purchase) - Objeto que contiene la información actualizada de la compra realizada. Se le asigna el PurchaseID que será utilizado como identificador de la compra a partir de este momento.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Obtener información de compra

URL: {URLBASE}/v1/api/purchase/{PurchaseID}

Método	Tipo de API	Autenticación
`GET`	`Pública`	`PrivateAccountKey`

Path Params:

PurchaseID (Numeric) - Identificador de la compra.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (Purchase) - Objeto que contiene la información de la compra solicitada.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Anular compra

URL: {URLBASE}/v1/api/purchase/{PurchaseID}/refund

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

PurchaseID (Numeric) - Identificador de la compra.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (Purchase) - Objeto que contiene la información de la compra actualizada.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Confirmar compra pre-autorizada

URL: {URLBASE}/v1/api/purchase/{PurchaseID}/commit

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

PurchaseID (Numeric) - Identificador de la compra.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (Purchase) - Objeto que contiene la información de la compra actualizada.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Listar compra

URL: {URLBASE}/v1/api/purchase

Este método permite obtener una lista de compras de acuerdo a los filtros que se pueden establecer en los parámetros

Método	Tipo de API	Autenticación
`GET`	`Pública`	`PrivateAccountKey`

Parámetros:

CustomerId (Numeric) - Identificador del cliente que realizó la compra.
From (Date) - Fecha inicial del filtro, Formato: yyyyMMdd. Default: Fecha actual.
To (Date) - Fecha final del filtro, Formato: yyyyMMdd. Default: Fecha actual.
PaymentMediaId (Numeric) - Identificador del Medio de Pago con el que se realizaron las compras.
Authorized (Boolean) - Si el valor es true devuelve solo las compras que hayan finalizado exitosamente. Default: false
OrderNumber (Numeric) - Número de orden del comercio.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (List <Purchase>) - Lista de Compras que coinciden con los filtros de búsqueda.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Objeto Customer

El objeto Customer es utilizada para la acción de creación y mantenimiento de los clientes.

CustomerId (Numeric) [Solo Lectura] - Identificador del cliente.
CommerceCustomerId (String) [Opcional] - Identificador del cliente en el comercio. Este valor es generado y utilizado internamente por el comercio para identificar al cliente dentro de la plataforma.
Created (TimeStamp) [Solo Lectura] - Fecha y hora del momento de la creación del cliente. Este campo está presente en la respuesta a consultas. No se incluye o valida en la creación o actualizaciones del objeto.
Owner (String) [Solo Lectura] - Determina si el usuario fue registrado por el comercio, a través de Cardnet o anónimo. Posibles valores: “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.
FirstName (String) [Opcional] - Nombre del cliente.
LastName (String) [Opcional] - Apellido del cliente.
Email (String) [Mandatorio] - Email del cliente.
PhoneNumber (String) [Opcional] - Teléfono de contacto del cliente.
Enabled (Boolean) [Opcional, Default: true] - Indica si el usuario está habilitado o no a operar.
ShippingAddress (<Address>) [Opcional] - Información de dirección de entrega (si está disponible).
BillingAddress (<Address>) [Opcional] - Información de dirección de facturación (si está disponible y el usuario habilitó que se compartiera esa información).
Plans [Opcional] - Reservado.
AdditionalData - Lista de datos de tipo “Clave:Valor” para almacenar información extra.
PaymentProfiles (List <PaymentProfile>) [Solo Lectura] - Lista de objetos PaymentProfile con información de los medios de pago registrados por el Customer.
CaptureURL (String) Opcional - URL de captura de datos de tarjeta (es la URL que se debe abrir en un iframe para iniciar el proceso de captura de datos sensibles). Solo es válida para Customer de tipo “Commerce”.
UniqueID [Solo Lectura] - Identificador único temporal utilizado para registrar medios de pago externos. Cada vez que se solicita la información del Customer se genera un identificador nuevo.
URL (String) [Solo Lectura] - URL donde se puede acceder a la información del Cliente (ej. /v1/customer/{CustomerId}).
DocumentTypeId (Numeric) [Opcional] - Tipo de documento del cliente.
DocNumber (String) [Opcional] - Documento del cliente.

API Customer

Crear nuevo cliente

URL: {URLBASE}/v1/api/customer

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Parámetros:

Customer (<Customer>) - Objeto que contiene la información del cliente.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información del Cliente actualizada. Se asigna el valor de CustomerId.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Actualizar datos del cliente

URL: {URLBASE}/v1/api/customer/{CustomerId}/update

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

CustomerId (Numeric) - Identificador del cliente.

Body:

Customer (<Customer>) - Objeto que contiene la información del cliente.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información actualizada del Cliente.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Obtener datos del cliente

URL: {URLBASE}/v1/api/customer/{CustomerId}

Método	Tipo de API	Autenticación
`GET`	`Pública`	`PrivateAccountKey`

Path Params:

CustomerId (Numeric) - Identificador del cliente.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información actualizada del Cliente.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Activar un perfil de pago

URL: {URLBASE}/v1/api/customer/{CustomerId}/activate

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

CustomerId (Numeric) - Identificador del cliente.

Body:

Activation (<CustomerActivation>) - Objeto que contiene la información relativa al perfil que se desea activar y el código de activación relacionado.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información actualizada del Cliente.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Objeto PaymentProfile

Este objeto es obtenido luego de ingresar un medio de pago, en este se informan los datos de un medio de pago registrado por el cliente al que está asociado, o sea el número de la tarjeta. La información ser obtenida a través de la consulta del cliente.

PaymentProfileId (Numeric) [Solo Lectura] - Identificador del perfil de pago registrado para el Customer.
PaymentMediaId (Numeric) [Solo Lectura] - Identificador del medio de pago asociado al perfil.
Brand (String) [Solo Lectura] - Nombre asociado a la marca de la tarjeta de pago, por ejemplo “VISA”.
IssuerBank (String) [Solo Lectura] - Identificador del Banco Emisor. (en caso que pueda ser determinado)
Type (String) [Solo Lectura] - Tipo de medio de pago, por ejemplo “CreditCard”
Token (String) [Solo Lectura] - Dato que representa al medio de pago registrado sin exponer los datos sensibles del mismo. Este dato será utilizado para realizar transacciones de pago mediante el medio de pago registrado.
Expiration (String) [Solo Lectura] - Fecha de expiración del medio de pago (si corresponde). Formato: yyyyMM
Last4 (Numeric) [Solo Lectura] - Últimos 4 dígitos de la tarjeta de pago (si corresponde).
Enabled Boolean [Solo Lectura] - Determina si el perfil se encuentra habilitado para realizar pagos.

API PaymentProfile

Actualizar PaymentProfile

URL: {URLBASE}/v1/api/customer/{CustomerId}/PaymentProfileUpdate

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

CustomerId (Numeric) - Identificador del cliente.

Body:

PaymentProfileID (Numeric) - Identificador del perfil de pago a modificar.
Expiration (String) - Fecha de expiración de la tarjeta a modificar.
Enable (Boolean) - Valor para actualizar estado del medio de pago, donde true es activo y false es inactivo.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información actualizada del Cliente.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Eliminar PaymentProfile

URL: {URLBASE}/v1/api/customer/{CustomerId}/PaymentProfileDelete

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Path Params:

CustomerId (Numeric) - Identificador del cliente.

Body:

PaymentProfileID (Numeric) - Identificador del perfil de pago a modificar.

Formato de Respuesta:

HTTP Code - Código HTTP.
Response (<Customer>) - Objeto que contiene la información actualizada del Cliente.
Errors (List <Error>) - Lista de errores que se pueden haber generado.

Objeto CustomerActivation

CustomerActivation es obtenido luego de ingresar el código de activación, se utiliza para informar los datos de activación de un perfil de pagos registrado por el cliente.

Token (String) [Mandatorio] - Identificador del Token asociado al perfil que se desea activar.
ActivationCode (String) [Mandatorio] - Código de activación recibido por el cliente, asociado al perfil que se desea activar.

Objeto 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. Además, va asociado a los diferentes estados por los cuales puede pasar una transacción (autorizada, anulada, etc.)

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

Los campos que forman el <TransactionStep> son:

TransactionID – Identificador de la Transacción.
Created – TimeStamp del momento de creación de la Transacción.
Status – Estado de la Transacción al momento de la consulta.
Steps – Lista de “estados intermedios” desde que se creó la transacción. Es una lista de objetos <TransactionStep>.

Objeto Address

Este objeto se utiliza para obtener los datos de la dirección de un cliente tanto de envió como dirección de facturación. (Shipping Address o Billing Addres).

AddressID (Numeric) [Mandatorio] - Identificador de la dirección.
AddressType (String) [Opcional] - Tipo de Dirección (billing, shipping, customer, etc.).
Country (String) [Opcional] - País.
State (String) [Opcional] - Estado / Departamento / Provincia.
City (String) [Opcional] - Ciudad.
AddressDetail (String) [Mandatorio] - Calle, número, etc.
PostalCode (String) [Opcional] - Código postal.

Objeto TransactinStep

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

Step (String) [Solo Lectura] - Nombre del paso ejecutado.
Created (TimeStamp) [Solo Lectura] - Fecha y hora del momento de ejecución del paso.
Status (TransactionStatus) [Solo Lectura] - Estado final luego de la ejecución del paso.
ResponseCode (String) [Solo Lectura] - Código de respuesta obtenido luego de la ejecución del paso actual. Contiene por ejemplo el código de respuesta del medio de pago.
ResponseMessage (String) [Solo Lectura] - Mensaje de respuesta asociado al ResponseCode.
Error (String) [Condicional] - Código de error generado (si corresponde) en la ejecución del paso.
AuthorizationCode (String) [Solo Lectura] - Código de aprobación devuelto por el medio de pago.
UniqueId (String) [Solo Lectura] - Identificador único de la llamada (request) que desencadenó la ejecución de este paso. Utilizado para relacionar operaciones Refund y Rollback.

Objeto CountryDataDo

Objeto utilizado para obtener datos de la República Dominicana (Código ISO-3166 = DO).

Invoice (String) [Mandatorio] - Número de factura asociado a la venta.
Tax (Amount) [Opcional] - Monto de impuestos pagados.

Objeto 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 para poder reaccionar a estas llamadas.

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

Servicio WebHook del Comercio

El comercio podrá implementar un servicio para recibir y procesar notificaciones enviadas desde el sistema.

Este servicio es necesario en algunos flujos de transacciones donde parte del proceso no puede ser realizado de forma sincrónica, por lo que el estado final de dicha transacción será informado asincrónicamente una vez que la plataforma puedan responder al comercio. El comercio deberá informar a CARDNET la URL en la que será publicado dicho servicio, de forma de que esta sea configurada en nuestros sistemas para el envío de las notificaciones.

Especificaciones del servicio WebHook

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

URL: Debe especificarlo el comercio

Método	Tipo de API	Autenticación
`POST`	`Pública`	`PrivateAccountKey`

Body:

Notification (<Notification>) - Objeto que contiene la información de notificación enviada. Formato: JSON

Formato de Respuesta:

HTTP Code - Código HTTP.

La implementación de dicho 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 como header de autenticación en el mismo formato (Basic Authentication) que el comercio debe enviar en cada uno de los requests.
Deberá responder solo un código HTTP, donde:
- Si se responde el código 200 (OK), SiemprePago asumirá que el procesamiento de la notificación fue exitoso.
- Si se responde cualquier otro código distinto a 200, CARDNET 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.

Códigos HTTP

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 Allowed - Request por método incorrecto (ej. GET en lugar de POST).
408 Request Timeout - No se pudo completar el pedido en el tiempo máximo configurado.
500 Internal Server Error - Ocurrió un error en el servicio.
503 Service Unavailable - El servicio está en mantenimiento o experimentando problemas de acceso.

Códigos de Error

TK… - Errores servicio de Tokenización.

TK001 INVALID_CARD_PAN - El número de tarjeta ingresado es incorrecto.
TK002 INVALID_CVV - El número de CVV ingresado es incorrecto.
TK003 INVLALID_EXPIRATION_DATE - La fecha de vencimiento de la tarjeta es incorrecta.
TK004 INVALID_SESSION_IDENTIFIER - Se envió un identificador de sesión inválido en una solicitud de token.
TK005 INVALID_EMAIL - Se ingresó un email con formato incorrecto.
TK006 EXPIRED_TOKEN - El token (de tipo One-Time) ya fue utilizado o está expirado.
TK007 INVALID_PAYMENT_MEDIA - Medio de pago no coincide con el esperado.
TK008 ISSUER_BANK_NOT_MATCH - Banco emisor no coincide con el esperado.
TK009 INVALID_ACTIVATION_CODE - Código de activación de Token inválido.
TK010 INVALID_COMMERCE_TOKEN - Token de comercio inválido.
TK011 CUSTOMER_NOT_FOUND - El cliente especificado no es válido.
TK012 TOKEN_ACTIVATION_ERROR - Error en la activación del token.
TK013 TOKEN_REGISTRY_ERROR - Error en el proceso de registro con el Adquirente.
TK014 TOKEN_PAYMENT_MEDIA_DISABLED - Medio de pago deshabilitado.
TK999 UNKNOWN_ERROR - Error desconocido, el detalle puede especificar el error real.

`PR...` Errores servicio de Purchase

PR001 INVALID_TOKEN - El token informado es inválido, está vencido o no corresponde al comercio.
PR002 INVALID_ORDER - El número de órden es inválido.
PR003 INVALID_AMOUNT - El monto informado es inválido.
PR004 INVALID_CURRENCY - La moneda informada es inválida.
CODE NAME - DETAILS.

`CS…` Errores servicio Customers.

CS001 INVALID_EMAIL - El email informado es inválido.
CS002 INVALID_ADDRESS_TYPE - Tipo de dirección inválida.
CS003 INVALID_CUSTOMER_IDENTIFIER - Identificador de cliente inválido.
CS004 TOKEN_CREATION_FAILED - Error en la creación del Token.
CS005 EMAIL_ALREADY_EXISTS - Email ya registrado.
CS006 INVALID_ADDITIONAL_DATA - AdditionalData mal formado, debe ser clave:valor separados por punto y coma (😉.
CS007 INVALID_CUSTOMER_DOCUMENT - El Documento especificado es inválido.
CS008 INVALID_CUSTOMER_DOCUMENT_TYPE - El Tipo Documento especificado es inválido.
CS009 TOKEN_ALREADY_EXISTS - El ComerceToken para este medio de pago ya existe.
CS010 INVALID_PAYMENT_PROFILE - El PaymentProfile informado es inválido.
CS011 INVALID_PAYMENT_PROFILE_IDENTIFIER - El identificador del PaymentProfile es inválido.
CS012 PROFILE_MUST_BE_ACTIVATED_FIRST - El PaymentProfile aún no ha sido activado.

`TR…` - Errores servicio Transactions

TR001 COMMINICATION_ERROR - Error de comunicación con el servicio adquirente.
TR002 INVALID_TRANSACTION_STATE - La transacción asociada a la compra se encuentra en un estado que no permite la ejecución de la operación actual. 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_ACCOUNT_PROBLEM - Problemas con la cuenta de comercio en el Adquirente.
TR004 ACQUIRER_PROXY_ERROR - Error el enviar transacción al Adquirente mediante Proxy.
TR005 ACQUIRER_PROBLEM - Error interno del Adquirente.
TR006 ACQUIRER_DUPLICATED_ORDER - Número de orden duplicada en el Adquirente.
TR007 INVALID_PAYMENT_MEDIA - Error con algún dato del medio de pago (número de tarjeta, código de verificación y/o fecha de expiración).
TR008 COMMIT_AMOUNT_GREATER_THAN_AUTHORIZED - El monto que se intenta confirmar es superior al autorizado previamente.
TR009 ACQUIRER_UNKNOWN_ERROR - Error desconocido de Adquirente.
TR999 UNKNOWN - Error no determinado al ejecutar la transacción.

`ER…` Errores genéricos

ER999 UNKNOWN - No determinado.

Códigos de Respuesta de la transacción

Este es el código de respuesta recibo del banco el cual indica si la transacción fue aprobada o rechazada. Este se encuentra en el objeto TransactionStep.

00 Aprobada
01 Llamar al Banco
02 Llamar al Banco
03 Comercio Invalido
04 Rechazada
05 Rechazada
06 Error en Mensaje
07 Tarjeta Rechazada
08 Llamar al Banco
09 Request in progress
10 Aprobación Parcial
11 Approved VIP
12 Transaccion Invalida
13 Monto Invalido
14 Cuenta Invalida
15 No such issuer
16 Approved update track 3
17 Customer cancellation
18 Customer dispute
19 Reintentar Transaccion
20 No tomo accion
21 No tomo acción
22 Transaccion No Aprobada
23 Transaccion No Aceptada
24 File update not supported
25 Unable to locate record
26 Duplicate record
27 File update edit error
28 File update file locked
30 File update failed
31 Bin no soportado
32 Tx. Completada Parcialmente
33 Tarjeta Expirada
34 Transaccion No Aprobada
35 Transaccion No Aprobada
36 Transaccion No Aprobada
37 Transaccion No Aprobada
38 Transaccion No Aprobada
39 Tarjeta Invalida
40 Funciono no Soportada
41 Transacción No Aprobada
42 Cuenta Invalida
43 Transacción No Aprobada
44 No investment account
51 Fondos insuficientes
52 Cuenta Invalidad
53 Cuenta Invalidad
54 Tarjeta vencida
56 Cuenta Invalidad
57 Transaccion no permitida
58 Transaccion no permitida en terminal
60 Contactar Adquirente
61 Excedio Limte de Retiro
62 Tarjeta Restringida
65 Exedio Cantidad de Intento
66 Contactar Adquirente
67 Hard capture
68 Response received too late
75 Pin excedio Limte de Intentos
77 Captura de Lote Invalida
78 Intervencion del Banco Requerida
79 Rechazada
81 Pin invalido
82 PIN Required
85 Llaves no disponibles
89 Terminal Invalida
90 Cierre en proceso
91 Host No Disponible
92 Error de Ruteo
94 Duplícate Transaction
95 Error de Reconciliación
96 Error de Sistema
97 Emisor no Disponible
98 Excede Limete de Efectivo
99 CVV or CVC Error response

Tipos de datos

Datos Básicos

`String`

Es una cadena de caracteres que puede contener cualquier carácter 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	Codificacion
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.
ttt indica los milisegundos.

Valor	Codificacion
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

`TransactionStatus`

Indica el estado final de la transacción.

TransactionStatusId	TransactionStatus
1	Approved
2	Pending
3	Preauthorized
4	Rejected

`ActionType`

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

Posibles valores:

Actiontype	Accion
1	Redirect

`ResourceType`

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

Posibles valores:

ResourceType	Resource
1	Purchase
2	Customer

`Medios de Pago`

La siguiente tabla identifica los medios de pago aceptados, incluyendo las funcionalidades soportadas por cada uno.

PaymentMediaId	Medio de Pago	Compra	Pre autorización
1	Visa	Si	No
2	MasterCard	Si	No
3	American Express	Si	No

Datos de Ambientes

Datos ambiente de pruebas

Para realizar pruebas se deben utilizar los siguientes URL:

API Servicios: https://labservicios.cardnet.com.do/servicios/tokens/v1/api/objeto donde objeto se refiere al nombre del objeto que se desea consultar.
API Tokenización Directa:
- https://labservicios.cardnet.com.do/servicios/tokens/Secure/api/Token?commerceKey=llaveprivada
Formulario de Captura:
- https://labservicios.cardnet.com.do/servicios/tokens/v1/Capture
- https://labservicios.cardnet.com.do/servicios/tokens/v1/Scripts/PWCheckout.js
Private Account Key: 9kYH2uY5zoTD-WBMEoc0KNRQYrC7crPRJ7zPegg3suXguw_8L-rZDQ__
Public Account Key: mfH9CqiAFjFQh_gQR_1TQG_I56ONV7HQ

Nota: Estos datos deben ser utilizados únicamente para pruebas de los servicios. Una vez que su aplicación sea certificada por los técnicos de CARDNET, deberá solicitar los datos para procesar en el ambiente de producción.

Datos ambiente de producción

Para realizar pruebas se deben utilizar los siguientes URL:

API Servicios: https://servicios.cardnet.com.do/servicios/tokens/v1/api/objeto donde objeto se refiere al nombre del objeto que se desea consultar.
Formulario de Captura:
- https://servicios.cardnet.com.do/servicios/tokens/v1/Capture
- https://servicios.cardnet.com.do/servicios/tokens/v1/Scripts/PWCheckout.js
API Tokenización Directa:
- https://servicios.cardnet.com.do/servicios/tokens/Secure/api/Token?commerceKey=llaveprivada

Tokenización & Autenticación ​

Preambulo ​

Conceptos ​

Api ​

URLBASE (Url Base) ​

Versiones de API ​

Autenticación ​

PublicAccountKey ​

PrivateAccountKey ​

Tokenización ​

Formato de Respuesta ​

Identificador Único ​

Formulario de Checkout ​

Importación de Librería ​

Métodos Disponibles ​

SetProperties ​

Propiedades: ​

Ejemplo ​

Proceso de Invocación Formulario Checkout ​

Ejemplo completo ​

Flujos Transaccionales ​

Usuarios Anónimos ​

Proceso de Transacción para Usuarios Anónimos ​

Flujo De Transacción Con Usuarios Anónimos ​

Usuarios Registrados ​

Proceso de Transacción para Usuarios Registrados ​

Registro de Usuarios: ​

Registro de Medios de Pago para un Usuario Registrado: ​

Proceso de Activación de Medio de Pago ​

Flujo de Clientes Registrados ​

Flujo de Tokenización Directa ​

Diagrama de Secuencia de Tokenización Directa ​

Proceso de Registro de Medio de Pago vía API ​

Api de servicio tokenización directa ​

Parametros de respuesta: ​

Ejemplo de mensajeria de Tokenización ​

Operaciones Permitidas ​

Directivas de Operaciones ​

Creación de Objetos ​

Actualización de Objetos ​

Consulta de Objetos ​

Nomenclatura de Objetos ​

Listado de Objetos ​

Objeto Token ​

Objeto Purchase ​

API Purchase ​

Crear nueva compra ​

Obtener información de compra ​

Anular compra ​

Confirmar compra pre-autorizada ​

Listar compra ​

Objeto Customer ​

API Customer ​

Crear nuevo cliente ​

Actualizar datos del cliente ​

Obtener datos del cliente ​

Activar un perfil de pago ​

Objeto PaymentProfile ​

API PaymentProfile ​

Actualizar PaymentProfile ​

Eliminar PaymentProfile ​

Objeto CustomerActivation ​

Objeto Transaction ​

Objeto Address ​

Objeto TransactinStep ​

Objeto CountryDataDo ​

Objeto Notification ​

Servicio WebHook del Comercio ​

Especificaciones del servicio WebHook ​

Códigos HTTP ​

Códigos de Error ​

PR... Errores servicio de Purchase ​

CS… Errores servicio Customers. ​

TR… - Errores servicio Transactions ​

ER… Errores genéricos ​

Códigos de Respuesta de la transacción ​

Tipos de datos ​

Datos Básicos ​

String ​

Numeric ​

Tokenización & Autenticación

Preambulo

Conceptos

Api

URLBASE (Url Base)

Versiones de API

Autenticación

PublicAccountKey

PrivateAccountKey

Tokenización

Formato de Respuesta

Identificador Único

Formulario de Checkout

Importación de Librería

Métodos Disponibles

SetProperties

Propiedades:

Ejemplo

Proceso de Invocación Formulario Checkout

Ejemplo completo

Flujos Transaccionales

Usuarios Anónimos

Proceso de Transacción para Usuarios Anónimos

Flujo De Transacción Con Usuarios Anónimos

Usuarios Registrados

Proceso de Transacción para Usuarios Registrados

Registro de Usuarios:

Registro de Medios de Pago para un Usuario Registrado:

Proceso de Activación de Medio de Pago

Flujo de Clientes Registrados

Flujo de Tokenización Directa

Diagrama de Secuencia de Tokenización Directa

Proceso de Registro de Medio de Pago vía API

Api de servicio tokenización directa

Parametros de respuesta:

Ejemplo de mensajeria de Tokenización

Operaciones Permitidas

Directivas de Operaciones

Creación de Objetos

Actualización de Objetos

Consulta de Objetos

Nomenclatura de Objetos

Listado de Objetos

Objeto Token

Objeto Purchase

API Purchase

Crear nueva compra

Obtener información de compra

Anular compra

Confirmar compra pre-autorizada

Listar compra

Objeto Customer

API Customer

Crear nuevo cliente

Actualizar datos del cliente

Obtener datos del cliente

Activar un perfil de pago

Objeto PaymentProfile

API PaymentProfile

Actualizar PaymentProfile

Eliminar PaymentProfile

Objeto CustomerActivation

Objeto Transaction

Objeto Address

Objeto TransactinStep

Objeto CountryDataDo

Objeto Notification

Servicio WebHook del Comercio

Especificaciones del servicio WebHook

Códigos HTTP

Códigos de Error

`PR...` Errores servicio de Purchase

`CS…` Errores servicio Customers.

`TR…` - Errores servicio Transactions

`ER…` Errores genéricos

Códigos de Respuesta de la transacción

Tipos de datos

Datos Básicos

`String`

`Numeric`