Guía de Actualización a SDK v2.0.x

Siguiendo su proyecto de mejora continua, PixelPay ha actualizado su SDK a la versión 2.0. Esta nueva versión ofrece una mejor experiencia para los comercios afiliados y sus clientes.

A continuación, se muestra un caso de uso utilizando el SDK v1.1.8 y su equivalente utilizando el SDK v2.0.x

Versión 1.1.8

// Configuracion del SDK
PixelPay.setup('2222222222', '8e68546db84c4aa7988085b6e0fa944c', 'https://{endpoint}'); 

// Creación del objeto Card
var card = PixelPay.newCard(); 
card.setCardNumber("4111111111111111"); 
card.setCvv("999");
card.setCardHolder("SERGIO PEREZ"); 
card.setExpirationDate("07-23");

// Creación del objeto Billing 
var billing = PixelPay.newBilling(); 
billing.setCity("San Pedro Sula"); 
billing.setState("HN-CR"); 
billing.setCountry('HN'); 
billing.setZip('21102'); 
billing.setAddress("Ave Circunvalacion"); 
billing.setPhoneNumber("99999999");

// Creación del objeto Item
var item_1 = PixelPay.newItem();
item_1.setDescription("Videojuego");
item_1.setPrice(800);
item_1.setQuantity(1);

// Creación del objeto Order
var order = PixelPay.newOrder();

order.setOrderID("ORDER-88888");
order.setFullName("SERGIO PEREZ");
order.setEmail("sergio.perez@gmail.com");

order.setCallBack("webhook.site");
order.setCurrency("HNL");
order.setTaxAmount(15);
order.setShippingAmount(10);
order.setNote("Nota de la Orden");

order.addItem(item_1);
order.addExtra("Key","Detalles adicionales de la compra");

order.addCard(card);
order.addBilling(billing);

// Generar pago
PixelPay.sale(order).then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

Versión 2.0.x

// Agregar llaves del comercio y endpoint brindado por el banco una vez afiliado
const settings = new Settings();
settings.setupEndpoint("https://{endpoint}");
settings.setupCredentials("2222222222", "8e68546db84c4aa7988085b6e0fa944c");

// Creación del objeto Card
const card = new Card();
card.number = "4111111111111111";
card.cvv2 = "999";
card.cardholder = "SERGIO PEREZ";
card.expire_month = 7;
card.expire_year = 2023;

// Creación del objeto Billing 
const billing = new Billing();
billing.city = "San Pedro Sula";
billing.state = "HN-CR";
billing.country = "HN";
billing.zip = "21102";
billing.address = "Ave Circunvalacion";
billing.phone = "99999999";

// Creación del objeto Item
const item = new Item();
item.code = "00001";
item.title = "Videojuego";
item.price = 800;
item.qty = 1;

// Creación del objeto Order
const order = new Order();

// Requerimientos mínimos
order.id = "ORDER-88888";
order.customer_name = "SERGIO PEREZ";
order.customer_email = "sergio.perez@gmail.com";

order.callback_url = "webhook.site";
order.currency =  "HNL";
order.tax_amount = 15;
order.shipping_amount = 10;
order.note = "Nota de la Orden";

order.addItem(item);
order.addExtra('key', value);

// El método addItem automáticamente calcula el valor amount de la orden, pero este también se puede agregar de manera manual si se desea:
order.amount = (item.price*item.qty) + order.tax_amount + order.shipping_amount;

// Generar pago
const sale = new SaleTransaction();
// sale.withAuthenticationRequest() en caso de solicitar transacciones con protección 3DSecure.
sale.setOrder(order);
sale.setCard(card);
sale.setBilling(billing);

const service = new Transaction(settings);

// with async / await
try {
  const response = await service.doSale(sale);

  if (TransactionResult.validateResponse(response)) {
    const result = TransactionResult.fromResponse(response);

    const validPayment = service.verifyPaymentHash(
      result.payment_hash,
      order.id,
      "abc...", // secret
    )

    if (validPayment) {
      // SUCCESS Valid Payment
    }
  }
} catch (error) {
  // ERROR
}

