background

Documentación

Para Desarrolladores — Integración para ...

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 (Hosted Payment SDK)

El Hosted Payment SDK de PixelPay es una forma mas sencilla para integrar pagos en Aplicaciones Móviles y Web, el método utilizado es por re-direccionamiento.

Ruta para envió de parámetros:

Es muy recomendable usar el método POST para realizar el envío de parámetros a esta ruta. Existen dos tipos de respuestas del request; JSON y HTML.

Las respuestas HTML (Valor por defecto) responde visualmente todo el contenido, en caso de un error de validación, caso contrario se realizara un re-direccionamiento al cobro generado listo para ser pagado.

Las respuestas JSON retornara el status en la llave success y los errores en la llave error, en caso de no existir un error se retornara la URL de re-direccionamiento en la llave url.

Los campos a utilizarse son:

Campo Valor Validación Descripción
_key 00000000 requerido, numérico llave del comercio extraída de las Opciones del API
_callback https://... opcional, url URL asincrónica (equivalente al WebHook) de éxito
_cancel http(s)://... requerido, url URL de re-direccionamiento al regresar o cancelar
_complete https://... requerido, url URL de re-direccionamiento al pagar con éxito
_order_id Alfanumérico requerido numero o identificador único de la orden o pago
_order_date dd-mm-aa hh:mm opcional, timestamp fecha y hora de la orden generada
_order_content base64-json opcional codificacion de un JSON String a base64 (ver estructura content)
_order_extras base64-json opcional codificacion de un JSON String a base64
_currency USD/HNL opcional,size:3,uppercase moneda en la cual se realizara el cobro
_tax_amount 0.00 opcional,double cantidad total del impuesto en moneda
_shipping_amount 0.00 opcional,double cantidad total del valor de envío en moneda
_amount 0.00 requerido,double cantidad total del cobro en moneda
_first_name Texto corto requerido,min:3,max:120 nombre del cliente
_last_name Texto corto requerido,min:3,max:120 apellido del cliente
_email usuario@dominio.com requerido,email correo electrónico del cliente
_address Texto corto requerido dirección principal del cliente (primer linea)
_address_alt Texto corto opcional dirección alternativa del cliente (segunda linea)
_zip 00000 opcional ZIP address code
_city Texto corto requerido,min:3,max:120 nombre de la ciudad del cliente
_state Texto corto requerido,min:3,max:120 nombre o código del estado/departamento del cliente
_country Texto corto requerido,min:3,max:120 nombre o código del país del cliente
json true/false opcional, boleano incluir en caso de cambiar a modo JSON en respuestas

Como crear un elemento Base64-JSON

Para poder codificar un valor JSON (no se permiten comillas simples o llaves sin comillas), es necesario convertirlo en string, como ejemplo tomaremos esta estructura:

{
    "nombre":"Pedro Perez",
    "nro_cliente" : "719827834",
    "nro_id" : "0501-1988-00237",
    "ciudad" : "San Pedro Sula"
}

Luego de convertir estos valores a string, deberán de ser codificados a Base64 para obtener un resultado como este:

ew0KCSJub21icmUiOiJQZWRybyBQZXJleiIsDQoJIm5yb19jbGllbnRlIiA6ICI3MTk4Mjc4MzQiLA0KCSJucm9faWQiIDogIjA1MDEtMTk4OC0wMDIzNyIsDQoJImNpdWRhZCIgOiAiU2FuIFBlZHJvIFN1bGEiDQp9

Muchas veces esta cadena de caracteres contiene valores que no encajan con una codificación correcta en un URL, por lo cual es recomendable codificarlo para URL.

Ejemplo PHP:

$obj_array = array(
    "nombre" => "Pedro Perez",
    "nro_cliente" => "719827834",
    "nro_id" => "0501-1988-00237",
    "ciudad" => "San Pedro Sula"
);
$json = json_encode($obj_array);
$base64 = base64_encode($json);
$order_extras = urlencode($base64);

Ejemplo Javascript:

var obj_array = {
    "nombre":"Pedro Perez",
    "nro_cliente" : "719827834",
    "nro_id" : "0501-1988-00237",
    "ciudad" : "San Pedro Sula"
};
var json = JSON.stringify(obj_array);
var base64 = window.btoa(json);
var order_extras = encodeURI(base64);

Uso del Modulo Web (Librería JS)

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>