Saltar al contenido principal
Iniciar sesión

Hosted Payment Gateway

Soporte
  • Actualización
ℹ️ En el siguiente enlace, PixelPay brinda SDK's en diferentes 
tecnologías para facilitar la integración en comercios: 
https://docs.pixelpay.app/docs/es/introduction

 

El Hosted Payment API de PixelPay es una forma sencilla de integrar pagos en Aplicaciones Móviles y Web. El método utilizado es por redireccionamiento.

 

1. Requisitos y Preparación

Para poder comenzar, es necesario tener acceso a una cuenta con permisos de Configuración Api 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.

 

2. Extracción de llaves

Para poder hacer esta integración, necesitarás obtener él Key ID desde tu plataforma PixelPay, el cual será utilizado más adelante en el campo _key.

2.1. Campo Key ID

El campo Key ID es un número que identifica de forma única al mercante y es un valor constante, no se puede cambiar.

Para poder extraer el valor de Key ID inicia sesión en la plataforma web y navega en el menú lateral izquierdo hacia Preferencias 〉Opciones del API. Ahí encontrarás el campo llamado Key ID.

Nota: Si deseas ejecutarlo en nuestro ambiente SandBox, la llave las encuentras aquí.

 

Imagen 1: Key ID en Opciones del API. https://www.pixelpay.app/admin/settings/app

 

ℹ️ En los siguientes enlaces encontrarás más información sobre:
- Iniciar sesión:
https://pixelpay.zendesk.com/hc/es-419/articles/360041553012
- Extraer Key ID en Opciones de API:
https://www.pixelpay.app/admin/settings/app
- Ejecutar en ambiente SandBox:
https://pixelpay.zendesk.com/hc/es-419/articles/360043039752-SandBox#ref-llavesSandBox

 

2.2 Campos adicionales en Webhook

Permite que, al activarla, el sistema incluya información extra dentro de los eventos enviados vía webhook. 
Cuando esta función está habilitada, se agregan los siguientes campos al cuerpo del webhook:

card_issuer Identifica la entidad emisora de la tarjeta utilizada en la transacción.

authorization_id Código único de autorización que genera el procesador o la red de la tarjeta al aprobar la transacción.

 

Imagen 2: Campos adicionales en webhook.

3. Índice de Campos

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

 

Los campos a utilizarse son:

Campo Valor Validación Descripción
_key * 00000000 Requerido, alfanumérico Llave del comercio (Opciones del API)
_client_signature * Alfanumérico Requerido, alfanumérico Firma única de la petición (ver detalles)
_callback https://... Opcional, URL URL asincrónica (equivalente al WebHook) de éxito  (ver detalles) 
_cancel * http(s)://... Requerido, URL URL de redireccionamiento al regresar o cancelar (ver detalles) 
_complete * https://... Requerido, URL URL de redireccionamiento al pagar con éxito (ver detalles) 
_order_id * Alfanumérico Requerido Número 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, array objetos Codificación de un JSON String a base64 (ver estructura content)
_order_extras base64-json  Opcional, array objetos 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:2, max:120 Apellido del cliente
_email * usuario@dominio.com Requerido, email Correo electrónico del cliente
_address Texto corto Opcional Dirección principal del cliente (primer línea)
_address_alt Texto corto Opcional Dirección alternativa del cliente (segunda línea)
_zip 00000 Opcional ZIP address code
_city Texto corto Opcional, min:3, max:120 Nombre de la ciudad del cliente
_state Texto corto Opcional, min:3, max:120 Nombre o código del estado/departamento del cliente
_country Texto corto Opcional, min:3, max:120 Nombre o código del país del cliente
expired_at yyyy/mm/dd hh:mm Opcional,
date 		Fecha de expiración del pago
json true/false Opcional, booleano Incluir en caso de cambiar a modo JSON en respuestas

*Campos requeridos

 

3.1. Detalles de la ruta

Ruta para envío de parámetros:
https://{endpoint}/api/v2/transaction/hosted/other GET/POST 

Ruta para envío de parámetros en ambiente SandBox:
https://{endpoint}/api/v2/transaction/hosted/sandbox  GET/POST

¿Dónde encuentro el DOMINIO que me corresponde?

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 a todo el contenido en caso de un error de validación. Caso contrario, se realizará un redireccionamiento al cobro generado listo para ser pagado.

Las respuestas JSON retornará el status en la llave success y los errores en la llave errors:{}. En caso de no existir un error se retornará la URL del Cobro en la llave url.

Ejemplo • Success response
{
  "success": true,
  "url": "https://www.pixelpay.app/.../checkout"
}
 
Ejemplo • Error response
{
  "success": false,
  "errors" : {
    "_first_name": [
      "El campo first name es obligatorio."
    ],
    ...
  }

 

ℹ️ En el enlace se explica con detalles cómo encontrar el dominio que le corresponde:
https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles#ref-dominio

 

3.2. Referencias

3.2.1. Elemento Base64-JSON

Para poder codificar un valor JSON (no se permiten comillas simples o llaves sin comillas), es necesario convertirlo a JSON string.

Como ejemplo tomaremos esta estructura:

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

Se convierte a JSON string, con resultado:

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

Y luego deberá de ser codificados a Base64 para obtener un resultado como este:

W3sibm9tYnJlIjoiUGVkcm8gUGVyZXoiLCJucm9fY2xpZW50ZSI6IjcxOTgyNzgzNCIsIm5yb19pZCI6IjA1MDEtMTk4OC0wMDIzNyIsImNpdWRhZCI6IlNhbiBQZWRybyBTdWxhIn1d

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(
  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 = encodeURIComponent(base64);

 

3.3. 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 Título del producto/factura

code

 [A-z][0-9] opcional Código o número de producto/factura
price * 0.00 requerido, double Precio unitario
qty * 1 ... n requerido, int, unsigned Cantidad de elementos
tax 0.00 opcional, double Importe del impuesto sobre el artículo por unidad.
total * 0.00 requerido, double

Total sin impuesto del producto x cantidad en moneda

*Campos requeridos

 

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
  },
  ...
]

 

3.4. Detalles de la URL _complete

La URL del campo _complete se ejecutará (redireccionamiento) cuando el cliente final haya realizado con éxito el pago. El request es de tipo GET.

La URL al ejecutarse contendrá un parámetro más 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 concatenará con la actual URL. Si la URL ya contiene parámetros, se procesara antes de ser ejecutada y no existirá ningún conflicto.

 

3.4.1. Comparación de paymentHash 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 elementos 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|82722502afb99875524ca8e9b1fb871a"


 

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 válida.

 

3.5. Detalles de la URL _callback

La URL del campo _callback se ejecutará 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 capturó el contenido.

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

Ejemplo • Respuesta JSON de _callback
{
   "ref":"4oRJCUc0",
   "uuid":"P-a039903a-449c-4911-bf43-85b776284e97",
   "status":"paid",
   "description":"Payment of Order #4oRJCUc0",
   "note":null,
   "category":"router",
   "currency":"HNL",
   "tax_amount":0,
   "amount":1,
   "items":[
      {
         "price":1,
         "title":"Example product",
         "qty":1,
         "total":1,
         "tax":0
      }
   ],
   "customer_name":"Carlos Agaton",
   "customer_email":"carlos@pixel.hn",
   "customer_phone":"99999999",
   "client_ip":null,
   "client_device":"other",
   "order":"4oRJCUc0",
   "payment_hash":"0b3de9ea8cd10f2494360bfc136c77e6",
   "billing_address":"Ave Circunvalacion",
   "billing_state":"HN-CR",
   "billing_city":"San Pedro Sula",
   "billing_country":"HN",
   "billing_zip":"",
   "created_at":"2025-10-28 16:35:33",
   "paid_at":"2025-10-28 16:35:41",
   "transaction_id":"7616909360246842704805",
   "card_account":" \u2022\u2022\u2022\u2022\u2022\u2022 ",
   "card_brand":"visa",
   "card_type":"DEBIT",
   "company_name":"Pruebas Maria 3",
   "company_slug":"pruebas-maria-3",
   "company_key":"BG1561261533",
   "is_overdue":false,
   "payment_url":"https:\/\/pixelpay.dev\/pruebas-maria-3\/P-a039903a-449c-4911-bf43-85b776284e97\/checkout",
   "attach_url":null,
   "extra":{
      “campoAdicional1”:”valor1”,
      “campoAdicional2”:”valor2”,
      “campoAdicional3”:”valor3”,
      “campoAdicional4”:”valor4”
   }
}

 

⚠️Importante: El contenido del campo "extra" de la respuesta, varía según la plantilla
o valores que sean agregados; es decir es un campo dinámico.

 

Si la transacción fue realizada con plan de financiamiento o puntos, la respuesta incluirá tres campos adicionales:

{
 ...
 "installment_type": "extra",
 "installment_months": "12",
 "points_redeem_amount": "100"
}

 

3.6. Detalles de la URL _cancel

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

 

4. Dominio de la ruta:

Ingresa a tu cuenta PixelPay y en la parte superior, en la barra del buscador, encontrarás el dominio.

Como veremos en la siguiente imagen, nuestro dominio en este caso es: pixelpay.app

enlace.png

Imagen 2: Obtener dominio.

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.