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
.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
"
, \
, '
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.
- importe clases de Kount desde el SDK.
- Cree
KountRisClient
con la URL y la clave API. - Cree un nuevo objeto
Inquiry()
. - Utilice configuradores de clientes para agregar la información de la transacción.
- Agregue la información del carrito.
- Llame a
client.process(inquiry)
y obtenga un objeto de respuesta. - 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
- 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.
- 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. - 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.
- Dirección IP del cliente. El comerciante puede descubrirla u obtenerla a través del servicio de Recopilador de datos.
- Establezca esto en un número de crédito correcto o seleccione otro método de pago (para fines de prueba).
- 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 |
|
|
|
|
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.
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.