Upgrading to SDK 2.0


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().

To configure the SDK, you need to extract the Endpoint, Key ID and Secret Key from the platform.

It is very important that the Secret Key value is converted to an MD5 hash. For more information See endpoint and key extraction

Order

  • The fields of the Order model have been modified as it follows:
Version 1.1.8 Version 2.0.x
_key Field moved to Settings model, as auth_key
_callback String variable callback_url
_cancel Pending assignment in next update
_complete Pending assignment in next update
_order_id String variable id
_order_date Deleted
_order_content Variable type Array; content
_card Field moved to Card model. The PaymentTransation.setCard() method assigns a card to a request.
_order_extras Variable type Object extras
_currency String variable currency
_tax_amount Variable type number tax_amount
_shipping_amount Variable type number shipping_amount
_amount Variable type number amount
_full_name String variable customer_name
_first_name Field removed, this data can be obtained from customer_name if necessary.
_last_name Field removed, this data can be obtained from customer_name if necessary.
_email String variable customer_email
_address Field moved to Billing model, as address
_address_alt Deleted
_zip Field moved to Billing model, as zip
_city Field moved to Billing model, as city
_state Field moved to Billing model, as state
_country Field moved to Billing model, as country
_note String variable note
_phone Field moved to Billing model, as phone
_uuid String variable payment_uuid
send Field moved to Settings model, as environment
  • 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:
Version 1.1.8 Version 2.0.x
pixelpay.sale transaction.doSale
pixelpay.auth transaction.doAuth
pixelpay.capture transaction.doCapture
transaction.doVoid
transaction.getStatus
  • 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:

Version 1.1.8 Version 2.0.x
pixelpay.createCard tokenization.vaultCard
pixelpay.updateCard tokenization.updateCard
pixelpay.getCardMetadata tokenization.showCard
tokenization.showCards
pixelpay.deleteCard tokenization.deleteCard
pixelpay.createCustomer Deleted
pixelpay.getCardsByCustomer Deleted

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.