Saltar al contenido principal
Iniciar sesión

PixelPay Javascript SDK

IT Support
  • Actualización

Índice 

Introducción 

Instalación

Implementación

Métodos disponibles

Métodos de objeto Item

Métodos de objeto Order

Métodos de objeto Card

Métodos de objeto Billing

Uso

Tokenización

Pagos inline

Integración del SDK con Angular

Introducción 

Para simplificar las integraciones, PixelPay proporciona un SDK Web/NodeJS.

El SDK brinda una forma sencilla para hacer el envío de los datos de cobro y evita el redireccionamiento al sitio web del proveedor para completar el proceso de pago.

Package Oficial: https://www.npmjs.com/package/@pixelpay/sdk
 

Instalación

npm install @pixelpay/sdk --save

 

Implementación

// ES5 Import
import * as PixelPay from '@pixelpay/sdk';

- o -

// CDN Unpkg
<script src="https://unpkg.com/@pixelpay/sdk"></script>
...

// Agregar llaves del comercio y endpoind
Pixelpay.setup('1234567890', '8e68546db84c4aa7988085b6e0fa944c' ,'https://endpoint.app');

Demo https://unpkg.com/@pixelpay/sdk/dist/index.html

 

Métodos disponibles

setup(apiKey, hash, endpoint)

Método para agregar el apiKey , la secret Key y el endpoint  donde se realizará la solicitud del cobro.

Revisa aquí la documentación para obtener las llaves del comercio y endpoint.

  • apiKey: Llave del comercio.
  • hash : Es necesario tener acceso a una cuenta con permisos de Configuración API o ser el administrador de la cuenta y seguir los pasos de extracción de llaves descritos en el siguiente enlace: https://pixelpay.zendesk.com/hc/es-419/articles/360050491031
  • endpoint: URL

Es importante que no se comparta la secret Key como aparece en la plataforma de PixelPay en la sección de Configuración API. La llave secreta se debe preparar con MD5 antes de poder compartirla.

debug(boolean)

Por defecto el SDK muestra los errores para ayudar a los desarrolladores con la implementación, pero se puede desactivar enviando false al método debug() para desactivar los mensajes en la consola.

  • debug: Valor booleano para activar/desactivar los logs y errores en la consola

sandbox()

Cambia el entorno a ambiente de pruebas

newOrder()

Método que genera una nueva orden, retorna un objeto de tipo Order

Ejemplo de uso:

var order = PixelPay.newOrder();

order.setOrderID('AB1234');
order.setFullName('John Doe');
order.setEmail('johndoe@email.test');
order.setAmount(1.99);

...

newItem()

Método que genera una variante de producto, retorna un objeto de tipo Item.

Ejemplo de uso:

var item_1 = PixelPay.newItem();

item_1.setDescription('Bolsa de manzanas');
item_1.setPrice(9.99);
item_1.setQuantity(3);

...

order.addItem(item_1);

...

payOrder(order)

Método para hacer el envío de los datos de cobro y abrir la ventana de pago si los valores mínimos requeridos están completos.

  • order: El parámetro debe de ser de tipo Order que se inicializa con el método .newOrder() y luego se debe de poblar con la información necesaria.

  • payOrder(order): El método retorna una promesa con la repuesta de un pago exitoso si se resuelve correctamente o un mensaje de error en caso de que algo surja inesperadamente o el sistema rechace el pago.

Ejemplo:

var order = PixelPay.newOrder();

// Requerimientos mínimos
order.setOrderID('AB1234');
order.setFullName('John Doe');
order.setEmail('johndoe@email.test');
order.setAmount(1.99);

...

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

 Ejemplo de respuesta exitosa:

{
    success: true,
    hash: "4f971c62bab8334f4d1a44b8c6925344",
    uuid: "Ns246RMTI0NTM="
}

newCard()

Método que genera una tarjeta, retorna un objeto de tipo Card.

newBilling()

Método que genera un objeto para almacenar los datos de facturación del cliente, retorna un objeto de tipo Billing.

toast(Object)

El SDK provee una manera de mostrar mensajes por medio de un popup pasando como parámetro un Objetocon las opciones del mensaje.

Opciones: 

  • text: Texto que llevara el pop-up
  • type: Tipo en segundos del pop-up (success, error, unknow)
  • interval: Tiempo que durara el pop-up
  • title: Título del pop-up

Ejemplo: 

PixelPay.toast({text: 'Un texto', type: 'success', interval: 3, title: 'Title'})

mceclip0.png

Métodos de objeto Item

