background

Documentación

Para Desarrolladores — Integración para ...

Documentación del API de PixelPay

Aquí encontrara la guía de integración y uso de las rutas principales para uso externo del API

Indice


Requerimientos en cada ruta

En cada ruta hay 2 campos necesarios que deberán ser incluidos en todo momento, los cuales son key y hash.

NOTA Ambos valores solo pueden ser extraídos desde las preferencias de la cuenta del administrador.

Campo key

El campo key es un numero que identifica de forma única al mercante y es un valor constante, no se puede cambiar.

Para poder extraer el valor de key puede ver las instrucciones en la siguiente imagen:

Extracción del campo key

Campo hash

El campo hash es un valor alfa-numérico de 28 caracteres que puede ser generado en el momento que desee, generar una nueva llave privada periódicamente aumenta la seguridad, pero es opcional para casos en los que un tercero posea la llave y no sea mas necesario otorgarle acceso.

Para poder extraer el valor de hash puede ver las instrucciones en la siguiente imagen:

Extracción del campo hash

Indice de Rutas

Generador de cobros

Esta ruta es ideal para la generación de cobros de forma des-atendida a través de un software de terceros o el desarrollo de un modulo para un aplicativo ya existente.

Los cobros pueden generarse incluso con parámetros adicionales que serán devueltos en el campo extra en los webhooks URL de Éxito y URL de Error.

Se pueden generar dos tipos de cobros, el de pago único donde solo se especifican los detalles de amount y el cobro con detalles en el cual se puede detallar en el campo content en un arreglo, ítem por ítem con su respectivo impuesto.

Estructura del los campos utilizados:

Campo Valor Validación Descripción
subject Texto corto requerido,min:3,max:120 asunto del correo o descripción del cobro
name Texto corto requerido,min:3,max:120 nombre completo del cliente
email usuario@dominio.com requerido,email correo electrónico del cliente
amount 0.00 requerido,double cantidad total del cobro en moneda
tax_amount 0.00 opcional,double cantidad total del impuesto en moneda
note Texto mediano opcional,text,min:3,max:160 nota para incluir en el cobro
currency USD/HNL opcional,size:3,uppercase moneda en la cual se realizara el cobro
user usuario@dominio.com opcional,email correo de usuario o empleado que genera el cobro
attach ... opcional,file,max:2000kb archivo adjunto tipo pdf/word/excel
extras {key:"value", ...} opciona,json contenido extra como parámetros para uso de respuesta en webhook
content {[key:"value",..], ...} opcional,arrayForm,json arreglo de detalles en el cobro

Estructura de cada elemento en el campo content :

Campo Valor Validación Descripción
title Texto corto requerido,min:3,max:60 Titulo del producto/factura
code [A-z][0-9] opcional código o numero de producto/factura
price 0.00 requerido,double precio unitario
qty 1 ... n requerido,int,unsigned cantidad de elementos
tax 0.00 opcional,double impuesto total del producto en moneda
total 0.00 requerido,double total sin impuesto del producto x cantidad en moneda

El resultado generado es en formato json, si el resultado falla, revuelve un campo message en el cual indica cual es el error, en caso de generar exitosamente el cobro la respuesta tiene como resultado:

{
    "success": true,
    "url": "http://pixelpay.test/pixel-sa/bH45y4McEy"
}

El campo success nos indicara el estado del resultado, y el campo url nos devolverá la URL generada en la cual puede utilizarse para enviarse por otros medios o ser compartido.

Resultados y uso de WebHook

Success Webhook

La URL de Exito se ejecutara cada vez que un cobro se haya pagado con éxito, devolviendo una estructura de tipo json :

{
    "id": 161,
    "ref": "REF-0001-1548494036",
    "gateway": "stripe",
    "status": "paid",
    "currency": "HNL",
    "description": "Prueba de Pago",
    "transaction": "ch_1BVos002HvR1VthjSrNfzs13",
    "note": "Entregar el dia de mañana",
    "amount": 100.00,
    "content": [
        {
            "title": "Prueba de Pago",
            "tax": 0,
            "price": "100.00",
            "qty": 1,
            "total": "100.00"
        }
    ],
    "location":{
        "uid": "c4dcb9866c21917689e29ff515fd9047",
        "os": "osx",
        "ip": "190.6.202.246",
        "geo": true,
        "city": "Tegucigalpa",
        "state": "Departamento de Francisco Morazan",
        "country": "Honduras",
        "isp": "Cablecolor S.A.",
        "lat": 14.10000038147,
        "lon": -87.216697692871,
        "mobile": false
    },
    "created_at": "2017-12-05 11:13:56",
    "paid_at": "2017-12-05 16:26:55",
    "exchange_rate": null,
    "customer":{
        "name": "PEDRO PEREZ",
        "email": "pedro.perez@gmail.com"
    },
    "extra": {
        "codigoCliente":4782164,
        "codigoNegocio":"ATGSH-6712",
        "grupo":"ferreteria"
    },
    "label_status": "Pagado",
    "label_status_color": "success",
    "label_status_description": "El cobro fue pagado con éxito",
    "date": "Dec 05, 2017",
    "total": "L.100.00"
}

