¿Cómo empezar?

Introducción

El PixelPay SDK permite simplificar tus integraciones de PixelPay en distintos tipos de entornos.

El SDK contiene objetos y funciones que brindan una forma sencilla para enviar los datos de cobro y evita el redireccionamiento al sitio web del proveedor al momento de completar el proceso de pago.

Esta nueva versión del PixelPay SDK es una gran evolución a las versiones anteriores, incluye múltiples mejoras y contiene todas las APIs integradas de manera estandarizada en un solo paquete.

Como buena práctica, todas las funciones del SDK de PixelPay excepto el método withAuthenticationRequest deben de ser llamadas desde el backend de la integración, enviando los datos requeridos desde el frontend de ser necesario.

Estructura

Una de las mejoras del SDK es que sigue un estándar definido. Incluye distintos modelos, respuestas, entidades, excepciones, servicios y demás, estructurados de manera que brinden una experiencia sin fricción para los desarrolladores.

Es muy importante conocer todas las utilidades y clases predefinidas incluidas en el SDK para poder explotar su potencial al máximo.

Modelos

Los modelos (categorizados como models dentro del SDK) brindan clases predefinidas para facilitar la interacción con entidades de PixelPay, como ser tarjetas de crédito, órdenes, facturación, direcciones de entrega, etc.

Estos incluyen todas las definiciones necesarias para cubrir la mayoría de tipos de integración con PixelPay.

Dentro de los modelos podemos encontrar:

  • Settings: configuración del SDK
  • Environment: valores de distintos tipos de entornos
  • Billing: datos de facturación
  • Card: tarjetas de crédito / débito
  • Item: todo tipo de artículos a la venta
  • Order: datos de pedidos

Los modelos son necesarios, ya que son los componentes que fabrican las peticiones.

Peticiones

Las peticiones (categorizados como requests dentro del SDK) son directrices que se encargan de tomar los datos requeridos de los modelos y convertirlos en una solicitud adecuada. La petición luego es enviada al sistema PixelPay. Por ejemplo: convertir nuestro pedido con varios artículos incluidos al formato JSON adecuado.

Dentro de la categoría de peticiones se incluyen las directrices necesarias para realizar los diferentes tipos de pagos:

  • SaleTransaction: crea la solicitud para realizar una venta directa.
  • AuthTransaction: crea la solicitud para autorizar una venta. Una vez autorizada la venta, el comercio puede solicitar la captura de los fondos autorizados por medio del SDK.
  • CaptureTransaction: crea la solicitud para capturar los fondos de una venta autorizada.
  • VoidTransaction: crea la solicitud para anular una venta.
  • StatusTransaction: crea la solicitud para obtener el estado de una transacción.
  • CardTokenization: crea la solicitud para tokenizar una tarjeta de crédito / débito.

Para utilizar los servicios es necesario enviar la información a través de peticiones.

Servicios

Los servicios (categorizados como services dentro del SDK) son los responsables de efectuar la comunicación con los servicios de PixelPay. Al utilizar los servicios, facilmente se construye la solicitud, que luego es enviada a los servidores.

Dentro de los servicios están:

  • Transaction: utilizando este servicio se pueden crear, autorizar, capturar, anular u obtener el estado de todo tipo de ventas dentro del comercio
  • Tokenization: utilizando este servicio se pueden tokenizar, actualizar, eliminar, u obtener distintas tarjetas de crédito / débito dentro del comercio

Los servicios son muy útiles ya que generan las solicitudes a la API de PixelPay.

Respuestas y Entidades

Las respuestas y entidades proveen información adicional que puede ser de mucha importancia para los desarrolladores que utilicen el SDK, como ser documentación adicional en la forma de IntelliSense (información de parámetros de funciones, variables y módulos del SDK).

Respuestas

Dentro de las respuestas (categorizados como responses dentro del SDK) existen todos los distintos tipos de respuestas que se puede obtener al momento de hacer una consulta a los servicios de PixelPay.

Utilizando los tipos de respuestas, se puede determinar si una transacción realizada es exitosa o no. En caso de no ser exitosa, se puede capturar que tipo de error se generó. Todos los tipos de respuestas son equivalentes a uno o varios códigos de respuesta HTTP.