// with callback
service.doSale(sale).then((response) => {
  if (TransactionResult.validateResponse(response)) {
    const result = TransactionResult.fromResponse(response);

    const validPayment = service.verifyPaymentHash(
      result.payment_hash,
      order.id,
      "abc...", // secret
    )

    if (validPayment) {
      // SUCCESS Valid Payment
    }
  }
}).catch((error) => {
  // ERROR
})

Nuevo - Respuestas y Entidades

Las respuestas y entidades (categorizados como responses y entities dentro del SDK) 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).

Para mayor información sobre las respuestas y entidades, haz clic aquí.

Nuevo - 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.

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 del monto autorizado por medio del SDK.
  • CaptureTransaction: crea la solicitud para capturar el monto 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 mayor información sobre las peticiones, haz clic aquí.

Nuevo - Recursos

Los recursos (categorizados como resources dentro del SDK) proveen recursos adicionales que pueden ser de gran ayuda para todo tipo de integraciones.

Los tipos de recursos incluidos son:

  • Ambientes (Environment): incluye los distintos tipos de entorno que influyen en el funcionamiento del SDK
  • Locaciones (Locations): incluye un listado de datos relevante de locaciones en cumplimiento con las normas ISO-3166-1 e ISO-3166-2

Para mayor información sobre los recursos, haz clic aquí.

Nuevo - Excepciones

Las excepciones (categorizados como exceptions dentro del SDK) son errores que pueden surgir durante una transacción o tokenización. 

Dentro de la categoría de peticiones se incluyen dos tipos de excepciones:

  • InvalidCredentialsException: Es lanzada cuando las credenciales ingresadas del comercio son inválidas.
  • InvalidTransactionTypeException: Es lanzada cuando el tipo de transacción es inválido, o la plataforma no soporta el tipo de transacción enviada.

Además, se han modificado los siguientes componentes:

Actualizado - Modelos

Billing

  • Se han eliminado los métodos "setters" del modelo.
  • Se crea una nueva instancia con billing = new Billing().

Card

  • Se han eliminado los campos token, customer y reference. Los campos deprecados cvc, pan, card_holder, exp_month, exp_year y customer_token han sido eliminados. Para más detalles sobre estos cambios, haz clic aquí.
  • Se han eliminado los métodos "setters" del modelo.
  • Se crea una nueva instancia con card = new Card().

InlineRequests

  • Este modelo se ha eliminado de la versión 2.0 del SDK. En su lugar, se utilizan las clases Entities y Requests.

Item

  • Se han eliminado los métodos "setters" del modelo.
  • El método _totalize() ha sido renombrado totalize().
  • Se crea una nueva instancia con item = new Item().

Responses

  • Las respuestas ya no se presentan como modelos. Estas tienen su propio directorio en la versión 2.0 del SDK.

Settings

  • El modelo Settings ha sido agregado en la versión 2.0 del SDK. Este modelo incluye las funciones que previamente se encontraban en includes/Config.
  • En este modelo se definen todas las configuraciones iniciales para utilizar el SDK.
  • Se crea una nueva instancia con settings = new Settings().
  • Se configuran las credenciales con settings.setupEndpoint() y settings.setupCredentials() en lugar de pixelpay.setup().
  • Se configura el lenguaje con settings.setupLanguage() en lugar de pixelpay.language().
  • Se configura el sandbox con settings.setupSandbox() en lugar de pixelpay.sandbox().

Para configurar el SDK, se necesita extraer el Endpoint, Key ID y Secret Key desde la plataforma.

Es muy importante que el valor del Secret Key se convierta a un MD5 hash. Para más información Ver extracción de endpoint y llaves

Order

  • Los campos del modelo Order han sido modificados de la siguiente manera:
