SDK JAVA

Nuestro SDK oficial JAVA, es compatible con la V2.0 del Culqi API, con el cual tendrás la posibilidad de integrarte con el API de tokens, cargos, devoluciones, clientes, tarjetas, planes, suscripciones y órdenes

El SDK te da la posibilidad de capturar el status_code de la solicitud HTTP que se realiza al API de Culqi, así como el response.

Requisitos

• Nuestro SDK es compatible con JAVA 1.8+.
• Debes tener tus llaves de producción o integración.
• Si aun no te afilias a Culqi, lo puedes hacer desde aquí.
• Para encriptar el payload debes generar un id y llave RSA ingresando a tu CulqiPanel > Desarrollo > RSA Keys.

Repositorio

Puedes descargar el código fuente del SDK desde:

Repositorio de paquetes

Puedes revisar las versiones disponibles desde el repositorio de paquetes de Git e instalarlo en tu aplicativo como una dependencia:

Instalación

Instalación usando Maven:

Solo necesitas agregar el siguiente repositorio en el archivo pom.xml* de tu aplicativo.

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

Luego agregar la dependencia. Selecciona siempre la versión mas reciente del repositorio de paquetes.

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

Configuración

1. Configurar llaves

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 = "{PUBLIC KEY}";
culqi.secret_key = "{SECRET KEY}";

2. Encriptar payload

Para encriptar el payload necesitas pasar como parámetro el rsaPublicKey y rsaId, enviarlos en los métodos de la librería.

Ejemplo

String rsaPublicKey = "{rsa_public_key}";
Sring rsaId = "{rsa_id}"; 

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

Servicios

Crear token

Para no poner en riesgo los datos sensibles de la tarjeta de crédito/débito es recomendable es generar los ‘tokens’ con el Custom Checkout debido a que es muy importante que los datos de la tarjeta sean enviados directamente desde el dispositivo de tus clientes a los servidores de 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 el parámetro source_id.

Los cargos son creados a través del 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) a través del API y CulqiPanel.

Las devoluciones son creadas a través del 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 son creados a través del API de cliente.

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

Crear Card

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 son creadas a través del 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 son creados a través del API de Plan o desde el CulqiPanel.

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

Crear Suscripción a un plan

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

Las suscripciones son creadas a través del 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 son creadas a través del 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));
 }

Pruebas

Antes de activar tu tienda en producción, te recomendamos realizar pruebas de integración. Así garantizarás un correcto despliegue.

Si vas a empezar a vender desde tu tienda virtual, deberás seleccionar el ambiente de producción e ingresar tus llaves.

Debes tener instalado Maven para poder ejecutar los tests

mvn test

Puedes ejecutar tesy 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());
}