Upgrading to SDK 2.0

• PixelPay SDK
• Sandbox
• Third Party Integration
• Changelog

Following its continuous improvement project, PixelPay has updated its SDK to version 2.0. This new version offers a better experience for affiliate merchants and their customers.

Below is a use case using SDK v1.1.8 and its equivalent using SDK v2.0.x

Version 1.1.8

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

// Card object creation
var card = PixelPay.newCard(); 
card.setCardNumber("4111111111111111"); 
card.setCvv("999");
card.setCardHolder("SERGIO PEREZ"); 
card.setExpirationDate("07-23");

// Billing object creation
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");

//Item object creation
var item_1 = PixelPay.newItem();
item_1.setDescription("Videojuego");
item_1.setPrice(800);
item_1.setQuantity(1);

// Order object creation
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);

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

Version 2.0.x

// SDK set up
const settings = new Settings();
settings.setupEndpoint("https://{endpoint}");
settings.setupCredentials("2222222222", "8e68546db84c4aa7988085b6e0fa944c");

// Card object creation
const card = new Card();
card.number = "4111111111111111";
card.cvv2 = "999";
card.cardholder = "SERGIO PEREZ";
card.expire_month = 7;
card.expire_year = 2023;

// Billing object creation
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";

//Item object creation
const item = new Item();
item.code = "00001";
item.title = "Videojuego";
item.price = 800;
item.qty = 1;

// Order object creation
const order = new Order();

// Required information
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);

// addItem automatically totalized the order amount, but this value can also be manually inputted if desired.
order.amount = (item.price*item.qty) + order.tax_amount + order.shipping_amount;

// Generate Payment
const sale = new SaleTransaction();
// sale.withAuthenticationRequest() in case the transaction is eligible for 3DS protection.
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
})

New - Responses and Entities

Responses and entities provide additional information that can be of great importance to developers using the SDK, such as additional documentation in the form of IntelliSense (function parameter information, variables, and SDK modules).

For more information regarding Responses and Entities, click here.

New - Requests

Requests are directives that take the required data from the models and convert it into a proper request that our system can interpret. An example of this would be converting an order with multiple items included to the proper JSON format.

The Requests section includes the necessary methods to create different transaction types:

• SaleTransaction: Creates the request to carry out a direct sale.
• AuthTransaction: Creates the request to authorize a sale. Once the sale is authorized, the merchant can request the capture of the authorized funds through the SDK.
• CaptureTransaction: Creates the request to capture the funds from an authorized sale.
• VoidTransaction: Creates the request to cancel a sale.
• StatusTransaction: Creates the request to obtain the status of a transaction.
• CardTokenization: Creates the request to tokenize a credit/debit card.

For more information regarding Responses and Entities, click here.

New - Resources

Resources provide additional resources that can be of great help for all kinds of integrations.

The types of resources included are:

• Environments (Environment): includes the different types of environment available.
• Locations (Locations): includes a list of relevant location data in compliance with ISO-3166-1 and ISO-3166-2 standards.

For more information regarding Responses and Entities, click here.

New - Exceptions

Exceptions are errors than can occur during a transaction or tokenization process.

There are two type of exceptions within the Requests:

• InvalidCredentialsException: Merchant's credentials are invalid.
• InvalidTransactionTypeException: Invalid transaction type, or transaction is not supported by the platform.

The following components have been updated:

Updated - Models

billing

• The "setters" methods have been removed from the model.
• A new instance is created with billing = new Billing().

Card

• Removed token, customer and reference fields. The deprecated fields cvc, pan, card_holder, exp_month, exp_year and customer_token have been removed. For more details about these changes, click here.
• The "setters" methods have been removed from the model.
• A new instance is created with card = new Card().

InlineRequests

• This model has been removed from version 2.0 of the SDK. Instead, the Entities and Requests classes are used.

Item

• The "setters" methods have been removed from the model.
• The _totalize() method has been renamed totalize().
• A new instance is created with item = new Item().

Responses

• Responses are no longer presented as templates. These have their own directory in version 2.0 of the SDK.

Settings

• The Settings model has been added in version 2.0 of the SDK. This model includes the functions that were previously found in includes/Config.
• In this model all the initial configurations to use the SDK are defined.
• A new instance is created with settings = new Settings().
• Credentials are set with settings.setupEndpoint() and settings.setupCredentials() instead of pixelpay.setup().
• Set the language with settings.setupLanguage() instead of pixelpay.language().
• Set up the sandbox with settings.setupSandbox() instead of pixelpay.sandbox().

Order

• The fields of the Order model have been modified as it follows:

• Removed the addCard() and addBilling() methods from the model.
• The "setters" methods have been removed from the model.
• The _totalize() method has been renamed to totalize().
• A new instance is created with order = new Order().
• The addItem(), addExtra() and totalize() methods have been updated.

Updated - Services

In the new version of the SDK, the previously offered services have been compacted into two classes: Tokenization and Transaction:

• Transaction: service to create direct sales, authorize, capture, cancel or obtain status of transactions.
• A new instance is created with transaction = new Transaction().
• The service has been modified as follows:

• Tokenization: service to tokenize, update, delete or obtain different credit/debit cards within the store.

• A new instance is created with tokenization = new Tokenization().

• The service has been modified as follows:

For more information about services, click here.

Removed - Toast

The toast method for displaying modals in web browsers has been removed, it is recommended to use specialized libraries for this use case.

In the official PixelPay SDK documentation there are examples of the different use cases that can be implemented using version 2.0. To see these examples, click here.

Removed - Modal

The modal service to display a pop-up window when making the payment and entering the card and billing data has been removed for SDK security improvements.

To implement this functionality, the integration must design a custom modal, a login form or even consider the option to redirect to a specific page. In this way, users will be able to enter their card and billing data according to the logic and design that best suits their application and needs.