Tipo de respuesta Códigos HTTP Descripción
SuccessResponse 200 Respuesta exitosa
Posiblemente contenga información adicional en data.
ErrorResponse 400 Error general por parte del cliente
NoAccessResponse 401, 403 Error de permisos y/o accesos, el cliente no tiene acceso a este recurso. Puede que no haya enviado las credenciales necesarias o sus credenciales ya hayan expirado
PaymentDeclinedResponse 402 Error de transacción del pago declinada por el servicio
NotFoundResponse 404, 405, 406 No se encontró el recurso
TimeoutResponse 408 Se acabó el tiempo de respuesta del servidor
PreconditionalResponse 412, 418 Error donde las condiciones enviadas por el cliente no concuerdan con las condiciones del servicio
InputErrorResponse 422 Error de entidad enviada por el cliente donde falla la validación de un campo enviado
NetworkFailureResponse 500 Falla de comunicación con el servicio
FailureResponse >500 o falla de red Falla del servicio

Entidades

Las entidades (categorizadas como entities dentro del SDK) proveen aún más información sobre el tipo de respuesta de parte de los servicios.

Todas las respuestas (por ejemplo: en formato JSON) tienen una estructura definida. Por ejemplo, muchas de las transacciones exitosas envían como respuesta una propiedad data. Las entidades ayudan a, dependiendo del tipo de servicio que se utiliza, definir en más detalle que exactamente contiene este componente.

Estructura de Respuesta

El tipo de respuestas que se reciben al interactuar con el servicio de PixelPay tiene un formato definido, dependiendo del tipo de respuesta que se reciba del servicio. Los tipos de respuesta están definidos aquí.

Llave
Tipo
 Descripción
success boolean Define si la solicitud se ejecutó con éxito
message string Mensaje descriptor de la respuesta enviada
data object<string, any> Data devuelta por el servicio, este depende de que servicio se solicita.
errors object<string, string[]> En caso de que haya errores (por ejemplo, valores inválidos en un formulario), se envían todos los campos que hayan causado el error junto con un mensaje descriptivo del error por cada campo.

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "status": "active",
    "mask": "411111******1111",
    "network": "visa",
    "type": "CREDIT",
    "bin": "411111",
    "last": "1111",
    "hash": "33fa2660f8e7c3556b72a3da1f375d535c3f00250b4af18777f950a40c7fcc1489d7c7879a73366f39ef23dfd210b6d74d98d1ec2db63b1797565a38e76bd239",
    "address": "Calle 1",
    "country": "HN",
    "state": "HN-CR",
    "city": "San Pedro Sula",
    "phone": "999-999999999",
    "token": "T-25ae86aa-d4f4-438f-8806-019575782fa0"
  }
}

Ejemplo de respuesta con errores

{
  "success": false,
  "message": "El campo number es obligatorio.",
  "errors": {
    "number": ["El campo number es obligatorio."],
    "cvv2": ["El campo cvv2 es obligatorio."],
    "expire_month": ["El campo expire month es obligatorio."],
    "expire_year": ["El campo expire year es obligatorio."],
    "cardholder": ["El campo cardholder es obligatorio."],
    "address": ["El campo dirección es obligatorio."],
    "country": ["El campo country es obligatorio."],
    "state": ["El campo departamento es obligatorio."],
    "city": ["El campo ciudad es obligatorio."],
    "phone": ["El campo teléfono es obligatorio."]
  }
}

Instalación

Puedes instalar el PixelPay SDK para distintas plataformas:

* El SDK está en proceso de desarrollo

Configuración

Para utilizar PixelPay SDK es necesario hacer una configuración inicial con datos del comercio, como vemos a continuacion.

Los datos necesarios del comercio son:

  • Tipo de ambiente
  • Endpoint
  • Llaves

Ambientes

Al utilizar el SDK se pueden configurar diferentes tipos de entornos, principalmente producción y sandbox. El ambiente sandbox es útil para hacer pruebas de la integración con PixelPay, una vez hechas las pruebas y verificado que la integración funciona, se puede cambiar el ambiente a producción.

Tipos de Ambientes:

  • LIVE (producción)
  • SANDBOX

Endpoint y Llaves

Para utilizar el SDK, es necesario extraer el dominio de la ruta (endpoint) y ciertas llaves asociadas con el comercio de la plataforma de PixelPay. La documentacion muestra como extraer las llaves.