Cómo integrar el SDK de RIS Java para Kount Command

Este documento contiene recursos para el SDK Java de RIS de Kount. Para una integración completa de Kount, debe incluir el POST de datos del dispositivo (Device Data Collector, DDC) y la publicación de RIS. Se recomienda codificar primero el DDC.

El SDK Java de RIS de Kount proporciona medios para:

  • Creación y envío de solicitudes al servicio de RIS
  • Verificación de datos del cliente
  • Protección de la información confidencial

Instalación del SDK Java de RIS

El SDK contiene varias clases de modelos de objetos que representan diferentes tipos de solicitud, así como muchos objetos similares a la enumeración, que pueden utilizarse como valores de parámetros de solicitud.

La clase KountRisClient logra comunicación cliente-servidor-cliente, TLS v1.2 segura y clave API JWT.

El SDK utiliza métodos de hash específicos para cifrar y transmitir datos confidenciales del cliente, como números de tarjetas de crédito y varios tokens de pago.

Requisitos del SDK

Para integrar con éxito el SDK Java de RIS de Kount, deben cumplirse los siguientes requisitos:

  • JRE/JDK 1.8+
  • (opcional) Apache Maven 3.x+
  • (opcional) Git 2.7.3+

El SDK Java de RIS de Kount requiere JRE/JDK 1.8 para ser utilizado en una aplicación existente.

Los dos requisitos opcionales se proporcionan en caso de que el usuario del SDK prefiera descargar las fuentes del SDK y crear la biblioteca del SDK a partir de ellas. Consulte la sección Preguntas Frecuentes para obtener más información.

Descarga del SDK Java de RIS de Kount

Hay dos maneras de obtener el SDK Java:

  • Recuperarlo como una dependencia de Apache Maven
  • Crear el archivo .jar binario desde el origen
NOTA: Kount recomienda usar la dependencia de Maven para descargar e integrar SDK Java de RIS. Si necesita crear el archivo .jar binario desde el origen, consulte los pasos en la sección Preguntas frecuentes.

Dependencia de Maven

Apache Maven es una herramienta de gestión y comprensión de proyectos de software. En función del concepto de un modelo de objeto de proyecto (Project Object Model, POM), Maven puede gestionar la construcción, los informes y la documentación de un proyecto a partir de una información central.

Se puede obtener un .jar de dependencia utilizando el siguiente descriptor de dependencia en su .pom:

<dependency>
  <groupId>com.kount</groupId>
  <artifactId>kount-ris-sdk</artifactId>
  <version>${kount.sdk.version}</version>
</dependency>

Donde ${kount.sdk.version} es el lanzamiento de la biblioteca que va a usar.

Configuración de SDK Java de RIS

Antes de realizar su llamada de RIS, debe haber recibido (o creado) los siguientes datos de Kount:

  • ID del comerciante, número entero de 6 dígitos, denominado MERCHANT_ID en fragmentos de código
  • ID del sitio, ID_del_SITIO
  • URL para llamadas de RIS (de prueba)
  • Clave API, una clave JWT utilizada para la autenticación, apiKey
  • Una clave de configuración adicional utilizada dentro del SDK, configKey

Actualmente, todos los parámetros anteriores, excepto apiKey y configKey, deben configurarse a través de los métodos correspondientes para cada objeto de solicitud que cree.

  • apiKey se pasa como un objeto de archivo Java o como un objeto de cadena al KountRisClient que se utiliza para realizar la comunicación con el servidor de RIS.
  • configKey debe configurarse como una variable del sistema a través de una de dos maneras:
    • Variable del sistema a través de System.getProperty(“kount.config.key”);
    • Línea de comandos Dkount.config.key=configKey
NOTA: Si hay caracteres como ", \, ' en el valor de la clave de configuración, es necesario escapar de ellos en la línea de comandos.

Hacer su primera llamada

