Hosted Payment Gateway

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.

Ultima Actualización: October 15, 2018

Requisitos y Preparación

Para poder comenzar es necesario tener acceso a una cuenta con permisos de Opciones de Desarrollo o ser el administrador de la cuenta.

Ten en cuenta que puedes utilizar esta integración en cualquier lenguaje de código que soporte consultas http/s o implementar una librería capaz de utilizar una instancia de tipo Request y Response.

Extracción de llaves

Para poder hacer esta integración necesitaremos obtener el Key ID desde nuestra plataforma PixelPay el cual sera utilizado mas adelante en el campo _key.

Campo Key ID

El campo Key ID 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 ID iniciaremos sesión en la plataforma web y navegaremos en el menú lateral izquierdo hacia Preferencias 〉 Opciones del API y encontraremos el campo llamado Key ID.

Opciones del API • Captura de pantalla

Indice de Campos

Todos los campos deberán ser enviados como parámetros en la consulta https en formato Query String o incluir en el header el tipo de formato content-type: x-www-form-urlencoded.

Los campos a utilizarse son:

Campo Valor Validación Descripción
_key * 00000000 requerido, numérico llave del comercio (Opciones del API)
_callback https://... opcional, url URL asincrónica (equivalente al WebHook) de éxito (ver detalles)
_cancel * http(s)://... requerido, url URL de re-direccionamiento al regresar o cancelar (ver detalles)
_complete * https://... requerido, url URL de re-direccionamiento al pagar con éxito (ver detalles)
_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 codificación de un JSON String a base64 (ver estructura content)
_order_extras base64-json opcional codificación 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, booleano incluir en caso de cambiar a modo JSON en respuestas

Detalles de la ruta

Ruta para envió de parámetros:
https://pay.pixel.hn/hosted/payment/other GET/POST

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 errors:{}, en caso de no existir un error se retornara la URL del Cobro en la llave url.

Ejemplo • Success response
{
  "success": true,
  "url": "https://pay.pixel.hn/.../checkout"
}

Ejemplo • Error response
{
  "success": false,
  "errors" : {
    "_first_name": [
      "El campo first name es obligatorio."
    ],
    ...
  }
}

Referencias

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);

Estructura del campo _content

El campo _content contiene un arreglo a detalle de cada elemento de la orden, a continuación mostraremos los campos de cada elemento:

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
Ejemplo • Elementos de una orden
[
  {
    "code" : "0000123",
    "title" : "Camiseta Roja",
    "description" : "Talla: XS",
    "tax" : 9.99,
    "price" : 99.99,
    "qty" : 1,
    "total" : 9.99
  },
  {
    "code" : "0000123",
    "title" : "Jeans Pepe",
    "description" : "Talla: 32",
    "tax" : 0.00,
    "price" : 123.99,
    "qty" : 1,
    "total" : 123.99
  },
  ...
]

Detalles de la URL _complete

La URL del campo _complete se ejecutara (re-direccionamiento) cuando el cliente final haya realizado con éxito el pago, el request es de tipo GET.

La URL al ejecutarse contendrá un parámetro mas llamado paymentHash, el cual permitirá comparar el origen de la transacción y poder validarla. El contenido de este parámetro es un hash md5

Ejemplo de una URL _complete:
https://myshop.com/orden/finalizar
Ejemplo de la misma URL _complete en ejecución:
https://myshop.com/orden/finalizar?paymentHash=d2e16e6ef52a45b7468f1da56bba1953

El parámetro paymentHash se concatenara con la actual URL, si la URL ya contiene parámetros se procesara antes de ser ejecutada y no existirá ningún conflicto.

Comparación de paymentHash de forma local y remota

Para poder comparar el paymentHash y verificar que la transacción es real necesitaremos 3 elementos: _order_id, Key ID y Secret Key (extraer llaves) .

Concatenaremos los 3 elemento con el símbolo | entre cada uno en el siguiente orden _order_id|Key ID|Secret Key, a continuación veremos un ejemplo del resultado:

"00000123|7812290000|6020ae5a-e263-40e4-acc4-88be8"

Para finalizar la validación, convertiremos el valor concatenado en un hash md5 y procederemos a compararlo con el parámetro paymentHash. Si ambos hash son iguales (hash remoto == hash local) las URL _complete es valida.

Detalles de la URL _callback

La URL del campo _callback se ejecutara de forma asincrónica cada vez que un cobro se haya pagado con éxito, el request es de tipo POST y su contenido es content-type: application/json.

La URL remota deberá de retornar una respuesta de código 200 para indicar que se capturo el contenido.

En caso de un código de respuesta distinto ó no obtener respuesta de la URL remota se re-programara el envió de datos con un retraso de 5 min. y un máximo de 3 intentos por envío.

Ejemplo • Respuesta JSON de _callback
{
  "ref": "REF-0001-0006350867",
  "uuid": "1dab5ed0",
  "status": "paid",
  "description": null,
  "note": null,
  "currency": "USD",
  "tax_amount": 9.99,
  "amount": 99.99,
  "items": [{
    "code" : "0000123",
    "title" : "Camiseta Roja",
    "description" : "Talla: XS",
    "tax" : 9.99,
    "price" : 99.99,
    "qty" : 1,
    "total" : 9.99
  }],
  "customer_name": "PEDRO PEREZ",
  "customer_email": "pedro.perez@gmail.com",
  "customer_phone": null,
  "client_ip": "180.125.81.220",
  "client_device": "android",
  "order": "XY0001234",
  "created_at": "2017-09-25 03:09:47",
  "paid_at": "2017-10-30 04:10:13",
  "transaction_id": "7398009601",
  "card_account": "4234 •••• •••• 1234",
  "card_brand": "visa",
  "card_type": "debit",
  "company_name": "My Company",
  "company_slug": "my_company",
  "company_key": "7812290000",
  "is_overdue": false,
  "payment_url": "https://pay.pixel.hn/my_company/1dab5ed0/checkout",
  "attach_url": null,
  "extra": {
    "codigoCliente" : "4782164",
    "codigoNegocio" : "ATGSH-6712",
  }
}

Detalles de la URL _cancel

La URL del campo _cancel se ejecutara (re-direccionamiento) cada vez que el cliente final presione sobre el enlace "cancelar orden y regresar", el request es de tipo GET.