Culqi-Java

Nuestra Biblioteca JAVA oficial, es compatible con la v2.0 del Culqi API, con el cual tendrás la posibilidad de realizar cobros con tarjetas de débito y crédito, Yape, PagoEfectivo, billeteras móviles y Cuotéalo con solo unos simples pasos de configuración.

Nuestra biblioteca te da la posibilidad de capturar el status_code de la solicitud HTTP que se realiza al API de Culqi, así como el response que contiene el cuerpo de la respuesta obtenida.

Versión actual	Culqi API
2.0.4	v2.0

Requisitos

• Java 1.7+
• Afiliate aquí.
• Si vas a realizar pruebas obtén tus llaves desde aquí, si vas a realizar transacciones reales obtén tus llaves desde aquí.

Recuerda que para obtener tus llaves debes ingresar a tu CulqiPanel > Desarrollo > API Keys.

Recuerda que las credenciales son enviadas al correo que registraste en el proceso de afiliación.

• Para encriptar el payload debes generar un id y llave RSA ingresando a CulqiPanel > Desarrollo > RSA Keys.

Instalación

Instalación usando Maven:

Solo necesita agregar el siguiente repositorio en el archivo pom.xml

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Luego agregar la dependencia:

<dependency>
    <groupId>com.github.culqi</groupId>
    <artifactId>culqi-java</artifactId>
    <version>v2.0.4</version>
</dependency>

Configuración

Para empezar a enviar peticiones al API de Culqi debes configurar tu llave pública (pk), llave privada (sk). Para habilitar encriptación de payload debes configurar tu rsa_id y rsa_public_key.

culqi.public_key = "pk_test_889113cd74ecfc55";
culqi.secret_key = "sk_test_LoSAl6rqTInlzPSJ";
String rsaPublicKey = "-----BEGIN PUBLIC KEY-----\n"
			+ "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDADka0Pt4SuWlHRA6kcJIwDde\n"
			+ "o67OYBEgQDEelmmixs9AlB/1bv446XOOE8eTJSridll2ZAn2nze7Gl2vQs0yW+4A\n"
			+ "XmszJwugM0lxTDiPdTXdbrA4VXiXDG29VLQCAxt1+/c7bE84hMS6cymWgEjYoa6I\n"
			+ "xX8u0ncLyiRUdZC2cwIDAQAB\n"
			+ "-----END PUBLIC KEY-----";
	
Sring rsaId = "5243bad7-1d88-49c0-9699-f8ae156da58f"; 
	
JsonData jsondata = new JsonData();

Encriptar payload

Para encriptar el payload necesitas pasar como parámetro el rsaPublicKey y rsaId.

Ejemplo

protected Map<String, Object> createTokenEncrypt() throws Exception {
    return init().token.create(jsondata.jsonToken(), rsaPublicKey, rsaId);
}

Servicios

Crear Token

Antes de crear un Cargo o Card es necesario crear un token de tarjeta. Lo recomendable es generar los 'tokens' con Culqi Checkout v4 o Culqi JS v4 debido a que es muy importante que los datos de tarjeta sean enviados desde el dispositivo de tus clientes directamente a los servidores de Culqi, para no poner en riesgo los datos sensibles de la tarjeta de crédito/débito.

Recuerda que cuando interactúas directamente con el API Token necesitas cumplir la normativa de PCI DSS 3.2. Por ello, te pedimos que llenes el formulario SAQ-D y lo envíes al buzón de riesgos Culqi.

 protected Map<String, Object> createToken() throws Exception {
    return init().token.create(jsondata.jsonToken());
 }

Crear Cargo

Crear un cargo significa cobrar una venta a una tarjeta. Para esto previamente deberías generar el token y enviarlo en parámetro source_id.

Los cargos pueden ser creados vía API de cargo.

protected Map<String, Object> createCharge() throws Exception {
   String source_id = createToken().get("id").toString();
   return init().charge.create(jsondata.jsonCharge(source_id));
}

Para realizar un cargo recurrente, puedes utilizar el siguiente código:

