logo

Introducción


Con ComproPago puede recibir pagos vía SPEI y en efectivo.

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 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": "*"
    }
}

Importación

Para poder hacer uso de la librería es necesario incluir el archivo principal del SDK junto con la clase principal del método de pago deseado de la siguiente forma:

<?php
# Agregar el archivo autoload.php
require 'vendor/autoload.php';

# Importar objeto Spei
use CompropagoSdk\Resources\Payments\Spei;

# Importar objeto Cash
use CompropagoSdk\Resources\Payments\Cash;

Instalación por GitHub

Puede descargar la ultima versión estable que hemos publicado aquí, o si lo desea puede clonar nuestro repositorio (puede ser una versión inestable) de la siguiente forma:

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

Configuración


La clase Spei y la clase Cash corresponden a las clases principales del SDK por cada método de pago disponible en ComproPago y es con las cuales se tiene acceso a todas las funcionalidades del API.

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 Spei o Cash. Tus llaves las encontrarás en su Panel de ComproPago en el menú Configuración o dando clic aquí.

Instacia de objecto Spei para cobros mediante transferencia:
<?php
/**
 * Configuración de las llaves de ComproPago
 * 
 * @param string $public   Llave pública correspondiente al modo de la tienda
 * @param string $private  Llave privada correspondiente al modo de la tienda
 */
$compropagoSpei = (new Spei)->withKeys(
    'pk_test_xxxxxxxxxxxxxxxxxx',
    'sk_test_xxxxxxxxxxxxxxxxxx'
);
Instacia de objecto Cash para cobros en efectivo:
<?php
/**
 * Configuración de las llaves de ComproPago
 * 
 * @param string $public   Llave pública correspondiente al modo de la tienda
 * @param string $private  Llave privada correspondiente al modo de la tienda
 */
$compropagoCash = (new Cash)->withKeys(
    'pk_test_xxxxxxxxxxxxxxxxxx',
    'sk_test_xxxxxxxxxxxxxxxxxx'
);

Métodos para generar de ordenes


Por transferencia (SPEI)

createOrder

Éste método le permite registrar órdenes en las cuales sus clientes podrán pagar posteriormente mediante transferencia interbancaria. El método recibe como parámetro un array con información de la orden y devuelve como resultado un array, el cual contendrá la información resultante de la generación de la orden.

Prototipo:
<?php
/**
 * @param array $orderInfo  Información de la orden
 * @return array
 * @throws \Exception
 */
public function createOrder($orderInfo);
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$orderInfo array Array con la información de la orden que sera generada.
Ejemplo:
<?php
# Crear array con información de la orden
$orderInfo = [
    "product" => [
        "id" => "10001",
        "price" => 258.99,
        "name" => "Test ComproPago SPEI",
        "currency" => "MXN",
        "url" => "http://dummyurl.com/prod10001.jpg"
    ],
    "customer" => [
        "id" => "123454",
        "name" => "Nombre del Cliente",
        "email" => "[email protected]",
        "phone" => "55222999888"
    ],
    "payment" =>  [
        "type" => "SPEI"
    ],
    "expiresAt" => 1563579320 
];

# Llamada al método del API para generar una orden de pago por transferencia
$order = $compropagoSpei->createOrder($orderInfo);
Parámetros de entrada del array:
Propiedad Tipo Descripción Requerido
product array Array con la información del producto o servicio. Si
  id string Identificador del producto o servicio. Si
  price string Monto total del producto o servicio. Si
  name string Nombre del producto o servicio. Si
  currency string Divisa del producto o servicio. Soporta los siguientes valores:
  • MXN: Pesos (Por default)
  • USD: Dolar americano
  • EUR: Euro
  • GBP: Libra Esterlina
Opcional
  url string URL de la imagen del producto o servicio Opcional
customer array Array con la información del cliente. Si
  id string Identificador del cliente (ejemplo: matricula de alumno); se usa para devolver la misma CLABE al cliente que realizará el pago. Opcional
  name string Nombre completo del cliente. Si
  email string Correo electrónico del cliente. Si
  phone string Teléfono del cliente. Opcional
payment array Array con información del método de pago. Si
  type string Tipo de pago a procesar. Si