setCode(value)

Agrega un código, SKU o número al producto (opcional)

  •  value: String

setDescription(value)

Agrega un título o descripción al producto

  • value: String descriptivo del producto

setPrice(value)

Define el precio unitario del producto

  • value: Valor flotante del producto

setQuantity(value)

Define la cantidad de elementos del producto (Default 1) 

  • value: Cantidad de elementos agregados

setTaxAmount(value)

Impuesto total del producto(s) en moneda (opcional) 

  • value: Valor flotante del costo del impuesto del producto

Métodos de objeto Order

setOrderID(string)

Método para agregar el valor del numero de orden de la transacción

  • string*: Valor alfanumérico sin espacios ni caracteres especiales. Numero o identificador único de la orden o pago.

setCurrency(currency)

Método para agregar la moneda en la cual se realizará el cobro

  • currency*: String de 3 caracteres. Ejemplo: 'HNL' o 'USD'.

setNote(value)

Método para incluir una nota a la orden

  • value: El texto no puede incluir caracteres que no sean alfanuméricos y tiene un mínimo requerido de 3 caracteres y un máximo de 300.

setFirstName(value)

Método para agregar el nombre del cliente

  • value*: Valor de tipo string.

setLastName(value)

Método para agregar el apellido del cliente

  • value*: Valor de tipo string.

setCity(value)

Método para agregar la ciudad del cliente

  • value*: Valor de tipo string.

setState(value)

Método para agregar el estado/departamento del cliente

  • value*: Valor de tipo string.

setCountry(value)

Método para agregar el pais del cliente

  • value*: Valor de tipo string.

setZip(value)

Método para agregar el código postal del cliente

  • value*: Valor de tipo string.

setAddress(value)

Método para agregar la dirección del cliente

  • value*: Valor de tipo string.

setReferenceAddress(value)

Método para agregar la dirección alternativa del cliente

  • value*: Valor de tipo string.

setAmount(value)

Método para agregar la cantidad total del cobro en moneda

Nota: Este valor es modificado al momento de hacer la petición si se agregaron ítems a la orden con el método newItem().

  • value*: valor de tipo float

setTaxAmount(value)

Método para agregar la cantidad total del impuesto en moneda

Nota: Este valor es modificado al momento de hacer la petición si se agregaron ítems a la orden con el método newItem().

  • value*: valor de tipo float

setShippingAmount(value)

Método para agregar la cantidad total del valor de envío en moneda

  • value*: valor de tipo float

setEmail(email)

Método para agregar y validar un correo electrónico.

  • email*: Correo electrónico del cliente

setCallBack(url)

Método para agregar la URL asincrónica (equivalente al WebHook) de éxito (ver detalles)

addItem(item)

Método que agrega un objeto tipo Ítem a la orden

  • item: Objeto Ítem, se puede generar con el método PixelPay.newItem()

addCard(card)

Método que agrega un objeto tipo Card a la orden para generar pagos inline.

  • card: Objeto Card, se puede generar con el método PixelPay.newCard()

addBilling(billing)

Método que popula la información del objeto Billingal objeto Order este método es necesario cuando se quiere hacer un pago inline y no se cuenta con el token de la tarjeta.

  • billing: Objeto Billing, se puede generar con el método PixelPay.newBilling()
  • Información populada: address, city, country, state, zip, phone

addExtra(key, value)

Método para agregar valores extraordinarios al pago.

  • key: Llave del objeto JSON
  • value: Valor del objeto JSON

Ejemplo:

...

order.addExtra('user_id', '123')

// resultado
{
    user_id: '123'
}

Métodos del objeto Card

Para poder utilizar los métodos del objeto Cardes necesario haber creado el objeto con el método newCard()

setCardNumber(number)

Agrega los 16 o 18 números de la tarjeta.

  • number: 16 o 18 números de la tarjeta 

setCvv(cvv)

Código de seguridad que se encuentra al reverso de la tarjeta

  • cvv: Número de 3 o 4 dígitos

setCardHolder(holder)

Agrega el nombre y apellido del tarjetahabiente. Debe contener al menos un nombre y un apellido

  • holder: Nombre y apellido del titular de la tarjeta

setExpirationDate(date)

Agrega el mes y año de expiración de la tarjeta.

  • Formato: (MM-YY)

setToken(token) 

Establece el token de una tarjeta.

  • token: Token de la tarjeta obtenida al momento de crearla

setCustomerToken(token) 

Establece el token de un cliente

  • token: Token del cliente obtenido al momento de crearlo

