Introducción


La librería de ComproPago Java SDK te permite interactuar con el API de ComproPago desde tu aplicación. También cuenta con los métodos necesarios para facilitar el desarrollo por medio de los servicios más utilizados (SDK). Con ComproPago puedes recibir pagos en 7Eleven, Extra, y más tiendas en todo México.

Requerimientos


  • Java 1.8
  • Json 2.8.0

Instalación


Puede descargar el archivo .jar de alguna de las versiones publicadas e incluirlo en su proyecto Java.

También puede descargar directamente el codigo fuente del SDK desde el repositorio de Github con el siguiente comando:

git clone https://github.com/compropago/compropago-java.git

Configuración


Importación

Para poder hacer uso de la librería es necesario incluir el namespace principal de la librería.

import compropagosdk.*;

Dentro de este namespace se encuentran la clase Client y la clase Factory que corresponden a las clases pricipales del sdk. La clase Client corresponde a la clase principal del SDK y es con la cual se tiene acceso a todas las funcionalidades del API. Por otro lado, la clase Factory es la encargada de la generación de todos los modelos dentro del SDK y es ocupada para la instaciación de clases como PlaceOrderInfo al momento de generar los cargos.

Configurar el cliente

Para hacer uso de la librería y llamados al API es necesario que primero configures tus Llaves de conexión y crees un instancia de Client. Tus llaves las encontrarás en su Panel de ComproPago en el menú Configuración.

/**
 * @param string publickey     Llave pública correspondiente al modo de la tienda
 * @param string privatekey    Llave privada correspondiente al modo de la tienda
 * @param bool   live          Modo de la tienda (false = Test | true = Live)
 */
Client client = new Client(
    "pk_test_xxxxxxxxxxxxxxxxx",  // publickey
    "sk_test_xxxxxxxxxxxxxxxxx",  // privatekey
    false                         // live
);

Metodos


listProviders

La función listProviders le proporciona un listado con los puntos de cobro disponibles para su tienda con parametros para su facil filtrado, la cual regresa un arreglo de objetos de tipo Provider con los cuales puede acceder a sus atributos.

Prototipo

/**
 * @return Provider[]
 * @throws Exception
 */
public Provider[] listProviders(){}

/**
 * @param double limit
 * @return Provider[]
 * @throws Exception
 */
public Provider[] listProviders(limit){}

/**
 * @param double limit
 * @param string currency
 * @return Provider[]
 * @throws Exception
 */
public Providers[] listProviders(limit, currency){}

Parametros
Parámetro Tipo Valor por defecto Descripción
limit double 0 Límite mínimo que deben de soportar los proveedores listados.
currency String MXN Divisa en la cual se procesa el campo limit, para poder ocupar este campo es necesario que el campo $auth este configurado como true o en su caso siempre se tomara el valor por defecto. los valores soportados son: Pesos mexicanos (MXN), Dolar americano (USD), Euro (EUR), Libra Esterlina (GBP).
Ejemplo

Provider[] providers = client.api.listProviders();

for (int x = 0; x <= providers.length; x++) {
    System.out.println(providers[x].name);
}

// 7Eleven
// Coppel
// ...

placeOrder

Éste método le permite registrar órdenes en las cuales sus clientes podrán pagar posteriormente. El método recibe como parámetro un objeto de tipo PlaceOrderInfo y como resultado genera un objeto de tipo NewOrderInfo la cual contendrá la información resultante de la generación de la orden.

Prototipo

/**
 * @param compropagosdk.factory.models.PlaceOrderInfo neworder
 * @return compropagosdk.factory.models.NewOrderInfo
 * @throws Exception
 */
public NewOrderInfo placeOrder(neworder){}

Parametros
Parámetro Tipo Valor por defecto Descripción
neworder PlaceOrderInfo Objeto con la información de la orden generado mediante la clase Factory
Ejemplo

// Se genera el objeto con la información de la orden
/**
 * @param string order_id          Id de la orden
 * @param string order_name        Nombre del producto o productos de la orden
 * @param string order_price       Monto total de la orden
 * @param string customer_name     Nombre completo del cliente
 * @param string customer_email    Correo electrónico del cliente
 * @param string payment_type      (default = SEVEN_ELEVEN) Valor del atributo internal_name' de un objeto 'Provider'
 * @param string currency          (default = MXN) Código de la moneda con la que se esta creando el cargo
 */
Map<String, String> data = new HashMap<String, String>();
data.put("order_id", "123");
data.put("order_name", "M4 test java");
data.put("order_price", String.valueOf(123.45));
data.put("customer_name", "Eduardo Aguilar");
data.put("customer_email", "[email protected]");
data.put("payment_type", "SEVEN_ELEVEN");
data.put("currency", "MXN");

PlaceOrderInfo order = Factory.placeOrderInfo(data);

// Llamada al método 'placeOrder' del API para generar la orden
NewOrderInfo neworder = client.api.placeOrder(order);

verifyOrder

Para verificar el estatus de una orden generada es necesario llamar al método verify_order que provee el atributo api del objeto Client y el cual regresa una instancia CpOrderInfo. Éste método recibe como parámetro el ID generado por ComproPago para cada orden. También puede obtener éste ID desde un objeto NewOrderInfo accediendo al atributo id.

Prototipo

/**
 * @param String orderId
 * @return compropagosdk.factory.models.CpOrderInfo
 * @throws Exception
 */
public CpOrderInfo verifyOrder( orderId ){}

Parametros
Parámetro Tipo Valor por defecto Descripción
orderId String Id generado al registrar una orden en ComproPago
Ejemplo

// Guardar el ID de la orden
String orderId = "ch_xxxx_xxx_xxx_xxxx";

// U obtenerlo de un objeto NewOrderInfo
String orderId = neworder.id;

// Se manda llamar al metodo del API para recuperar la información de la orden
CpOrderInfo info = client.api.verifyOrder( orderId );

sendSmsInstructions

Para realizar el el envío de las instrucciones de compra vía SMS es necesario llamar al método sendSmsInstructions que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo SmsInfo.

Prototipo

/**
 * @param String number
 * @param String orderId
 * @return compropagosdk.factory.models.SmsInfo
 * @throws Exception
 */
public SmsInfo sendSmsInstructions(number, orderId){}

Parametros
Parámetro Tipo Valor por defecto Descripción
number String Número telefónico del cliente al cual se enviará el mensaje de texto
orderId String ID de la orden de compropago la cual fue generada previamente.
Ejemplo

// Numero al cual se enviarán las instrucciones
String phoneNumber = "55xxxxxxxx";

// Id de la orden de compra de cual se enviarán las instrucciones
String orderId = "ch_xxxxx-xxxxx-xxxxx-xxxxx";

// Llamada al metodo del API para envío de las instrucciones
SmsInfo smsinfo = client.api.sendSmsInstructions(phoneNumber , orderId);

listWebhooks

Para obtener la lista de webhooks registrados en una cuenta, se debe de llamar al método listWebhook que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo Webhook[].

Prototipo

/**
 * @return Webhook[]
 * @throws Exception
 */
public Webhook[] listWebhooks(){}

Ejemplo

Webhook[] webhooks = client.api.listWebhooks();

for (int x = 0; x <= webhooks.lenght; x++) {
    System.out.println(webhooks[x].url);
}

// https://misitio.com/webhook/
// https://misitio.com/webhook/dos/
// ...

createWebhook

Para crear un nuevo Webhook en la cuenta, se debe de llamar al método createWebhook que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo Webhook.

Prototipo

/**
 * @param String url
 * @return compropagosdk.factory.models.Webhook
 * @throws Exception
 */
public Webhook createWebhook(url){}

Parametros
Parámetro Tipo Valor por defecto Descripción
url String Url que será registrada como EndPoint del webhook.
Ejemplo

/**
 * Se pasa como parámetro la URL al webhook
 */
Webhook webhook = client.api.createWebhook("http://sitio.com/webhook");

updateWebhook

Para actualizar la url de un webhook, se debe de llamar al método updateWebhook que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo Webhook.

Prototipo

/**
 * @param String webhookId
 * @param String url 
 * @return compropagosdk.factory.models.Webhook
 * @throws Exception
 */
public Webhook updateWebhook(webhookId, url){}
    
/**
 * @param String webhookId
 * @param String url 
 * @param String type (secondary | primary)
 * @return compropagosdk.factory.models.Webhook
 * @throws Exception
 */
public Webhook updateWebhook(webhookId, url, type){}

Parametros
Parámetro Tipo Valor por defecto Descripción
webhookId String Id de un webhook previamente registrado. Puede ser obtenido de una instancia Webhook accediendo al atributo id.
url String Nueva url del webhook.
Tipo de webhook. Puede tomar valores de secondary o primary.
Ejemplo

Webhook updated = client.api.updateWebhook(webhook.id, "http://sitio.com/nuevo");

deactiveWebhook

Para desactivar un webhook y evitar que reciba notificaciones sin eliminarlo debe de ocupar la función deactiveWebhook que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo Webhook.

Prototipo

/**
 * @param String webhookId
 * @return compropagosdk.factory.models.Webhook
 * @throws Exception
 */
public Webhook deactiveWebhook(webhookId){}

Parametros
Parámetro Tipo Valor por defecto Descripción
webhookId String Id de un webhook previamente registrado. Puede ser obtenido de una instancia Webhook accediendo al atributo id.
Ejemplo

Webhook deactive = client.api.deactiveWebhook( webhook.id );

deleteWebhook

Para eliminar un webhook, se debe de llamar al método deleteWebhook que se encuentra alojado en el atributo api del objeto Client y el cual regresa una instancia de tipo Webhook.

Prototipo

/**
 * @param String webhookId
 * @return compropagosdk.factory.models.Webhook
 * @throws Exception
 */
public Webhook deleteWebhook(webhookId){}

Parametros
Parámetro Tipo Valor por defecto Descripción
webhookId String Id de un webhook previamente registrado. Puede ser obtenido de una instancia Webhook accediendo al atributo id.
Ejemplo

Webhook deleted = client.api.deleteWebhook( webhook.id );

Iframe de recibo


Para facilitar el despliegue de instrucciones de pago, puedes incluir un Iframe en tu sitio apuntando a los recibos de ComproPago de la siguiente manera.

<div class="compropagoDivFrame" id="compropagodContainer" style="width: 100%;">
    <iframe style="width: 100%;"
        id="compropagodFrame"
        src="https://www.compropago.com/comprobante/?confirmation_id=ch_xxxxx_xxxx_xxx_xxxxx"
        frameborder="0"
        scrolling="yes"> </iframe>
</div>
<script type="text/javascript">
    function resizeIframe() {
        var container=document.getElementById("compropagodContainer");
        var iframe=document.getElementById("compropagodFrame");
        if(iframe && container){
            var ratio=585/811;
            var width=container.offsetWidth;
            var height=(width/ratio);
            if(height>937){ height=937;}
            iframe.style.width=width + 'px';
            iframe.style.height=height + 'px';
        }
    }
    window.onload = function(event) {
        resizeIframe();
    };
    window.onresize = function(event) {
        resizeIframe();
    };
</script>

Dentro del parámetro src del Iframe, se especifica la ruta del recibo, la cual contiene un parametro confirmation_id el cual debera contener el Id de la orden generada, el cual se puede obtener del atributo id de los objetos NewOrderInfo o CpOrderInfo.