Índice
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/sdkInstalación
Implementación
// ES5 Import
;
- 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 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 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;
order;
order;
order;
order;
...
newItem()
Método que genera una variante de producto, retorna un objeto de tipo Item
.
Ejemplo de uso:
var item_1 = PixelPay;
item_1;
item_1;
item_1;
...
order;
...
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 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;
// Requerimientos mínimos
order;
order;
order;
order;
...
PixelPay
;
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 Objeto
con 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'})
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)
url*
: Valor de tipo string, ejemplo. https://midominio.com
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étodoPixelPay.newCard()
addBilling(billing)
Método que popula la información 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()
- Información 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
// 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 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.
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;
// Requerimientos mínimos
order;
order;
order;
order;
// Generar pago
PixelPay
;
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') |
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 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')
Comentarios
0 comentarios
Inicie sesión para dejar un comentario.