expiresAt integer Define el tiempo en que se expiran las ordenes, se recibe en formato epoch. Opcional
verifyOrder

Para verificar el estatus de una orden generada es necesario llamar al método verifyOrder que se provee del objeto Spei y el cual regresa un array con la información de la orden. Éste método recibe como parámetro el ID generado por ComproPago para cada orden. También puede obtener éste ID accediendo al elemento ID almacenado al crear una nueva orden.

Prototipo:
<?php
/**
 * @param string $orderId   ID de la orden generada por medio de SPEI
 * @return array            Estructura con información de la orden generada en SPEI
 * @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
# Obtener el ID de la orden generada por medio de la clase 'Spei'
$orderId = $order['data']['id'];

# Llamada al método del API para recuperar la información de la orden de pago
$verified = $compropagoSpei->verifyOrder($orderId);

Mediante pago en efectivo

getProviders

La función getProviders le proporciona un listado con los puntos de cobro disponibles para su tienda con parámetros para su facil filtrado, la cual regresa un array de los proveedores y a los cuales puede acceder a sus atributos.

Prototipo:
<?php
/**
 * @param float  $limit     Monto límite que el proveedor puede que aceptar
 * @param string $currency  Moneda para el monto límite
 */
public function getProviders($limit = 0, $currency="MXN");
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$limit float 0 Monto límite que deben de soportar los proveedores listados.
$currency string MXN Divisa en la cual se procesa el parámetro limit. Los valores soportados son:
  • MXN: Pesos
  • USD: Dolar americano
  • EUR: Euro
  • GBP: Libra Esterlina
Ejemplo:
<?php
# Llamada al método del API que recupera lista de proveedores disponibles
$providers = $compropagoCash->getProviders();

foreach ($providers as $provider) {
    echo $provider['name'];
}

# 7Eleven
# Oxxo
# Coppel
# ...
createOrder

Éste método le permite registrar órdenes en las cuales sus clientes podrán pagar posteriormente en el establecimiento de su preferencia. El método recibe como parámetro un array con información de la orden y devuelve como resultado un array el cual contendrá la información resultante de la generación de la orden.

Prototipo:
<?php
/**
 * @param array $orderInfo  Información de la orden
 * @return array
 * @throws \Exception
 */
public function createOrder($orderInfo);
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$orderInfo array Array con la información de la orden que sera generada.
Ejemplo:
<?php
# Crear array con información de la orden
$orderInfo = [
    "order_id" => "10002",
    "order_name" => "Test ComproPago CASH",
    "order_price" => 157.25,
    "image_url" => "http://dummyurl.com/prod10002.jpg",
    "customer_name" => "Nombre del Cliente",
    "customer_email" => "[email protected]",
    "customer_phone" => "55222999888",
    "payment_type" => 'OXXO',
    "currency" => 'MXN'
];

# Llamada al método del API para generar la orden de pago en efectivo
$order = $compropagoCash->createOrder($orderInfo);
Parámetros de entrada del array:
Propiedad Tipo Descripción Requerido
order_id string ID de la orden Si
order_name string Nombre del producto o productos de la orden. Si
order_price float Monto total de la orden. Si
image_url string Imegen del producto o servicio. Opcional
customer_name string Nombre completo del cliente. Si
customer_email string Correo electrónico del cliente. Si
customer_phone string Teléfono del cliente. Opcional
payment_type string internal_name de una propiedad del array providers. Si
currency Divisa del producto o servicio. Soporta los siguientes valores:
  • MXN: Pesos (Por default)
  • USD: Dolar americano
  • EUR: Euro
  • GBP: Libra Esterlina
Opcional
verifyOrder

Para verificar el estatus de una orden generada es necesario llamar al método verifyOrder que se provee del objeto Cash y el cual regresa un array con la información de la orden. Éste método recibe como parámetro el ID generado por ComproPago para cada orden. También puede obtener éste ID accediendo al elemento ID almacenado al crear una nueva orden.

