Generador de Cobros vía API

1. Envió de Cobros (API)

Envía cobros a través de correo electrónico, ideal para la generación de cobros de forma desatendida a través de un software de terceros o el desarrollo de un módulo para un aplicativo ya existente.

1.1. Requisitos y Preparación

Para poder comenzar es necesario tener acceso a una cuenta con permisos de Configurar 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.

1.2. Extracción de llaves

Para poder hacer esta integración necesitaremos obtener el Key ID y Secret Key desde nuestra plataforma PixelPay el cual será usado más adelante en los campos x-auth-key, x-auth-hash y x-client-signature.

1.2.1. Campo Key ID

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

1.2.2. 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 más 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.

NOTA:

El valor del Secret Key se debe convertir a un SHA512 o MD5.

Imagen 1: Key ID y Secret Key en Opciones del API. 

1.2.3. Campo Firma de Seguridad

El campo Signature es una firma única necesaria para autenticar la transacción, haz clic aquí para ver mas detalles de como generarla.

ℹ️ En los siguientes enlaces encontrarás más información sobre:
- Iniciar sesión:
https://pixelpay.zendesk.com/hc/es-419/articles/360041553012

1.3. Uso de las llaves

Para poder generar cobros automáticos es necesario contar con las llaves del comercio que se utilizarán en los headers de la petición, junto con él Accept: Application/json es importante que la Secret Key no se comparta como se muestra en la aplicación, ya que puede quedar expuesta. 
 

Headers

Accept: application/json
x-auth-key: 12345678
x-auth-hash: 8e68546db84c4aa7988085b6e0fa944c // SHA512 o MD5 del secret Key
x-client-signature: d79bb3dabf0f41b74b11fe7b859af69094283f642482d1bdbd913662951869675ede176b60553c85b1ce1ace4eccbbc06f30b78b28a7797ab3ec070752096002

1.4. Índice 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
order *	Texto corto	Requerido, min:1, max:191	Número de orden del cobro
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 *	[e-mail]	Requerido, email	Correo electrónico del cliente
amount *	0.00	Requerido, doublé	Cantidad total del cobro en moneda
tax_amount	0.00	Opcional, doublé, menor que amount	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_email	[e-mail]	Opcional, email	Correo de usuario o empleado que genera el cobro
expired_at	yyyy/mm/dd hh:mm	Opcional, date	Fecha de expiración del pago, si no se especifica una hora, el pago caducará a las 23:59 del día enviado
attach	...	Opcional, file, max:2000kb	Archivo adjunto tipo pdf/word/excel
extras	{"key":"value", ...}	Opcional, JSON String	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)

*Campos requeridos

1.4.1. Detalles de la ruta

Ruta para envío de parámetros:
https://{endpoint}/api/v2/generatePOST

¿Dónde encuentro el DOMINIO que me corresponde?

Esta ruta es ideal para la generación de cobros de forma desatendida a través de un software de terceros o el desarrollo de un módulo 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 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 cuál es el error, en caso de generar exitosamente el cobro la respuesta tiene como resultado:

Ejemplo • Success response

{
  "success": true,
  "url": "https://www.pixelpay.app/.../checkout"
}

Ejemplo • Error response

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

El campo success nos indicará 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.

ℹ️ 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