protected Map<String, Object> createCharge() throws Exception {
    String source_id = createToken().get("id").toString();
    Map<String, String> customHeaders = new HashMap<String, String>();
    customHeaders.put("X-Charge-Channel", "recurrent");

    return init().charge.create(jsondata.jsonCharge(source_id), customHeaders);
}

Crear Devolución

Solicita la devolución de las compras de tus clientes (parcial o total) de forma gratuita a través del API y CulqiPanel.

Las devoluciones pueden ser creados vía API de devolución.

protected Map<String, Object> createRefund() throws Exception {
   String charge_id = createCharge().get("id").toString();
   return init().refund.create(jsondata.jsonRefund(charge_id));
}

Crear Cliente

El cliente es un servicio que te permite guardar la información de tus clientes. Es un paso necesario para generar una tarjeta.

Los clientes pueden ser creados vía API de cliente.

 protected Map<String, Object> createCustomer() throws Exception {
    return init().customer.create(jsondata.jsonCustomer());
 }

Crear Tarjeta

La tarjeta es un servicio que te permite guardar la información de las tarjetas de crédito o débito de tus clientes para luego realizarles cargos one click o recurrentes (cargos posteriores sin que tus clientes vuelvan a ingresar los datos de su tarjeta).

Las tarjetas pueden ser creadas vía API de tarjeta.

protected Map<String, Object> createCard() throws Exception {
   String customer_id = createCustomer().get("id").toString();
   String token_id = createToken().get("id").toString();
   return init().card.create(jsondata.jsonCard(customer_id,token_id));
}

Crear Plan

El plan es un servicio que te permite definir con qué frecuencia deseas realizar cobros a tus clientes.

Un plan define el comportamiento de las suscripciones. Los planes pueden ser creados vía el API de Plan o desde el CulqiPanel.

protected Map<String, Object> createPlan() throws Exception {
   return init().plan.create(jsondata.jsonPlan());
}

Crear Suscripción

La suscripción es un servicio que asocia la tarjeta de un cliente con un plan establecido por el comercio.

Las suscripciones pueden ser creadas vía API de suscripción.

 protected Map<String, Object> createSubscription() throws Exception {
    String card_id = createCard().get("id").toString();
    String plan_id = createPlan().get("id").toString();
    return init().subscription.create(jsondata.jsonSubscription(card_id, plan_id));
 }

Crear Orden

Es un servicio que te permite generar una orden de pago para una compra potencial. La orden contiene la información necesaria para la venta y es usado por el sistema de PagoEfectivo para realizar los pagos diferidos.

Las órdenes pueden ser creadas vía API de orden.

 protected Map<String, Object> createSubscription() throws Exception {
    String card_id = createCard().get("id").toString();
    String plan_id = createPlan().get("id").toString();
    return init().subscription.create(jsondata.jsonSubscription(card_id, plan_id));
 }

Build

mvn package -DskipTests

Testing

Debes tener instalado Maven para poder ejecutar los tests

mvn test

Puede ejecutar estos unitarios independientemente

mvn test -D test=CulqiCreateTest#test01_createToken
mvn test -D test=CulqiCreateTest#test02_createTokenEncrypt
mvn test -D test=CulqiCreateTest#test04_createCharge
mvn test -D test=CulqiCreateTest#test05_createPlan
mvn test -D test=CulqiCreateTest#test06_createCustomer
mvn test -D test=CulqiCreateTest#test07_createCard
mvn test -D test=CulqiCreateTest#test08_createSubscription
mvn test -D test=CulqiCreateTest#test09_chargeCapture

Ejemplo Prueba Token

@Test
public void test01_createToken() throws Exception {
    culqiCRUD.createToken().get("object").toString();
    assertEquals("token", culqiCRUD.createToken().get("object").toString());
}

Ejemplo Prueba Cargo

@Test
public void test04_createCharge() throws Exception {
    assertEquals("charge", culqiCRUD.createCharge().get("object").toString());
}

¿Cómo instalar el jar de Culqi en un proyecto Maven?

mvn install:install-file -Dfile={dir}/culqi-java-1.1.8.jar  -DgroupId=com.culqi -DartifactId=culqi-java -Dversion={version} -Dpackaging=jar