Prototipo:
<?php
/**
 * @param string $orderId   ID de la orden generada por medio de efectivo
 * @return array            Estructura con información de la orden generada en efectivo
 * @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
# Obtener el ID de la orden generada por medio de la clase 'Cash'
$orderId = $order['id'];

# Llamada al método del API para recuperar la información de la orden de pago
$verified = $compropagoCash->verifyOrder($orderId);

Enviar instrucciones por SMS

Para poder enviar las instrucciones de pago mediante mensajes SMS, deberá crear una instancia del objecto Sms y posteriormente configurar sus llaves de acceso.
Prototipo:
<?php
/**
 * @param $phoneNumber  Número al cual se enviaran las instrucciones
 * @param $orderId      Id de la orden de compra de la cual se enviaran las instrucciones
 */
public function sendToOrder($phoneNumber, $orderId);
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$phoneNumber 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
# Importar objeto Sms
use CompropagoSdk\Resources\Sms;

# Configuración de las llaves de ComproPago
$compropagoSms = (new Sms)->withKeys(
    'pk_test_xxxxxxxxxxxxxxxxxx',
    'sk_test_xxxxxxxxxxxxxxxxxx'
);

# Llamada al método del API para envío de las instrucciones por SMS
$smsInfo = $compropagoSms->sendToOrder(
    "55xxxxxxxx",
    "ch_xxxxx-xxxxx-xxxxx-xxxxx"
);

Webhooks


Los webhooks son de suma importancia para el procesamiento de las ordenes de ComproPago, estos se encargaran de recibir las notificaciones del cambio en los estatus en las ordenes de compra generadas; también deberán contener parte de la lógica de aprobación en su tienda en linea. El proceso que siguen es el siguiente.

create

Para crear un nuevo Webhook en la cuenta, se debe de llamar al método create que se encuentra alojado en el atributo API del objeto Webhook y el cual regresa un array con los datos del Webhook registrado.

Prototipo:
<?php
/**
 * @param $url
 * @return array
 * @throws \Exception
 */
public function create($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 del webhook de su sitio o tienda en línea
$webhookInfo = $compropagoWebhook->create("https://mitienda.com/webhook");
getAll

Para obtener la lista de webhooks registrados en una cuenta, se debe de llamar al método getAll que se encuentra alojado en el atributo API del objeto Webhook y el cual regresa un array que contiene los detalles de los webhooks.

Prototipo:
<?php
/**
 * @return array
 * @throws \Exception
 */
public function getAll()
Ejemplo:
<?php
# Llamada al método del API para listar los webhooks
$webhooks = $compropagoWebhook->getAll();

foreach ($webhooks as $webhook) {
    echo $webhook["url"];
}

# https://mitienda.com/webhook 
# ...
update

Para modificar la url de un webhook previamente registrado, se debe de llamar al método update que se encuentra alojado en el atributo API del objeto Webhook y el cual regresa un array con los datos del nuevo Webhook registrado.

Prototipo:
<?php
/**
 * @param string $webhookId
 * @param string $url
 * @return array
 * @throws \Exception
 */
public function update($webhookId, $url)
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$webhookId string ID de un webhook previamente registrado.
$url string URL que reeplazara a la registrada anteriormente como endpoint del webhook.
Ejemplo:
<?php
# Llamada al método del API para actualizar el webhook
$webhook = $compropagoWebhook->update($webhook['id'], "https://tienda.com/webhook2");
delete

Para eliminar la url de un webhook registrado con anterioridad, debera llamar al método delete que se encuentra alojado en el atributo API del objeto Webhook y el cual regresa un array con los datos del webhook eliminado.

Prototipo:
<?php
/**
 * @param string $webhookId
 * @return array
 * @throws \Exception
 */
public function delete($webhookId)
Parámetros:
Parámetro Tipo Valor por defecto Descripción
$webhookId string ID de un webhook previamente registrado.
Ejemplo:
<?php
# Llamada al método del API para eliminar un webhook
$webhook = $compropagoWebhook->delete($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.

Dentro del parámetro src del Iframe, se debe especificar la ruta del recibo, la cual contiene el parámetro confirmation_id el cual debera contener el Id de la orden generada, el cual se puede obtener por los métodos verifyOrder ya sea de Spei o Cash.

Ejemplo:
<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>