Métodos del objeto Billing

Para poder utilizar los métodos del objeto Billing es necesario haber creado el objeto con el método newBilling()

setCity(value)

Método para agregar la ciudad del cliente

  • value*: Valor de tipo string.

setState(value)

Método para agregar el estado/departamento del cliente

  • value*: Valor de tipo string. Código del estado

setCountry(value)

Método para agregar el pais del cliente

  • value*: Valor de tipo string(2) ISO 3166 ALPHA-2.

setZip(value)

Método para agregar el código postal del cliente

  • value*: Valor de tipo string.

El campo de código postal no es requerido, sin embargo, si es enviado se realizara una evaluación para confirmar el formato del código postal correspondiente al País. A continuación se listan los países donde dicha evaluación del formato del código postal no aplica.

Angola, Bahamas, Belice, Benín, Bolivia, Botsuana, Burkina Faso, Burundi, Camerún, Comoras, República del Congo, República Democrática del Congo, Corea del Norte, Costa de Marfil, Dominica, Emiratos Árabes Unidos, Eritrea, Fiyi, Gabón, Gambia, Ghana, Granada, Guinea Ecuatorial, Guyana, Honduras, Irlanda, Islas Cook, Islas Salomón, Kiribati, Malawi, Mali, Mauritania, Namibia, Nauru, Niue, Panamá, Qatar, República Centroafricana, Ruanda, San Cristóbal y Nieves, Santa Lucía, Santo Tomé y Príncipe, Seychelles, Sierra Leona, Siria, Somalia, Surinám, Tanzania, Timor Oriental, Togo, Tokelau, Tonga, Trinidad y Tobago, Tuvalu, Uganda, Vanuatu, Yemen, Yibuti, Zimbabue, Isla Bouvet.
 

setAddress(value)

Método para agregar la dirección del cliente 

  • value*: Valor de tipo string

setPhoneNumber(phone) 

Método para agregar el número de teléfono del cliente 

  • phone*: Valor de tipo string

Uso

Para poder generar un cobro es necesario haber ejecutado el método setup() con los parámetros requeridos por el método, posteriormente procedemos a generar la orden con la información requerida utilizando el métodonewOrder()una vez llenos los datos mínimos requeridos procedemos a usar el método payOrder() el cual nos devuelve una promesa con la respuesta del cobro como se muestra en el ejemplo:

// Configuracion del SDK
Pixelpay.setup('1234567890', '8e68546db84c4aa7988085b6e0fa944c' ,'https://endpoint.app'); 

// Creacion del objeto Order
var order = PixelPay.newOrder();

// Requerimientos mínimos
order.setOrderID('AB1234');
order.setFullName('John Doe');
order.setEmail('johndoe@email.test');
order.setAmount(1.99);

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

Valores mínimos requeridos

