@pixelpay/sdk v1.1.8
Pixelpay SDK
Para simplificar las integraciones, PixelPay proporciona un SDK Web/NodeJS.
El SDK brinda una forma sencilla para hacer el envió de los datos de cobro y evita el redireccionamiento al sitio web del proveedor para completar el proceso de pago.
Índice
- 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
- Tokenizacion
- Pagos Inline
- Integración del SDK con Angular
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' 'ae2966c0153bd8d53c4b7b2ac4c27ecd', 'https://endpoint.app');
Demo
https://unpkg.com/@pixelpay/sdk/dist/index.html
Métodos disponibles
setup(apiKey, hash endpoint)
Método para agregar la llave del comercio, la secret Key
y el endopoind 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 deConfiguració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/360050491031endpoint
: 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 boleano 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 objecto 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 envió 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 tipoOrder
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)
toast(Object) El SDK provee una manera de mostrar mensajes por medio de un popup pasando como parámetro un Objetocon las opciones del del mensaje.
Opciones:
- text: Texto que llevara el popup
- type: Tipo del popup (success, error, unknow)
- interval: Tiempo en segundos que durara el popup
- title: TItulo del popup
Ejemplo:
PixelPay.toast({
text: 'Un texto',
type: 'success',
interval: 3,
title: 'Title'
})
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)
Metodo 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)
Metodo 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 metodo 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 metodo 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)
url*
: Valor de tipo string, ejemplo. https://midominio.com
addItem(item)
Método que agrega un objeto tipo Item a la orden
item
: Objeto Item, se puede generar con el métodoPixelPay.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étodoPixelPay.newCard()
addBilling(billing)
Método que popula la informacion del objeto Billing
al 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étodoPixelPay.newBilling()
- Informacion populada: address, city, country, state, zip, phone
addExtra(key, value)
Método para agregar valores extraordinarios al pago.
key
: Llave del objeto JSONvalue
: 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 Card
es necesario haber creado el objeto con el método newCard()
setCardNumber(number)
Agrega los 16 o 18 numeros 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 obtenido 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.
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étodo newOrder()
una ves 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 | PixelPay.setup('1234567891', 'https://endpoint.com'); . |
oder_id | order.setOrderID('EJ101') |
amount | order.setAmount(1.55') |
fist_name | order.setFirstName('Jonh') o .setFullName('Jonh Doe') |
last_name | order.setLastName('Doe') o .setFullName('Jonh Doe') |
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) |
card | order.addCard(Card) |
billing | order.addBilling(Card) |
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 mas información sobre el Tokenizacion puedes revisar la documentación aquí.
El SDK simplifica la integración con el servicio de 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 tokenizacion.
Uso del servicio de tokenización
Para poder acceder a los métodos disponibles de tokenizacion 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 Cardbilling
: 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. Circunvalacion",
"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 Billingcard_token
: Token obtenido en la respuesta al momento de crear la tarjeta.
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.
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.
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 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.
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.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 el 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 metodos disponibles en el SDK debemos llamarlo con la variable global que declaramos como window.PixelPay
Ejemplo:
window.PixelPay.setup('2212294588', 'ae2966c0153bd8d53c4b7b2ac4c27edd', 'https://endpoint.app')
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago