logo

Introducción


Con ComproPago puede recibir pagos en 7Eleven, Extra, y muchas tiendas más en todo México.

La librería de ComproPago PHP SDK le permite interactuar con el API de ComproPago en su aplicación. También cuenta con los métodos necesarios para facilitar el desarrollo por medio de los servicios más utilizados.

Requerimientos


Instalación


Instalación por Github

Puede descargar alguna de las versiones que hemos publicado aquí, o si lo desea puede clonar nuestro repositorio de la siguiente forma:

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

Posteriormente deberá de incluir en su proyecto el archivo CompropagoSdk/Client.php, el cual le proporcionará el acceso a todas las clases del SDK junto con las dos clases principales de la siguiente forma:

<?php
require_once 'CompropagoSdk/Client.php';

use CompropagoSdk\Client;
Client::register_autoload();

use CompropagoSdk\Factory\Factory;

Instalación por Composer

Puede descargar el SDK directamente desde el repositorio de composer con el siguiente comando:

composer require compropago/php-sdk && composer -o dumpautoload

O si lo prefiere, puede incluir directamente en su archivo composer.json el código abajo descrito y posteriormente deberá correr el comando composer install para instalar las dependencias.

{
    "require": {
        "compropago/php-sdk": "^4.0"
    }
}

Para poder hacer uso de la librería es necesario incluir el archivo principal del SDK junto con las dos clases principales de la siguiente forma:

<?php
require 'vendor/autoload.php';

use CompropagoSdk\Client;
use CompropagoSdk\Factory\Factory;

Configuración


Importación

Para poder hacer uso de la librería es necesario incluir las clases principales de la librería:

use CompropagoSdk\Client;
use CompropagoSdk\Factory\Factory;

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 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.

<?php
# @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 = new Client(
    'pk_test_xxxxxxxxxxxxxxxxx',  # publickey
    'sk_test_xxxxxxxxxxxxxxxxx',  # privatekey
    false                         # live
);

Métodos


listProviders

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

Prototipo
<?php
/**
 * @param float $limit
 * @param string $currency (Default="MXN") Supported Currencies "USD", "EUR" & "GBP"
 * @return array
 * @throws \Exception
 */
public function listProviders($limit = 0, $currency="MXN");

Parámetros
Parámetro Tipo Valor por defecto Descripción
$limit float 0 Límite mínimo que deben de soportar los proveedores listados.
$currency string MXN Divisa en la cual se procesa el campo limit. Los valores soportados son: Pesos mexicanos (MXN), Dolar americano (USD), Euro (EUR), Libra Esterlina (GBP).

Ejemplo
<?php
$providers = $client->api->listProviders();

