tb-pay v1.1.5

tb-pay

Módulo que ofrece servicios de pagos. Para ello utiliza servicios de terceros ofrecidos a través de distintos módulos.

Instalación:

Para utilizar los servicios de pago es necesario tener instalada la librería tb-pay junto con la librería del servicio que se vaya a utilizar, como por ejemplo tb-pay-payoneer, y tener una cuenta creada para dicho servicio.

Además es importante inicializar la librería en el archivo "boot.js" dentro de app para que estén disponibles los distintos modelos que ofrece el módulo. Para ello incluir la siguiente linea de código dentro de la función Boot:

App.pay.init();

Configuración del servicio:

- Servicios disponibles:

Para poder utilizar un servicio se utilizarán los identificadores de cada uno de ellos.

Los servicios disponibles para pagos son:

• Payonner
  • Nombre de módulo: tb-pay-payoneer
  • Identificador: "payoneer"
  • Página web

Los servicios disponibles para cobros son:

• Stripe
  • Nombre de módulo: tb-pay-stripe
  • Identificador: "stripe"
  • Página web

- Configuración desde interfaz administrativa:

Por el momento la opción de configuración a través de la interfaz de administración no está disponible.

- Configuración manual:

La configuración manual se realiza sobre una colección en la base de datos llamada "tb.configs".

Para ello hay que añadir un nuevo documento cuyo id sea el "payOptions" (Ej. "_id":"payOptions"). Dicho documento debe tener un objeto para cada uno de los servicios que se quiera configurar cuya clave sea el identificador del servicio.

- Configuración del servicio Payoneer:

Para configurar Payoneer se requerirán los siguientes campos:

Un ejemplo de configuración del servicio Payoneer sería el siguiente:

{
    "_id" : "payOptions",
    "payoneer" : {
        "url" : "https://api.sandbox.payoneer.com/v2/programs",
        "username" : <myServiceUsername>,
        "password" : <myServicePassword>,
        "programs" : [ 
            {
                "id" : "100094XXX",
                "currency" : "USD"
            }
        ]
    }
}

- Configuración del servicio Stripe:

Para configurar Stripe se requerirán los siguientes campos:

Un ejemplo de configuración del servicio Payoneer sería el siguiente:

{
    "_id" : "payOptions",
    "stripe" : {
        "apiKey" : <myPrivateApiKey>
    }
}

Funcionalidades

- Obtener de link de registro/login:

Disponible para los servicios: Payoneer

• REST Api:

Petición:

Parámetros en la ruta:

Parámetros del query:

Respuesta:

Ejemplo:

GET: https://a2server.a2system.net:1234/api/v1/srv/pay/registrationlink/payoneer/58ad3fe33e13466beefe91e2?login=false&redirectUrl=www.google.com

• RESPUESTA:

  {
    "url": "https://payouts.sandbox.payoneer.com/partners/lp.aspx?token=6b8d1e788973496239438e81aee28ea4329DCC0A38"
  }

• Código Javascript:

Parámetros:

Respuesta:

Ejemplo:

var service = "payoneer";

var forLogin = true; //Se pide link para login. false si se quiere para registro
var uid = <myUserId> //Identificador del usuario para el que se pide el link

//Datos opcionales 
let data = {
  redirectUrl: <myRedirectUrl>,
  redirectTime: <myRedirectTimeInSeconds>
}

//Opcion 1 : obteniendo un objeto cliente para el servicio.
App.pay.forService(service)
  .then(client => client.createRegistrationLink(uid, data, forLogin));
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

//Opcion 2 : Sin obtener instancia del cliente del servicio. (Se instancia internamente)
App.pay.createRegistrationLink(service, uid, data, forLogin)
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

Ejemplo Respuesta:

{
  "url": "https://payouts.sandbox.payoneer.com/partners/lp.aspx?token=6b8d1e788973496239438e81aee28ea4329DCC0A38"
}

• Modificacion de parámetros:

Al solicitar el link de registro/login se puede pasar información adicional para que aparezca autocompletada en la página web. Para ello se puede configurar un hook para modificar los parámetros que se enviarán en la consulta al servicio.

Ver sección Hooks -> Modificacion de parámetros de petición de enlace de registro

- Realizar un pago:

Disponible para los servicios: Payoneer

• REST Api:

No disponible.

• Código Javascript:

Parámetros:

Respuesta:

Ejemplo:

var service = "payoneer";

var data = {
  "amount":"20.00",
  "currency": "USD",
  "description": "Test payout",
  "uid":<theUserId>
}

//Opcion 1 : obteniendo un objeto cliente para el servicio.
App.pay.forService(service)
  .then(client => client.payout(data));
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

//Opcion 2 : Sin obtener instancia del cliente del servicio. (Se instancia internamente)
App.pay.payout(service, data)
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

- Realizar un cobro:

Disponible para los servicios: Stripe

Charge a user (tb.pay-transactions: in), from a stored account or with a token

• REST Api:

Parámetros en la ruta:

Parámetros del body:

Respuesta:

- Ejemplo REST 1: Cobro con token sin creación de cuenta

POST: https://a2server.a2system.net:1234/api/v1/srv/pay/charge/stripe

Body:

{
  "uid": "59c43f31aeXX437956fffX2e",
  "amount": 0.39,
  "currency": "USD",
  "token": "tok_1CqjooG5RtxSooBrAUdVWn0K",
  "store": false, //False para no crear cuenta
  "description": "My receipt description",
  "statementDescription": "My card statement description"
}

- Ejemplo REST 2: Cobro con token con creación de cuenta