El formato del campo extra es opcional y puede ser de estructura escalable.

Fail Webhook

La URL de Error se ejecutara cada vez que un cobro falle o exista un Exception en el código devolviendo un mensaje con el detalle técnico listo para ser reportado al soporte técnico de PixelPay.

Devuelve una estructura de tipo json de la siguiente forma:

{
    "success": false,
    "message": "Fatal error: Maximum execution time of 30 seconds exceeded"
}

Uso del Modulo Web

Integración e Instalación

El modulo web de PixelPay es una librería desarrollada en javascript el cual es de fácil implementación en cualquier sitio o app html.

El primer paso para poder integrar el modulo es necesario incluir la librería jQuery a tu proyecto, verifica que tu versión de jQuery sea mayor o igual a v2.2.4.

Para poder empezar a utilizar la libreria, es necesario primero extraer el snippet desde las preferencias de tu cuenta de PixelPay, para eso iremos a PreferenciasOpciones del APIInserte este código en su sitio y veremos un snippet ya generado para poder ser integrado en nuestro sitio, similar al siguiente ejemplo:

Código de librería para integración

NOTA El snippet solo puede ser extraído desde las preferencias de la cuenta del administrador.

Seleccionamos todo el contenido del snippet y copiamos para luego pegarlo en el proyecto web donde desea integrar el modulo antes de cerrar la etiqueta </body>.

El resultado debería de ser similar al lo siguiente:

<!DOCUMENT html>
<html>
    ...
    <body>
        ...
        <!-- Integrar jQuery antes de implementar pay.js -->
        ...
        <script 
            key="00000000" 
            src="http://pixelpay.test/cdn/pay.js">
        </script>
    </body>
</html>

NOTA La libreria jQuery debera ser integrada antes de poder implementar el snippet.

La etiqueta </script> esta compuesta de 3 atributos, el atributo key es obligatorio y es constante, este nunca cambiara su valor.

El atributo debug es utilizado para habilitar el modo depuración el cual imprimirá en la consola de javascript todos los eventos con sus respectivos detalles, útil para los desarrolladores.

El atributo opacity puede definirse con un valor entre 1.0 a 0.0, definiéndose el valor de opacidad que tendrá el color de fondo del modal (popup/ventana de pago) de PixelPay, el valor por defecto es 0.9 que es el mas recomendado.

Ejemplo con todos los atributos habilitados:
<script
    key="74238979"
    debug="true"
    opacity="0.7"
    src="http://pixelpay.test/cdn/pay.js">
</script>

Como usar y generar un botón de pago

Este proceso es bastante fácil, cualquier etiqueta html puede ser un botón de pago, pero lo mas recomendable es usar las etiquetas </a> , </button> , </img> o </div>.

Para inicializar una etiqueta como botón de pago, los atributos data-payment , data-customer-name y data-customer-email son obligatorios.

Ejemplo de un botón de etiqueta </a> con los requerimientos mínimos:
<a 
    href="#" 
    data-payment="123.99" 
    data-customer-name="Pedro Perez" 
    data-customer-email="pedro.perez@gmail.com">
    Pagar Aquí
</a>

Lista de atributos que pueden ser utilizados:

Atributo Valor Validación Descripción
data-payment 0.00 requerido,double cantidad total del cobro en moneda (incluido el impuesto)
data-tax 0.00 opcional,double cantidad de impuestos del cobro en moneda
data-shipping 0.00 opcional,double cantidad del costo de envio en moneda
data-customer-name Texto corto requerido,min:3,max:120 nombre completo del cliente
data-customer-email usuario@dominio.com requerido,email correo electrónico del cliente
data-order Alfanumérico opcional,recomendado numero o identificador único de la orden o pago
data-description Texto mediano opcional,double descripción o resumen del pago
data-success javascript opcional,code código o método a ejecutarse al finalizar el pago
data-success-url url opcional,url direccion url a redireccionar al finalizar el pago
data-payment-extra {key:"value", ...} opcional,json contenido extra como parámetros para uso de respuesta en webhook
Ejemplo de un botón de etiqueta </a> con todos los atributos:
<a 
    href="#" 
    data-payment="123.99" 
    data-order="0032"
    data-customer-name="Pedro Perez" 
    data-customer-email="pedro.perez@gmail.com"
    data-description="Artículos varios"
    data-success="ejemploDeMetodo()"
    data-payment-extra="{categoria:'ferretero', idCliente: 9018230}">
    Pagar Aquí
</a>