Valor Método
key/hash/endpoint PixelPay.setup('1234567891', '8e68546db84c4aa7988085b6e0fa944c', 'https://endpoint.com');.
oder_id order.setOrderID('EJ101')
amount order.setAmount(1.55')
first_name order.setFirstName('Jonh') or .setFullName('Jonh Doe')
last_name order.lastName('Doe') or .setFullName('Jonh Doe')
email order.setEmail('example@gmail.com')

 

Valores opcionales

Valor Método
callback order.setCallback('https://midominio.com/callback')
currency order.setCurrency('USD')
tax_amount order.setTaxAmount(1.75')
shipping_amount order.setShippingAmount(2.00')
address order.setAddres('Avenida universo')
address_alt order.setAlternateAddress('Circuito Holstein')
zip order.setZip('48290')
city order.setCity('San Pedro Sula')
state order.setState('CR')
country order.setCountry('Honduras')
order_content order.newItem() ...
order_extras order.addExtra('user_id', 15)

 

 

# Válida con tu proveedor, si está disponible esta funcionalidad

Tokenización

El servicio de tokenización de PixelPay permite almacenar información de tarjetas de forma segura utilizando un servicio de tokens que simplifica el proceso de pago y le permite al comercio acceder a una variedad de beneficios adicionales que incluyen: experiencias omnicanal, información sobre los clientes y más.

Para más información sobre el Tokenización puedes revisar la documentación aquí.

 

El SDK simplifica la integración con el servicio de tokenización ofreciendo ya los métodos para tokenizar una tarjeta, actualizar, asociar tarjetas a un usuario o comercio, obtener la información de las tarjetas, obtener las tarjetas asociadas a un cliente y eliminar las tarjetas.

Es importante revisar la documentación del objeto Card y Billing, ya que son necesarios para el servicio de tokenización.

Uso del servicio de tokenización

Para poder acceder a los métodos disponibles de tokenización es necesario acceder a la clase tokenize() del SDK.

createCard(card, billing)

Método hace la petición para generar una nueva tarjeta. Retorna una promesa con la información y token de la tarjeta.

- Card: Objeto de tipo Card

- billing: Objeto de tipo Billing

Ejemplo:

PixelPay.tokenize().createCard(card,billing).then(function(response) { 
    console.log(response)
}).catch(function(err) {
    console.error('Error: ', err);  
});

// Respuesta
{  
"success": true,  
"message": "Response successfully",  
"data": {  
        billing_address: "Ave. Circunvalacion"
        billing_city: "San Pedro"
        billing_country: "HN"
        billing_phone: "95852921"
        billing_state: "CR"
        billing_zip: "21102"
        card_bin: "411111"
        card_hash: "299e830be25d5c6fba8afa8b0a14c3c0"
        card_holder: "Fulano de Tal"
        card_issuer: "JPMORGAN CHASE BANK, N.A."
        card_last: "1111"
        card_network: "visa"
        card_type: "CREDIT"
        cvc: "***"
        exp_month: "10"
        exp_year: "2023"
        pan: "411111******1111"
        status: "active"
        token: "133.1602256370.5f807df2401b74.07346582"
    }  
}

getCardMetadata(card_token)

Método que hace la petición para obtener la información de una tarjeta por medio del token obtenido en la respuesta al momento de crearla.

Ejemplo:

PixelPay.tokenize().getCardMetadata("133.1602256370.5f807df2401b74.07346582").then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

// RESPUESTA
{  
    "success": true,  
    "data": {  
        "status": "active",  
        "pan": "411111******11111",  
        "cvc": "***",  
        "exp_month": "08",  
        "exp_year": "2021",  
        "card_holder": "FULANITO DE TAL ",  
        "card_issuer": "BBVA BANCOMER, S.A.",  
        "card_network": "visa",  
        "card_type": "DEBIT",  
        "card_bin": "411111",  
        "card_last": "1111",  
        "card_hash": "cf03cf812d1014f4688a885ca105b2d9",  
        "billing_address": "Ave. Circunvalación",  
        "billing_city": "San Pedro Sula",  
        "billing_state": "CR",  
        "billing_country": "HN",  
        "billing_zip": "21102",  
        "billing_phone": "95852921",  
        "billing_email": "fulano@gmail.com"  
    }  
}

updateCard(card, billing, card_token)

Método que genera una petición para actualizar información una tarjeta - card: Objeto de tipo Card. - billing: Objeto de tipo Billing - card_token: Token obtenido en la respuesta al momento de crear la tarjeta.

Ejemplo:

PixelPay.tokenize().updateCard(card, billing, "133.1602256370.5f807df2401b74.07346582").then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

// RESPUESTA
{  
    "success": true,  
    "data": {  
        "status": "active",  
        "pan": "411111******11111",  
        "cvc": "***",  
        "exp_month": "08",  
        "exp_year": "2021",  
        "card_holder": "FULANITO ACTUALIZADO ",  
        "card_issuer": "BBVA BANCOMER, S.A.",  
        "card_network": "visa",  
        "card_type": "DEBIT",  
        "card_bin": "411111",  
        "card_last": "1111",  
        "card_hash": "cf03cf812d1014f4688a885ca105b2d9",  
        "billing_address": "Holstein",  
        "billing_city": "San Pedro Sula",  
        "billing_state": "CR",  
        "billing_country": "HN",  
        "billing_zip": "21102",  
        "billing_phone": "95852921",  
        "billing_email": "fulano@gmail.com"  
    }  
}

deleteCard(card_token)

Método que genera una petición para eliminar una tarjeta. - card_token: Token obtenido en la respuesta al momento de crear la tarjeta.

Ejemplo:

PixelPay.tokenize().deleteCard("133.1602256370.5f807df2401b74.07346582").then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

//RESPUESTA
{ "success": true, "message": "Response successfully", "data": true }

createCustomer(email)

Método que genera una petición para crear un nuevo cliente. Retorna una promesa con el token del cliente el cual podremos utilizar para asignarlo a una o varias tarjetas. - email: E-mail del cliente.

Ejemplo:

PixelPay.tokenize().createCustomer("me@gmail.com").then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

//RESPUESTA
{  
    "success": true,  
    "message": "Response successfully",  
    "data": {  
        "email": "fulano@gmail.com",  
        "token": "16020164865f7cd4e61b800525ceb06bc8862932d853a033411e3b7"  
    }  
}

getCardsByCustomer(customer_token)

Este método nos permite obtener las tarjetas asociadas a un cliente. - customer_token: Token obtenido en la respuesta al momento de crear al cliente.

Ejemplo:

PixelPay.tokenize().getCardsByCustomer("16020164865f7cd4e61b800525ceb06bc8862932d853a033411e3b7").then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});

//RESPUESTA
{  
    "success": true,  
    "message": "Response successfully",  
    "data": [  
        {  
        "status": "active",  
        "pan": "411111******11111",  
        "cvc": "***",  
        "exp_month": "08",  
        "exp_year": "2021",  
        "card_holder": "FULANITO ACTUALIZADO ",  
        "card_issuer": "BBVA BANCOMER, S.A.",  
        "card_network": "visa",  
        "card_type": "DEBIT",  
        "card_bin": "411111",  
        "card_last": "1111",  
        "card_hash": "cf03cf812d1014f4688a885ca105b2d9",  
        "billing_address": "Holstein",  
        "billing_city": "San Pedro Sula",  
        "billing_state": "CR",  
        "billing_country": "HN",  
        "billing_zip": "21102",  
        "billing_phone": "95852921",  
        "billing_email": "fulano@gmail.com" 
        }  
    ]  
}

Pagos inline

Los pagos inline son una forma segura de pagar usando PixelPay sin ser redirigidos a otro sitio web o ver el modal de pago e ingresar los datos de la tarjeta y los datos de facturación.

Para poder realizar un Pago Inline es necesario agregar al objeto de la orden de compra una tarjeta (Card) y los datos de facturación (Billing)

Agregar una tarjeta.

Agregar datos de facturación (Opcional si se tiene el token de la tarjeta)

Los datos de facturación y todos los datos de una tarjeta (CVV, NÚMERO DE LA TARJETA, FECHA DE EXPIRACIÓN Y NOMBRE DEL TARJETAHABIENTE) pueden ser omitidos si se cuenta con el token de la tarjeta.

Ejemplo de pago Inline usando token de la tarjeta.

PixelPay.setup('1234567891', 'https://endpoint.com');

//Valores mínimos requeridos de la orden de compra
var order = PixelPay.newOrder();
order.setOrderID('EJ101');
amount  order.setAmount(1.55)
order.order.setFullName('Jonh Doe')
order.setEmail('example@gmail.com')

// Creación del objeto Card
var card = PixelPay.newCard();
card.setToken("133.1602174841.5f7f3f7933ae76.61699479")
order.addCard(card);

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

Ejemplo de pago inline sin token de la tarjeta.

El código postal no es un campo requerido, sin embargo, si es enviado se realiza una evaluación para verificar el formato del código postal referente al país. Revisa aquí los países donde el código postal no es evaluado. 

PixelPay.setup('1234567891', 'https://endpoint.com');

//Valores mínimos requeridos de la orden de compra
var order = PixelPay.newOrder();
order.setOrderID('EJ101');
order.setAmount(1.55)
order.order.setFullName('Jonh Doe')
order.setEmail('example@gmail.com')

// Creación del objeto Card
var card = PixelPay.newCard();
card.setCardNumber("4111125812341234")
card.setCvv("123")
card.setCardHolder("Fulanito Tal")
card.setExpirationDate("06-23")
order.addCard(card);

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

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

Integración del SDK con Angular

Para poder utilizar el SDK en Angular o Ionic/Angular recomendamos utilizar el CDN 

CDN

<script src="https://unpkg.com/@pixelpay/sdk"></script>

Implementación

Debemos colocar el en él archivo el script en el archivo src/index.html y declarar una variable global del SDK donde se vaya a utilizar el servicio del SDK.

Script

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Angular</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
  <app-root></app-root>
  <!-- CDN SDK -->
  <script src="https://unpkg.com/@pixelpay/sdk"></script>
</body>

</html>

Declarar el SDK de manera global

declare global {
  interface Window { PixelPay: any; }
}
window.PixelPay = window.PixelPay || {};

Uso

Para utilizar los métodos disponibles en el SDK debemos llamarlo con la variable global que declaramos como window.PixelPay

Ejemplo:

window.PixelPay.setup('2212294588', 'ae2966c0153bd8d53c4b7b2ac4c27edd', 'https://endpoint.app')

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.

Tecnología de Zendesk