Antes de seguir estos pasos, debe tener el SDK Java de RIS de Kount, una URL de RIS válida y una clave API válida.

  1. importe clases de Kount desde el SDK.
  2. Cree KountRisClient con la URL y la clave API.
  3. Cree un nuevo objeto Inquiry().
  4. Utilice configuradores de clientes para agregar la información de la transacción.
  5. Agregue la información del carrito.
  6. Llame a client.process(inquiry) y obtenga un objeto de respuesta.
  7. Procese el objeto de respuesta.
paquete net.example;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
import com.kount.ris.Inquiry;
import com.kount.ris.KountRisClient;
import com.kount.ris.Response;
import com.kount.ris.util.CartItem;
import com.kount.ris.util.MerchantAcknowledgment;
import com.kount.ris.util.RisException;
import com.kount.ris.util.payment.Payment;
clase public Ejemplo {
    public static void main(String[] args) throws MalformedURLException {
        URL url = new URL("https://risk.kount.net"")         Cadena apiKey = new Cadena("23459856789");
        // Cree un objeto de cliente RIS con la URL de destino y su clave API
        KountRisClient ris = new KountRisClient(url, apiKey);
        // Cree y complete una nueva solicitud. La solicitud se entregará
        // al cliente RIS para realizar la llamada y proporcionar la respuesta.
        Inquiry req = new Inquiry();
        req.setMerchantId(555556);
        req.setSessionId("faa6370074b53928bc51ef913441e0cd");
        Pago = new Pago("CARD", "4111111111111111");
        req.setCurrency("USD");
        req.setPayment(payment);
        req.setTotal(125);
        req.setCustomerName("John Doe");
        req.setEmail("johndoe@test.com");
        req.setIpAddress("127.0.0.1");
        req.setMerchantAcknowledgment(MerchantAcknowledgment.YES);
        req.setWebsite("DEFAULT");
        CartItem item0 = new CartItem("SURROUND SOUND", "HTP-2920", "Sistema de sonido envolvente Pioneer 5.1 de alta potencia", 1, 49999);
        CartItem ítem1 = new CartItem("REPRODUCTOR BLU-RAY", "BDP-S500", "Reproductor de discos Blu-Ray Sony 1080p", 1, 69999);
        Collection<CartItem> cart = nueva ArrayList<>();
        cart.add(item0);

        cart.add(item1);
        req.setCart(cart);

        pruebe {
            // Este es el primer punto en que el código realmente llama a Kount
            // servicios. Todo lo anterior a esto es simplemente configurar la carga útil.
            Response response = ris.process(req);
            String responseText = "ID de transacción: " + response.getTransactionId() + "\n\n";
            responseText += response;
            System.out.print(responseText);
        } catch (RisException risException) {
            System.out.print(risException.getMessage());
        }

    }
}

Creación de objetos de solicitud

Existen dos tipos de solicitudes que se pueden realizar a través del SDK: Consulta y actualización.  Consulte Tipos de solicitud y Parámetros para obtener más información.

La estructura habitual de una Solicitud generalmente consta de tres partes:

  • Información sobre el comerciante e instrucciones de procesamiento para el servicio de RIS
  • Información sobre el cliente que realiza una compra: datos personales, ubicación geográfica, etc.
  • Información sobre la compra: nombre del producto, categoría, cantidad, precio

Objeto de consulta de muestra enviado al servicio de RIS.

public void evaluateInquiry() lanza la excepción {
Inquiry req = new Inquiry();
setMerchantInformation(i);
setCustomerInformation(i);
setPurchaseInformation(i);
Client KountRisClient = new KountRisClient(
new URL("https://kount.ris/url"), new file("/path/to/api.key")); // 1
Response response = client.process(i);
// hacer cosas con la respuesta
}
public void setMerchantInformation(Inquiry i) {
i.setMerchantId(MERCHANT_ID);
i.setWebsite(SITE_ID);
i.setMode(InquiryMode.INITIAL_INQUIRY); // 2
i.setMerchantAcknowledgment(MerchantAcknowledgment.YES);
}
private void setCustomerInformation(Inquiry i) {
i.setSessionId("session-id-max-32-chars"); // 3
i.setIpAddress("192.168.32.16"); // 4
i.setPayment(new CardPayment("credit-card-number")); // 5
i.setCustomerName("Customer Name");
i.setEmail("customer.name14@email.com");
i.setShippingAddress(new Address());
}
private void setPurchaseInformation(Inquiry i) {
i.setCurrency("USD");
i.setTotal(1000); // 6
CartItem cartItem = new CartItem(
"deportes", "nombre del producto deportivo", 
"descripción del producto deportivo", 2, 500);
i.setCart(Collections.singletonList(cartItem));
}

Explicación de la solicitud

Esta es una breve descripción de lo que sucede durante la creación de la solicitud, siguiendo los comentarios numerados en el código

  1. La creación del cliente de comunicación requiere la URL del servicio de RIS y una ruta al archivo de clave API proporcionado. La clave API se establece como el encabezado de la solicitud para la solicitud de red.
  2. Configuración del modo de solicitud. Como se mencionó anteriormente, hay varios modos de solicitud e InquiryMode.INITIAL_INQUIRY es el que más se utiliza. Consulte la página Avanzado para obtener más información sobre los modos de solicitud.
  3. Configuración de un identificador de sesión. Este ID debe ser único para un intervalo de 30 días y se utiliza para realizar un seguimiento de todos los cambios relacionados con la compra descrita en la solicitud. Más información en la página Avanzado.
  4. Dirección IP del cliente. El comerciante puede descubrirla u obtenerla a través del servicio de Recopilador de datos.
  5. Establezca esto en un número de crédito correcto o seleccione otro método de pago (para fines de prueba).
  6. El monto total de la compra representado en la denominación de moneda más baja posible (ejemplo: centavos para dólares estadounidenses)

Respuesta de RIS

Después de que un comerciante haya publicado la información de RIS en Kount, se devolverá una cadena de par clave-valor al comerciante. El formato de respuesta de RIS será el mismo que se especificó en la solicitud de RIS, con el nombre predeterminado de pares. Cada campo de datos debe invocarse mediante métodos de acceso en el objeto de Respuesta desde el SDK. Luego, el comerciante puede utilizar la respuesta de RIS para automatizar el proceso de gestión de pedidos basado en el campo AUTO y puede utilizar cualquiera de los datos adicionales devueltos para el procesamiento interno.

Un uso importante de la respuesta de RIS es la capacidad de ver cualquier advertencia o error que se haya cometido durante la publicación de RIS del comerciante. Todas las advertencias se mostrarán en la respuesta y, si se producen errores, la respuesta de RIS se devolverá con un MODO = E. Puede encontrar más información sobre advertencias y errores en la sección Resolución de problemas.

Si se utilizó el Recopilador de datos de Kount para recopilar información del cliente, se puede verificar el campo KAPT para determinar si este proceso fue exitoso. KAPT = S significa exitoso, KAPT = N significa que el proceso no tuvo éxito.

Opciones de cifrado de pagos de RIS

El SDK Java de RIS de Kount define un grupo de objetos que representan varios tipos de pago. El uso de esos tipos de pago con el método Request.setPayment(...) establece automáticamente el parámetro PTYP requerido y otros parámetros correspondientes al tipo de pago seleccionado.

Tipos de pago compatibles:

  • ApplePayPayment
  • BPayPayment
  • CardPayment
  • CarteBleuePayment
  • CheckPayment
  • ElvPayment
  • GiftCardPayment
  • GiroPayPayemnt
  • GooglePayment
  • GreenDotMoneyPakPayment
  • InteracPayment
  • MercadoPagoPayment
  • NetellerPayment
  • PaypalPayment
  • PoliPayment
  • SingleEuroPaymentsArea
  • SkrillMoneybookersPayment
  • SofortPayment
  • TokenPayment

También hay varios tipos de pago del "sistema":

  • NoPayment
  • BillMeLaterPayment

Para obtener la lista más reciente de los tipos de pago compatibles, así como sus valores de parámetros PTYP correspondientes, consulte Pagos de API RESTful de RIS (en inglés).

Si el SDK no contiene su tipo de pago preferido, utilice los métodos genéricos:

// opción 1
Payment unlistedPayment = new Payment("XYZ", "XYZ-payment-token");
request.setPayment(unlistedPayment);
// opción 2
request.setPayment("XYZ", "XYZ-payment-token");

Tipos y parámetros de solicitud

Existen dos tipos principales de solicitudes: Consulta y actualización. Su manejo por parte del servicio de RIS se puede configurar estableciendo el parámetro MODO en el valor correcto.

El tipo de consulta debe utilizarse para el registro inicial de la compra en el sistema de Kount. Tiene cuatro valores disponibles para el parámetro MODO.

MODO de consulta

Constante del SDK

Descripción

Q

InquiryMode.INITIAL_INQUIRY

Modo de consulta predeterminado, tipo de pedido por Internet

P

InquiryMode.PHONE_ORDER

Se utiliza para analizar un pedido recibido por teléfono

W

InquiryMode.KC_FULL_INQUIRY_W

Consulta completa de Kount Central con umbrales devueltos

J

InquiryMode.KC_FULL_INQUIRY_J

Consulta rápida de Kount Central con solo umbrales

El tipo de actualización debe utilizarse siempre que haya cambios en un pedido determinado y el comerciante desee que se reflejen en el sistema de Kount. La actualización tiene dos valores disponibles para el parámetro MODO.

MODO de actualización

Constante del SDK

Descripción

U

UpdateMode.NO_RESPONSE

Modo de actualización predeterminado, solo envía el evento de actualización

X

UpdateMode.WITH_RESPONSE

Envía el evento de actualización y el servicio de RIS devuelve una respuesta de estado

Parámetros obligatorios

Nombre del parámetro

Configurador

P

P

W

J

U

X

MODE

setMode

S

S

S

S

S

S

VERS

setVersion

S

S

S

S

S

S

MERC

setMerchantId

S

S

S

S

S

S

SITIO

setWebsite

S

S

S

 

 

 

SESS

setSessionId

S

S

S

 

S

S

CURR

setCurrency

S

S

S

S

 

 

TOTL

setTotl

S

S

S

S

 

 

MACK

setKcCustomerId

S

S

S

 

 

 

CUSTOMER_ID

kount_central_customer_id

 

 

S

S

 

 

PTYP

 

S

S

S

S

 

 

IPAD

setIpAddress

S

S

S

S

 

 

MACK

setMerchantAcknowledgment

S

S

S

 

S

S

TRAN

set_transaction_id

 

 

 

 

S

S

PROD_TYPE

*

S

S

S

 

 

 

PROD_ITEM

*

S

S

S

 

 

 

PROD_QUANT

*

S

S

S

 

 

 

PROD_PRICE

*

S

S

S

 

 

 

ANID

setAnid

 

S

 

 

 

 

NOTA: Los parámetros marcados con un asterisco son los parámetros del carrito de compras. Se configuran a granel mediante el método Inquiry.setCart(collection<CartItem> cart). Si el carrito de compras contiene más de una entrada, los valores para cada parámetro se transforman en cadenas concatenadas únicas y luego se establecen en el parámetro correspondiente.

Parámetros opcionales

El SDK Java de RIS de Kount proporciona una gran cantidad de parámetros de solicitud opcionales para aumentar la precisión al decidir sobre una compra o un pedido determinado.

  • AUTH: Estado de autorización devuelto al comerciante desde el procesador. Los valores aceptables para el campo AUTH son A para Autorizado o D para Rechazar (Decline). En los pedidos donde AUTH = A se sumará a la velocidad del pedido de la persona mientras que los pedidos donde AUTH = D disminuirán la velocidad de la persona.
  • AVST: Respuesta de verificación de Calle del sistema de verificación de dirección devuelta al comerciante desde el procesador. Los valores aceptables son M para coincidencia (Match), N para sin coincidencia (no-match) o X para no compatible o no disponible.
  • AVSZ: Respuesta de verificación de código postal del sistema de verificación de dirección devuelta al comerciante desde el procesador. Los valores aceptables son M para coincidencia, N para sin coincidencia o X para no compatible o no disponible.
  • CVVR: Respuesta del valor de verificación de la tarjeta devuelta al comerciante desde el procesador. Los valores aceptables son M para coincidencia, N para sin coincidencia o X para no compatible o no disponible.
  • LAST4: Últimos 4 números del valor de la tarjeta de crédito.

Campos definidos por el usuario (User Defined Fields, UDF)

Puede crear campos definidos por el usuario (User Defined Field, UDF) para incluir información adicional relacionada con su negocio que no sea un campo estándar en la página Detalles de transacciones en AWC. Una vez que haya definido el UDF en AWC, puede pasar estos datos a Kount a través de una matriz llamada UDF como pares clave-valor donde la etiqueta es la clave y los datos transferidos son el valor. Para obtener más información sobre cómo crear UDF, revise Cómo gestionar campos definidos por el usuario (UDF) (en inglés).

Respuesta predictiva

La respuesta predictiva es un mecanismo que pueden utilizar los comerciantes de Kount para enviar solicitudes de prueba y recibir respuestas predecibles de RIS. Esto significa que un comerciante, para probar RIS, puede generar una solicitud particular que está diseñada para proporcionar una o más respuestas y/o errores específicos de RIS. Las consultas de respuesta predictiva no son consultas de RIS reales, lo que significa que los datos nunca se enviarán a la base de datos interna de Kount.

Un ejemplo sería si un comerciante quisiera enviar una solicitud de RIS que devolviera las respuestas muy específicas SCOR = 71, AUTO = E y GEOX = CA.

Las respuestas predictivas se crean utilizando la opción de anulación de campos definidos por el usuario (UDF). Estos campos definidos por el usuario no necesitan crearse a través de la consola web del agente, simplemente pueden pasarse como campos adicionales en la consulta de RIS de respuesta predictiva.

NOTA: Para crear una consulta de RIS de respuesta predictiva, la solicitud debe contener un parámetro de correo electrónico específico en el campo de correo electrónico: predictive@kount.com. La dirección de correo electrónico distingue entre mayúsculas y minúsculas; y debe estar en minúsculas.

Todos los demás elementos de la solicitud de RIS que envíe deben ser elementos válidos y contener el conjunto mínimo de claves de RIS requeridas.

La sintaxis básica es: UDF[~K!_label]="foo" ~K!_ es el prefijo, la etiqueta es el campo deseado para el cual desea una respuesta, como SCOR o ERRO, y después del signo igual (=), ingrese el valor específico que desea devolver. El prefijo ~K!_ es necesario para activar el UDF para que se convierta en un campo de respuesta predictiva.

Ejemplo 1

Desea enviar una solicitud que dará como resultado un puntaje Kount de 18, una decisión automática de E y un código de error del sistema 601.

Solicitud

   UDF[~K!_SCOR]=18

    UDF[~K!_AUTO]=E

    UDF[~K!_ERRO]=601

Respuesta

   SCOR=18

    AUTO=E

    ERRO=601

Ejemplo 2

Desea aprobar una solicitud que dará como resultado un puntaje de Kount de 42, una decisión automática de rechazo y un GEOX de Nigeria.

Solicitud

   UDF[~K!_SCOR]=42

    UDF[~K!_AUTO]=D

    UDF[~K!_GEOX]=NG

Respuesta

   SCOR=42

    AUTO=D

    GEOX=NG

Puede usar las anulaciones de UDF para pasar una cantidad ilimitada de solicitudes simuladas, pero todos los campos que pase que no sean anulaciones deben ser válidos. En la respuesta, todos los demás elementos, además de las anulaciones de UDF, serán los valores predeterminados, incluidos MODO y MERC.

Parámetros relacionados con la sesión

Existen algunos parámetros responsables de mantener la conexión entre las interacciones vinculadas con el RIS. Se transportan como parte de los objetos de solicitud/respuesta durante la comunicación estándar de RIS.

Parámetro SESS

Este parámetro debe ser creado por el comerciante al comienzo de cada compra de cliente nuevo. El SESS se utiliza para unir los datos del dispositivo del cliente con los datos del pedido enviados con la solicitud de RIS. Si el comerciante utiliza el servicio Recopilador de datos del dispositivo para obtener información del dispositivo del cliente, entonces se debe utilizar el mismo valor de SESS para todas las llamadas de RIS que comienzan con la del servicio del Recopilador de datos del dispositivo. Los requisitos para el valor del parámetro son:

  • Alfanumérico
  • 1-32 caracteres
  • El valor debe ser único durante un período de treinta días. El SESS es un parámetro obligatorio establecido por el método Request.session_set(string).

Parámetro TRAN

El parámetro TRAN es necesario para actualizar llamadas al RIS de Kount. Kount crea su valor y lo devuelve dentro del objeto Respuesta para la primera consulta de RIS. Para todos los eventos posteriores, al modificar este pedido de cliente en particular, el parámetro TRAN debe establecerse en el valor creado por Kount.

Preguntas Frecuentes

¿Cómo creo el archivo .jar binario desde el origen?

Kount permite a los desarrolladores descargar y crear la biblioteca de SDK desde el repositorio de SDK Java de GitHub, pero se recomienda que use el método de dependencia de Maven como se escribe en Instalación del SDK Java de RIS.

  1. Clonar el repositorio SDK a su máquina:
    1. Use su cliente preferido de Git.
    2. Consola:
      git clone https://github.com/Kount/kount-ris-java-sdk.git
      git clone git@github.com:Kount/kount-ris-java-sdk.git
  2. Compilar y crear:
    El paquete mvn clean genera documentación (javadoc), compila y crea el SDK, ejecuta un conjunto predefinido de pruebas de unidad e integración y, al final, junta todo.
  3. Integrar en su IDE:
    Los paquetes IntelliJ IDEA y Eclipse recientes tienen soporte completo para proyectos de Maven.
    Con Eclipse también puede usar el comando mvn eclipse:eclipse para generar archivos de ruta de clase y proyecto que utilizará este IDE.
  4. Se puede encontrar el binario generado (.jar) en kount-ris-sdk/objetivo. Se puede agregar directamente a un proyecto como dependencia o se puede implementar en su repositorio local de Maven y al que se hace referencia mediante el fragmento .pom que se proporciona en la sección dependencia de Maven.
NOTA: Ejecutar el comando de paquete limpio de mvn solo crearía el SDK. Las pruebas de dependencia que contiene esta distribución fallarán sin la configuración adecuada. Comuníquese con Kount para obtener información sobre los datos de configuración requeridos. Aún puede usar el jar de dependencia creado como primer módulo del proyecto de Maven.
¿Dónde puedo encontrar campos definidos por el usuario?
¿Dónde puedo encontrar los tipos de pago aceptados y los códigos correspondientes?
¿Dónde puedo encontrar los códigos de error de RIS?
¿Cuáles son los otros modos de RIS?
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 1
Risk Inquiry Service SDKs — Español
Cómo integrar el SDK de RIS Java para Kount Command