Introducción


La librería de ComproPago SDK C#.NET te permite interactuar con el API de ComproPago en 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 puede recibir pagos en 7Eleven, Extra, y más tiendas en todo México.

Requerimientos


  • NET framework 4.x
  • Newtonsoft.Json 9.0.1

Referencias

  • Microsoft.CSharp
  • Newtonsoft.Json
  • System
  • System.Core
  • System.Data
  • System.Data.DataSetExtensions
  • System.Net.Http
  • System.Web
  • System.Web.Extensions
  • System.Xml
  • System.Xml.Linq

Instalación


Puede descargar la última versión estable desde los repositorios de NuGet. El repositorio del SDK es el siguiente: https://www.nuget.org/packages/ComproPago.
O bien puede instalarlo directamente desde el manager de Nuget en Visual Studio o desde el Package Manager Console de la siguiente forma:

PM> Install-Package ComproPago

O usando .NET CLI

dotnet add package ComproPago

Puede descargar alguna de las versiones que hemos publicado desde aquí o si o lo desea puede clonar el repositorio directamente con el siguiente comando:

git clone https://github.com/compropago/sdk-cs-net.git

Configuración


Importación

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

using CompropagoSdk;
using CompropagoSdk.Factory;

El namespace CompropagoSdk corresponde a la clase principal del SDK y es con la cual se tiene acceso a todas las funcionalidades del API. Por su lado el namespace CompropagoSdk.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 libreria y llamados al API es necesario que primero configures tus Llaves de conexión y crees un instancia de Client. Tus llaves las encontraras en su Panel de ComproPago en el menú Configuración.

/**
 * @param string publickey     Llave publica 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)
 */
var 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 disponobles 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

/**
 * @param double limit    = 0       (default = 0) Limite minimo de transaccion que deberan tener los proveedores a obtener
 * @param string currency = "MXN"   (dafault = MXN) Divisa del monto en el paremetro limit
 * @return Provider[]
 */
public Provider[] ListProviders(double limit = 0, string currency = "MXN");

Parametros
Parámetro Tipo Valor por defecto Descripción
limit double 0 Limite minimo 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(GBP).
Ejemplo

var providers = client.Api.ListProviders();

foreach (var provider in providers)
{
    Console.WriteLine(provider.name);
}

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

placeOrder

Este método le permite registrar ordenes en las cuales sus clientes podran pagar posteriormente. El método recibe como parametro un objeto de tipo PlaceOrderInfo y como resultado genera un objeto de tipo NewOrderInfo la cual contendra la información resultante de la generacón de la orden.

Prototipo

/**
 * @param PlaceOrderInfo info   Objeto con la informacion de la orden de compra
 * @return NewOrderInfo
 */
public NewOrderInfo PlaceOrder(PlaceOrderInfo info);

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

/**
 * @param string order_id          Id de la orden
 * @param string order_name        Nombre del producto o productos de la orden
 * @param double  order_price      Monto total de la orden
 * @param string customer_name     Nombre completo del cliente
 * @param string customer_email    Correo electronico del cliente
 * @param string payment_type      (default = OXXO) 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
 */
var order_info = new Dictionary
{
    {"order_id", "123"},
    {"order_name", "M4 sdk CS.NET"},
    {"order_price", "123.45"},
    {"customer_name", "Eduardo"},
    {"customer_email", "[email protected]"},
    {"payment_type", "SEVEN_ELEVEN"},
    {"currency", "USD"}
};

var order = Factory.PlaceOrderInfo(order_info);

/**
 * Llamada al metodo 'PlaceOrder' del API para generar la orden
 */
var newOrder = client.Api.PlaceOrder(order);

verifyOrder

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

Prototipo

/**
 * @param string orderId        Id de orden generada por ComproPago
 * @return CpOrderInfo
 */