Versión 1.1.8 Versión 2.0.x
_key Campo trasladado a modelo Settings, como auth_key
_callback Variable tipo string callback_url
_cancel Pendiente de asignar en siguiente actualización
_complete Pendiente de asignar en siguiente actualización
_order_id Variable tipo string id
_order_date Eliminado
_order_content Variable tipo Array<Item> content
_card Campo trasladado a modelo Card. El método PaymentTransation.setCard() asigna una tarjeta a una solicitud.
_order_extras Variable tipo Object extras
_currency Variable tipo string currency
_tax_amount Variable tipo number tax_amount
_shipping_amount Variable tipo number shipping_amount
_amount Variable tipo number amount
_full_name Variable tipo string customer_name
_first_name Campo eliminado, este dato se puede obtener de customer_name de ser necesario.
_last_name Campo eliminado, este dato se puede obtener de customer_name de ser necesario.
_email Variable tipo string customer_email
_address Campo trasladado a modelo Billing, como address
_address_alt Eliminado
_zip Campo trasladado a modelo Billing, como zip
_city Campo trasladado a modelo Billing, como city
_state Campo trasladado a modelo Billing, como state
_country Campo trasladado a modelo Billing, como country
_note Variable tipo string note
_phone Campo trasladado a modelo Billing, como phone
_uuid Variable tipo string payment_uuid
env Campo trasladado a modelo Settings, como environment
  • Se han eliminado los métodos addCard() y addBilling() del modelo.
  • Se han eliminado los métodos "setters" del modelo.
  • El método _totalize() ha sido renombrado a totalize().
  • Se crea una nueva instancia con order = new Order().
  • Se han actualizado los métodos addItem(), addExtra() y totalize().

Actualizado - Servicios

En la nueva versión del SDK, se han compactado los servicios previamente ofrecidos en dos clases: Tokenization y Transaction:

  • Transaction: servicio para crear ventas directas, autorizar, capturar, anular u obtener estado de transacciones.
  • Se crea una nueva instancia con transaction = new Transaction().
  • El servicio se ha modificado de la siguiente manera:
Versión 1.1.8 Versión 2.0.x
pixelpay.sale transaction.doSale
pixelpay.auth transaction.doAuth
pixelpay.capture transaction.doCapture
transaction.doVoid
transaction.getStatus

  • Tokenization: servicio para tokenizar, actualizar, eliminar u obtener distintas tarjetas de crédito / débito dentro del comercio.

  • Se crea una nueva instancia con tokenization = new Tokenization().

  • El servicio se ha modificado de la siguiente manera:

Versión 1.1.8 Versión 2.0.x
pixelpay.createCard tokenization.vaultCard
pixelpay.updateCard tokenization.updateCard
pixelpay.getCardMetadata tokenization.showCard
tokenization.showCards
pixelpay.deleteCard tokenization.deleteCard
pixelpay.createCustomer Eliminado
pixelpay.getCardsByCustomer Eliminado

Para más información sobre los servicios, haz clic aquí.

Eliminado - Toast

El método toast para mostrar modales en navegadores web ha sido eliminado, se recomienda utilizar librerías especializadas para este caso de uso.

En la documentación oficial del SDK de PixelPay existen ejemplos de los distintos casos de uso que se pueden implementar utilizándo la versión 2.0. Para ver estos ejemplos, haz clic aquí.

Eliminado - Modal

El servicio de modal para mostrar una ventana emergente al realizar el pago e ingresar los datos de la tarjeta y facturación ha sido retirado con el fin de mejoras en la seguridad del SDK.

Para llevar a cabo esta funcionalidad, en la integración se debe diseñar un modal personalizado, un formulario de ingreso o incluso considerar la opción de realizar una redirección a una página específica. De esta manera, los usuarios podrán ingresar sus datos de tarjeta y facturación de acuerdo a la lógica y diseño que mejor se adapte a su aplicación y necesidades.