foreach ($providers as $provider) {
    echo $provider->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
<?php
/**
 * @param \CompropagoSdk\Factory\Models\PlaceOrderInfo $neworder
 * @return \CompropagoSdk\Factory\Models\NewOrderInfo
 * @throws \Exception
 */
public function placeOrder($neworder);

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

Ejemplo
<?php
# 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 float  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      internal_name de un objeto Provider
 * @param string currency          MXN, USD, GBP, EUR
 */
$order_info = [
    'order_id' => 12,
    'order_name' => 'M4 php sdk',
    'order_price' => 123.45,
    'customer_name' => 'Eduardo',
    'customer_email' => '[email protected]',
    'payment_type' => 'SEVEN_ELEVEN',
    'currency' => 'MXN'
];

$order = Factory::getInstanceOf('PlaceOrderInfo', $order_info);

# Llamada al método 'place_order' del API para generar la orden
$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
<?php
/**
 * @param string $orderId
 * @return \CompropagoSdk\Factory\Models\CpOrderInfo
 * @throws \Exception
 */
public function verifyOrder( $orderId );

Parámetros
Parámetro Tipo Valor por defecto Descripción
$orderId string Id generado al registrar una orden en ComproPago

Ejemplo
<?php
# Guardar el ID de la orden
$order_id = "ch_xxxx_xxx_xxx_xxxx";

# U obtenerlo de un objeto NewOrderInfo
$order_id = $neworder->id;

# Se manda llamar al método del API para recuperar la información de la orden
$info = $client->api->verifyOrder($order_id);


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
<?php
/**
 * @param string $number
 * @param string $orderId
 * @return \CompropagoSdk\Factory\Models\SmsInfo
 * @throws \Exception
 */
public function sendSmsInstructions($number, $orderId);

Parámetros
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
<?php
# Numero al cual se enviarán las instrucciones
$phone_number = "55xxxxxxxx";

# Id de la orden de compra de cual se enviarán las instrucciones
$order_id = "ch_xxxxx-xxxxx-xxxxx-xxxxx";

# Llamada al método del API para envío de las instrucciones
$smsinfo = $client->api->sendSmsInstructions($phone_number , $order_id);


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 un arreglo que contiene objetos de tipo Webhook.

Prototipo
<?php
/**
 * @return array
 * @throws \Exception
 */
public function listWebhooks();

Ejemplo
<?php
$webhooks = $client->api->listWebhooks();

foreach ($webhooks as $webhook) {
    echo $webhook->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.

Protptipo
<?php
/**
 * @param string $url
 * @return \CompropagoSdk\Factory\Models\Webhook
 * @throws \Exception
 */
public function createWebhook($url)

Parámetros
Parámetro Tipo Valor por defecto Descripción
$url string Url que será registrada como EndPoint del webhook.

Ejemplo
<?php
# Se pasa como parámetro la URL al 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
<?php
/**
 * @param string $webhookId
 * @param string $url
 * @param string $type (secondary | primary)
 * @return \CompropagoSdk\Factory\Models\Webhook
 * @throws \Exception
 */
public function updateWebhook($webhookId, $url=null, $type=null);

Parámetros
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
$type string Tipo de webhook. puede tomar valores de secondary o primary.

Ejemplo
<?php
$updated_webhook = $client->api->updateWebhook($webhook->id, 'http://sitio.com/nuevo_webhook');


deactiveWebhook

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

Prototipo
<?php
/**
 * @param string $webhookId
 * @return CompropagoSdk\Factory\Models\Webhook
 * @throws Exception
 */
public function deactiveWebhook($webhookId);

Parámetros
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
<?php
$deactive_webhook = $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
<?php
/**
 * @param string $webhookId
 * @return \CompropagoSdk\Factory\Models\Webhook
 * @throws \Exception
 */
public function deleteWebhook($webhookId);

Parámetros
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
<?php
$deleted_webhook = $client->api->deleteWebhook( $webhook->id );


Webhook Endpoint

Los Webhook EndPoints, son rutas a las cuales ComproPago envía las notificaciones de cambio de estatus con las cuales podra generar la lógica necesaria para sus procesos internos en su sitio. A continuación se muestra un ejemplo de la estructura y control de flujo de un Webhook EndPoint con un archivo webhook.php.

Nota: Es importante recalcar que para la correcta recepción de los webhooks, así como la correcta notificación a los servicios de ComproPago, es necesario regresar una cadena de texto siempre que finalice la ejecución de sus rutinas como se muestra a continuación. Tambien se debe de tomar en cuenta que para el procesamiento optimo su sistema no debe de tardar mas de 30 segundos en regresar esta respuesta.

<?php
require_once 'vendor/autoload.php';

use CompropagoSdk\Factory\Factory;
use CompropagoSdk\Client;

$request = @file_get_contents('php://input');

if(!$resp_webhook = Factory::getInstanceOf('CpOrderInfo', $request)){
    die(json_encode([
        'status' => 'error',
        'message' => 'invalid request',
        'short_id' => null,
        'reference' => null
    ]));
}

$publickey     = "pk_live_xxxxxxxxxxxxxxxxxxx";
$privatekey    = "sk_live_xxxxxxxxxxxxxxxxxxx";
$live          = true; // si es modo pruebas cambiar por 'false'

try{
    $client = new Client($publickey, $privatekey, $live );

    if($resp_webhook->short_id == "000000"){
        die(json_encode([
            'status' => 'success',
            'message' => 'OK - test',
            'short_id' => $resp_webhook->short_id,
            'reference' => $resp_webhook->order_info->order_id
        ]));
    }

    $response = $client->api->verifyOrder($resp_webhook->id);

    switch ($response->type){
        case 'charge.success':
            // TODO: Actions on success payment
            break;
        case 'charge.pending':
            // TODO: Actions on pending payment
            break;
        case 'charge.expired':
            // TODO: Actions on expired payment
            break;
        default:
            die(json_encode([
                'status' => 'error',
                'message' => 'invalid webhook type',
                'short_id' => $response->short_id,
                'reference' => $response->order_info->order_id    
            ]));
    }

    die(json_encode([
        'status' => 'success',
        'message' => 'OK - ' . $response->type,
        'short_id' => $resp_webhook->short_id,
        'reference' => $resp_webhook->order_info->order_id
    ]));
}catch (Exception $e) {
    die(json_encode([
        'status' => 'error',
        'message' => $e->getMessage(),
        'short_id' => null,
        'reference' => null    
    ]));
}


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 parámetro 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.