public CpOrderInfo VerifyOrder(string 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
 */
var orderId = "ch_xxxx_xxx_xxx_xxxx";

/**
 * U obtenerlo de un objetdo NewOrderInfo
 */
var orderId = newOrder.id;

/**
 * Se manda llamar al metodo del API para recuperar la informacion de la orden
 */
var 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         Numero al que se enviaran las instrucciones (10 digitos)
 * @param string orderId        Id de orden generada por ComproPago
 * @return SmsInfo
 */
public SmsInfo sendSmsInstructions(string number, string orderId);

Parametros
Parámetro Tipo Valor por defecto Descripción
number string Numero telefónico del cliente al cual se enviara el mensaje de taxto.
orderId string ID de la orden de compropago la cual fue generada previamente.
Ejemplo

/**
 * Numero al cual se enviaran las instrucciones
 */
var phoneNumber = "55xxxxxxxx";

/**
 * Id de la orden de compra de cual se enviaran las instrucciones
 */
var orderId = "ch_xxxxx-xxxxx-xxxxx-xxxxx";

/**
 * Llamada al metodo del API para envio de las instrucciones
 */
var 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 un arreglo de objetos tipo Webhook.

Prototipo

/**
 * @return Webhook[]
 */
public Webhook[] ListWebhooks();

Ejemplo

var webhooks = client.Api.ListWebhooks();

foreach (var webhook in webhooks)
{
    Console.WriteLine(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.

Prototipo

/**
 * @param string url            Url del webhook a registrar
 * @return Webhook
 */
public Webhook CreateWebhook(string url);

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

/**
 * Se pasa como paramtro la URL al webhook
 */
var 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       Id del webhook que se desea actualizar
 * @param string url             Url nueva del webhook
 * @return Webhook
 */
public Webhook UpdateWebhook(string webhookId, string url);

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

var updateWebhook = client.Api.UpdateWebhook(webhook.id, newUrl);

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       Id del webhook registrado
 * @return Webhook
 */
public Webhook DeleteWebhook(string webhookId);

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

var updateWebhook = client.Api.DeleteWebhook(webhook.id);

Webhook Endpoint


Los Webhook EndPoints, son rutas a las cuales ComproPago envia 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 controlador WebhookController dentro de ASP.NET MVC.

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.

using System;
using System.IO;
using System.Web.Mvc;
using CompropagoSdk;
using CompropagoSdk.Factory;
using Newtonsoft.Json.Linq;

namespace webhookcs.Controllers
{
    public class WebhookController : Controller
    {
        [HttpPost]
        public ActionResult Index()
        {
            JObject response = new JObject();
            Stream req = Request.InputStream;
            req.Seek(0, SeekOrigin.Begin);
            string json = new StreamReader(req).ReadToEnd();


            var request = Factory.CpOrderInfo(json);

            if (request.id == null || request.id == "")
            {
                response["status"] = "error";
                response["message"] = "invalid request";
                response["short_id"] = null;
                response["reference"] = null;
                return Content(response.ToString(), "application/json");
            }

            var publicKey = "pk_test_638e8b14112423a086";
            var privateKey = "sk_test_9c95e149614142822f";
            var mode = false;

            try
            {
                var client = new Client(publicKey, privateKey, mode);

                if (request.short_id == "000000")
                {
                    response["status"] = "success";
                    response["message"] = "OK - test";
                    response["short_id"] = request.short_id;
                    response["reference"] = null;
                    return Content(response.ToString(), "application/json");
                }


                var verifyed = client.Api.VerifyOrder(request.id);

                switch (verifyed.type)
                {
                    case "charge.success":
                        // TODO: actions for success payments
                        break;
                    case "charge.pending":
                        // TODO: actions for pending payments
                        break;
                    case "charge.expired":
                        // TODO: actions for expired payments
                        break;
                    default:
                        response["status"] = "error";
                        response["message"] = "invalid request type";
                        response["short_id"] = request.short_id;
                        response["reference"] = request.order_info.order_id;
                        return Content(response.ToString(), "application/json");
                }

                response["status"] = "success";
                response["message"] = "OK - " + request.type;
                response["short_id"] = request.short_id;
                response["reference"] = request.order_info.order_id;
                return Content(response.ToString(), "application/json");
            }
            catch (Exception e)
            {
                response["status"] = "error";
                response["message"] = e.Message;
                response["short_id"] = null;
                response["reference"] = null;
                return Content(response.ToString(), "application/json");
            }
        }
    }
}

Iframe de recibo


Para facilitar el despliegue de instrucciones de pago, puedes incluir un Iframe en tu sitio apuntando alos 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>