POST: https://a2server.a2system.net:1234/api/v1/srv/pay/charge/stripe

Body:

{
  "uid": "59c43f31aeXX437956fffX2e",
  "amount": 0.39,
  "currency": "USD",
  "token": "tok_1CqjooG5RtxSooBrAUdVWn0K",
  "store": true, //True para crear cuenta
  "description": "My receipt description",
  "statementDescription": "My card statement description"
}

- Ejemplo REST 3: Cobro a cuenta

POST: https://a2server.a2system.net:1234/api/v1/srv/pay/charge/stripe

Body:

{
  "uid": "59c43f31aeXX437956fffX2e",
  "amount": 0.39,
  "currency": "USD",
  "paid":"5b54a20af7bde109c8c0e0e2",
  "description": "My receipt description",
  "statementDescription": "My card statement description"
}

• Código Javascript:

Parámetros:

Respuesta:

Ejemplo:

var service = "stripe";

var data = {
  "uid": "59c43f31aeXX437956fffX2e",
  "amount": 0.39,
  "currency": "USD",
  "token": "tok_1CqjooG5RtxSooBrAUdVWn0K",
  "store": false, //False para no crear cuenta
  "description": "My receipt description",
  "statementDescription": "My card statement description"
}

//Opcion 1 : obteniendo un objeto cliente para el servicio.
App.pay.forService(service)
  .then(client => client.charge(data));
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

//Opcion 2 : Sin obtener instancia del cliente del servicio. (Se instancia internamente)
App.pay.charge(service, data)
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

- Obtener balance del servicio:

Disponible para los servicios: Payoneer, Stripe

• REST Api:

Petición:

Parámetros en la ruta:

Parámetros del query:

Respuesta:

Ejemplo:

GET: https://a2server.a2system.net:1234/api/v1/srv/pay/balance/payoneer?programId=123456789

• RESPUESTA:

  {
  "data": {
    "audit_id": 42874167,
    "code": 0,
    "description": "Success",
    "balance": 19669.36,
    "currency": "USD",
    "fees_due": 0,
    "programId": "123456789"
  },
  "balance": {
    "amount": 19669.36,
    "currency": "USD"
  },
  "service": "payoneer"
}

• Código Javascript:

Parámetros:

Respuesta:

{ "data": { "audit_id": 42875167, "code": 0, "description": "Success", "balance": 19669.36, "currency": "USD", "fees_due": 0, "programId": "100094640" }, "balance": { "amount": 19669.36, "currency": "USD" }, "service": "payoneer" } Ejemplo:

var service = "payoneer";

var data = {
  "programId":"123456789"
}

//Opcion 1 : obteniendo un objeto cliente para el servicio.
App.pay.forService(service)
  .then(client => client.getBalance(data));
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

//Opcion 2 : Sin obtener instancia del cliente del servicio. (Se instancia internamente)
App.pay.getBalance(service, data)
  .then(resp => console.log(resp))
  .catch(err => console.log(err));

• RESPUESTA:

  {
  "data": {
    "audit_id": 42874167,
    "code": 0,
    "description": "Success",
    "balance": 19669.36,
    "currency": "USD",
    "fees_due": 0,
    "programId": "123456789"
  },
  "balance": {
    "amount": 19669.36,
    "currency": "USD"
  },
  "service": "payoneer"
}

Hooks

El módulo dispone de algunas funciones a las que se le puede añadir hooks para modificar la información o para conocer que algún documento cambió.

Para añadir un hook se basta con configurarlo de la siguiente manera, por ejemplo en la función Boot() del archivo boot.js:

  App.pay.post(theHookedFunction, function(...args){
    //...
    // manejar hook
    //...
  });

A continuación se detallarán las distintas funciones a las que se puede añadir un hook.

• Modificacion de parámetros de petición de enlace de registro:

NOTA: Hook relacionado con Funcionalidades -> Obtener de link de registro/login

Al solicitar el link de registro/login se puede pasar información adicional para que aparezca autocompletada en la página web. Para ello se puede configurar un hook para modificar los parámetros que se enviarán en la consulta al servicio.

Dicho hook se debe realizar a la función "prepareRequestLinkPayload" y se puede configurar, por ejemplo, en el momento de inicialización del módulo en el archivo "boot.js", de la siguiente manera:

  App.pay.post("prepareRequestLinkPayload", function(data, res,  next){
    //...
    //se modifica el objeto res para añadir/modificar los valores 
    //...
    next(res);
  });

Los parámetros que se pueden enviar en la peticion del link son los siguientes:

EJEMPLO

El siguiente ejemplo modifica el nombre y el apellido del contacto y añade una dirección

  App.pay.post("prepareRequestLinkPayload", function(data, res,  next){
    res.payee.contact.firstName = usersLoadedFirstName;
    res.payee.contact.lastName = usersLoadedLastName;
    res.payee.address = {
      country: "US",
      state:"NY"
    }
    next(res);
  });

• Evento de modificación de un objeto tb.pay-transactions:

Para recibir un evento cada vez que sea actualizado un objeto 'tb.pay-transactions' basta con añadir un hook.

Dicho hook se debe realizar a la función transactionUpdated y se puede configurar, por ejemplo, en el momento de inicialización del módulo en el archivo "boot.js", de la siguiente manera:

  App.pay.post("transactionUpdated", function(doc){
    //...
    //Manejar evento de transacción modificada
    //...
  });

Modelos

tb.pay-accounts

Modelo de datos que contiene información sobre una cuenta de pago

tb.pay-transactions

Modelo de datos que contiene información sobre una transacción