Luego agregas la siguiente dependencia en el pom.xml

<dependency>
    <groupId>com.culqi</groupId>
    <artifactId>culqi-java</artifactId>
    <version>{version}</version>
</dependency>

Documentación

• Referencia de Documentación
• Referencia de API
• Demo Checkout V4 + Culqi 3DS
• okhttp3
• Jackson Core Databind
• Wiki

Instalar Java

Descarga Spring Tools Suite 4-4.21.0 archivo del siguiente link:

    https://cdn.spring.io/spring-tools/release/STS4/4.21.0.RELEASE/dist/e4.30/spring-tool-suite-4-4.21.0.RELEASE-e4.30.0-linux.gtk.x86_64.tar.gz

Instalar jdk (Kit de Desarrollo de Java)

Asegúrate de tener instalado el JDK 8 mediante los siguientes comandos:

sudo apt-get update
sudo apt-get install openjdk-8-jdk

Configurar Variables de Entorno para Java y Maven

Edita el archivo .bashrc con el siguiente comando:

    #Abre el archivo .bashrc 
    nano ~/.bashrc

Añade las siguientes líneas al final del archivo:

    #Agrega las siguientes líneas al final del archivo:
    JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
    M2_HOME=/usr/share/maven
    PATH=$PATH:$JAVA_HOME/bin:$M2_HOME/bin

Guarda los cambios y cierra el editor (Ctrl + o >> Enter >> Ctrl + x).

Instalar Maven

Instala Maven con el siguiente comando

sudo apt-get install maven

Como abrir el archvio SDK

Abre Spring Tools Suite y selecciona:

    FILE >> IMPORT >> MAVEN >> EXISTING MAVEN PROJECTS

Instalar Dependencias

Haz clic derecho en la carpeta raíz del proyecto y selecciona:

        RUN AS >> MAVEN CLEAN 
        RUN AS >> MAVEN INSTALL

Ejecutar Tests

Haz clic derecho en la carpeta src/test/java y selecciona:

        RUN AS >> JUnit Test

Espera a que se ejecuten todas las pruebas unitarias y, luego, ejecuta cada prueba individualmente según las necesidades.

CulqiCreateTest:
    test05_createPlan
    test08_createSubscription

CulqiDeleteTest: 
    test01_deleteSubscription
    test02_deletePlan

CulqiGetTest:
    test06_findPlan
    test07_findSubscription

CulqiAllTest:
    test04_allPlan
    test06_allSubscriptions

Click derecho en el nombre del test_0** >> RUN

Donde Encontrar los ejemplos para Pruebas

Dentro de la estructura del proyecto, encontrarás ejemplos de pruebas que puedes utilizar para verificar el funcionamiento del SDK. Sigue estos pasos para acceder y ejecutar los ejemplos:

Ubicación de los Ejemplos:

• Haz clic derecho en la carpeta src/test/java.
• Abre el archivo CulqiCRUD.java.
• En la linea 27 puedes configurar el secreto:

    culqi.secret_key = "sk_live_************";

• Haz clic derecho en la carpeta src/test/java.

• Abre el archivo JsonData.java.

• Ejemplo de JSON: En el archivo JsonData.java, encontrarás ejemplos de datos en formato JSON que se utilizan en las pruebas. Puedes modificar estos datos según tus necesidades.

php examples/plan/02-create-plan.php
    Crear Plan: jsonPlan
    Actualizar Plan: jsonUpdatePlan
    All Plan: jsonPlanFilter

    Crear Subscription: jsonSubscription
    Actualizar Subscription: jsonUpdateSubscription
    All Subscription: jsonListSubscriptions

Modifica estos ejemplos según tus necesidades y asegúrate de tener configuradas correctamente tus credenciales de Culqi antes de ejecutar las pruebas.

Changelog

Todos los cambios en las versiones de esta biblioteca están listados en CHANGELOG.

Autor

Team Culqi

Licencia

El código fuente de culqi-java está distribuido bajo MIT License, revisar el archivo LICENSE.