pixelpay-module/README.md

Modulo para integrar pagos con PixelPay

# Pixelpay SDK
Para simplificar las integraciones, PixelPay proporciona un SDK de NodeJS. 

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

**Índice** 

 - [Instalación](#instalación)
 - [Implementación](#implementacion)
 - [Métodos disponibles](#métodos-disponibles)
 - [Uso](#uso)


## Instalación

`npm i pixelpay-module`

# Implementacion
 
``` javascript
	import PixelPay from 'pixelpay-module/pixelpay/sdk';

    //Importacón de estilos.
    @import '~pixelpay-module/pixelpay/css/pixelpay.css'; //scss
    import '~pixelpay-module/pixelpay/css/pixelpay.css'  //js
    
    //Instalación de manera global
    window.Pixelpay = new PixelPay();

    //Agregar llaves del comercio y endpoind
    Pixelpay.setup('2212294583', 'http://pixelpay.test')

```

<!-- `Demo` [https://demo.pixel-pay.com](#!) -->


## Métodos disponibles

### setup(apiKey, endpoint, debug)
Método para agregar la llave del comercio y el endopoind donde se realizar la solicitud del cobro. 

Por defecto el SDK muestra los errores para ayudar a los desarrolladores con la implementacion, pero se puede desactivar pasando `false` como tercer parametro del metodo `setup()`

- `apiKey`/`endpoint`: Revisa [aquí](https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles) la documentación para obtener las llaves del comercio y endpoint. 
- `debug`: Valor boleano para activar/desactivar los errores en la consola del SDK. **(Default TRUE)**

### 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 realizara el cobro
-  `currency*`: String de 3 caracteres. Ejemplo: 'HNL' o 'USD'.

### 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.

### setAlternateAddress(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 elementos con el método `setItemContent()`

- `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 elementos con el método `setItemContent()`

- `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](https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles#ref-callback))

-  `url*`: Valor de tripo string, ejemplo. [https://midominio.com](#!)

<!-- ### setCancel(url)
URL de re-direccionamiento al regresar o cancelar ([ver detalles](https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles#ref-cancel)) 

- `url*`: Valor de tripo string, ejemplo. [https://midominio.com](#!) -->

### setComplete(url)
Método para agregar la URL de re-direccionamiento al pagar con éxito ([ver detalles](https://pixelpay.zendesk.com/hc/es-419/articles/360039834392-Integraci%C3%B3n-Web-y-Apps-M%C3%B3viles#ref-complete))

-  `url*`: Valor de tripo string, ejemplo. [https://midominio.com](#!)

### setItemContent(title, price, qty, description, code, tax)
Método para agregar un variante del producto

-  `title*`: Titulo del producto/factura

-  `price*`: Precio unitario del producto.

-  `qty`: Cantidad de elementos **(Default 1)**

-  `description`: Descripción del producto **(opcional)**

-  `code`: Código o numero de producto/factura **(opcional)**

-  `tax`: Impuesto total del producto(s) en moneda **(opcional)**

### clearItemContent()
Método para eliminar los ítems agregados. 

### setContentExtra(key, value)
Método para agregar valores extraordinarios al pago. 

-  `key`: Llave del objeto JSON
-  `value`: Valor del objeto JSON

Ejemplo:
``` javascript
Pixelpay.setContentExtra('user_id', '123')

//resultado
{
    user_id: '123'
}

```

### setJsonContentExtra(json)
Método para agregar valores extraordinarios al pago en formato JSON. 

Ejemplo.
``` javascript
var obj = {
    nombre:"Pedro Perez",
    nro_cliente : "719827834",
    nro_id : "0501-1988-00237",
    ciudad : "San Pedro Sula"
}

Pixelpay.setJsonContentExtra(obj)
```

### clearConentExtra()
Método para eliminar el contenido extra agregado. 

### sendPayment()
Método para hacer el envió de los datos de cobro y abrir la ventana de pago en un **Iframe** si los [valores mínimos requeridos](#Valores-mínimos-requeridos) están completos.  

- `sendPayment()`: El método retorna una [promesa](https://developer.mozilla.org/es/docs/Web/JavaScript/Referencia/Objetos_globales/Promise) 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 

``` javascript
Pixelpay.sendPayment().then(function(response) {
    console.log(response);
}).catch(function(err) {
    console.error('Error: ', err);
});
```

Ejemplo de respuesta exitosa. 
``` javascript

{
    success: true
    data: {
        payment_hash: "4f971c62bab8334f4d1a44b8c6925344"
        status: "paid"
        uuid: "Ns246RMTI0NTM="
    }
}
```

### isValid()
Retorna `true` o `false` si los [valores minimos requeridos](#Valores-mínimos-requeridos) estan cubiertos.

### closeFrame()
Método para cerrar el modal de pago. 

# Uso 

## Valores mínimos requeridos
|Valor|Método|Retorno|
|-----|------|-----------|
|key|`new  PixelPay('1234567891', 'https://endpoint.com');`|void|
|oder_id|`Pixelpay.setOrderID('EJ101')`|boolean: true|
|amount|`Pixelpay.setAmount(1.55')`|boolean: true|
|fist_name|`Pixelpay.setFirstName('Pedro ')`|boolean: true|
|last_name|`Pixelpay.setLastName('Perez')`|boolean: true|
|email|`Pixelpay.setEmail('example@gmail.com')`|boolean: true|

## Valores opcionales

|Valor|Método|Retorno|
|-------------------|-------------------------------------------------------------------------------------------------------|---------------|
|callback           |`Pixelpay.setCallback('https://midominio.com/callback')`                                               |boolean: true  |
|complete           |`Pixelpay.setComplete('https://midominio.com/callback')`                                               |boolean: true  |
|currency           |`Pixelpay.setCurrency('usd')`                                                                          |boolean: true  |
|tax_amount         |`Pixelpay.setTaxAmount(1.75')`                                                                         |boolean: true  |
|shipping_amount    |`Pixelpay.setShippingAmount(2.00')`                                                                    |boolean: true  |
|address            |`Pixelpay.setAddres('Avenida universo')`                                                               |boolean: true  |
|address_alt        |`Pixelpay.setAlternateAddress('Circuito Holstein')`                                                    |boolean: true  |
|zip                |`Pixelpay.setZip('48290')`                                                                             |boolean: true  |
|city               |`Pixelpay.setCity('San Pedro Sula')`                                                                   |boolean: true  |
|state              |`Pixelpay.setState('Jalisco'')`                                                                        |boolean: true  |
|country            |`Pixelpay.setCountry('Honduras')`                                                                      |boolean: true  |
|order_content      |`Pixelpay.setItemContent('Talla Chica', 2', 2, 'Camisa de Linterna Verde', 'LV100', 1.00)`             |boolean: true  |
|order_extras       |`Pixelpay.setContentExtra('user_id', 15)`                                                              |boolean: true  |
|order_extras       |`Pixelpay.setJsonContentExtra(obj)`                                                                    |boolean: true  |

## Otros Metodos

|Descripción                                        |Método                 |Retorno                                        |
|---------------------------------------------------|-----------------------|-----------------------------------------------|
|Verifica si los valores minimos estan cubiertos    |`isValid()`            |boolean: true/false                            |
|Envia los datos del pago a PixelPay                |`sendPayment()`        |promesa                                        |
|Cierra la ventana de pago de PixelPay              |`closeFrame()`         | void                                          |
|Elimina los items agregados                        |`clearItemContent()`   |boolean: true                                  |
|Elimina el contenido extra agregado                |`clearConentExtra()`   |boolean: true                                  |