Envio de Cobros (API)

Enviá cobros a través de correo electrónico, 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.

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 y Secret Key desde nuestra plataforma PixelPay el cual sera utilizado mas adelante en el campo key y hash.

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.

Campo Secret Key

El campo Secret Key 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 Key ID y Secret Key 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 y Secret Key.

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
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 (ver estructura content)

Detalles de la ruta

Ruta para envió de parámetros:
https://pay.pixel.hn/api-v2/generate GET

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 un solo valor en 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.

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:

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

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

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.

Referencias

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

Webhook URL de Éxito

La URL de Exito se ejecutara 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.

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

Ejemplo • Objeto JSON de URL de Éxito
{
  "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",
  "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",
  }
}

Webhook URL de Error

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"
}