Kaching is a simple payments solution for Express-based web app, inspired by Passport.js. Together with various strategies, Kaching provides a unified control flow to hook up with different online payment services.

For now, Kaching only provides kaching-paypal to accepting payment through Paypal. More strategies are under plan.

Install

$ npm install kaching
$ npm install kaching-paypal

Example

https://github.com/gregwym/kaching/tree/master/example

Usage

0. Setup with Kaching

Paypal strategy require the client_id and client_secret offered by Paypal to operate. You can obtain them from https://developer.paypal.com/webapps/developer/applications.

It use api.sandbox.paypal.com as the default paypal host address. Feel free to change it in production environment.

var PaypalStrategy = require('kaching-paypal');
var kaching = require('kaching');

kaching.use(new PaypalStrategy({
  host: '<paypal_rest_api_endpoint>',        // optional
  port: '',                                  // optional
  client_id: '<paypal_client_id>',
  client_secret: '<paypal_client_secret>'
}));

1. Create a payment

Use kaching.create, specifying paypal strategy, to create a Paypal payment. The payment detail should be setup and saved in req.payment prior invoking the create middleware.

After kaching created the pending payment, it replaces req.payment with the real payment object that was returned from Paypal API. Save it securely. (i.e., together with the user's order.)

app.get('...', function(req, res, next) {
  // Setup payment detail in `req.payment`.
  req.payment = {
    amount:{
      total:'7.47',
      currency:'USD'
    },
    redirect_urls: {
      return_url: 'http://<return_url>',
      cancel_url: 'http://<cancel_url>'
    },
    description:'Kaching paypal test transaction'
  };
  next();
}, kaching.create('paypal', {
  // Optional options
}), function(req, res) {
  // Now `req.payment` is the Paypal returned payment object
  res.json(req.payment);
});

2. Redirect user to Paypal to approve the payment

For most of the time, user should redirect to Paypal to complete the payment right away. You can find the page url in payment.links and do whatever you want.

Or simpler, append the kaching.approve middleware after the last request handler. It will redirect the user to the payment approval page.

app.get('...', function(req, res, next) {
  ...
}, kaching.create('paypal', {
  ...
}), function(req, res, next) {
  console.log(JSON.stringify(req.payment));
  next();
}, kaching.approve('paypal'));

If you want to use kaching.approve somewhere else, make sure req.payment contain a valid payment object.

3. Execute the approved payment to complete the transaction

User will be redirect to return_url once the payment has been approved. Paypal will specify the payer_id in req.query.PayerID. This piece of information is required to execute and complete the payment, so save it securely.

Commonly, execute the payment right after can save many trouble. Here is an example,

app.get('<return_route>', function(req, res, next) {
  // Prepare payment information and payerId
  req.payment = ...;           // Fetch the payment object from anywhere it was saved.
  req.payment.payer_id = req.query.PayerID;
  next();
}, kaching.execute('paypal'), function(req, res) {
  res.json(req.payment);       // Now the payment has been completed.
});

Like kaching.create, kaching.execute will update req.payment to the latest. And it's up to you to deal with it.

API

Note: all the middleware look for the payment informations in req.payment. Make sure it is set before passing control to a middleware.

PaypalStrategy(options)

Construct a new strategy.

var options = {
  host: '<paypal_rest_api_endpoint>',        // optional
  port: '',                                  // optional
  client_id: '<paypal_client_id>',
  client_secret: '<paypal_client_secret>'
}

PaypalStrategy#create

Build the payment creation middleware.

It use req.payment as the payment_detail skeleton.

req.payment = {
  intent: '[sale | authorize]',             // default: sale
  payment_method: '[paypal | credit_card]', // default: paypal
  funding_instruments: {                    // required when payment_method = credit_card
    ...   // https://developer.paypal.com/webapps/developer/docs/api/#fundinginstrument-object
  },
  amount: {                                 // required
    ...   // https://developer.paypal.com/webapps/developer/docs/api/#amount-object
  },
  item_list: {                              // optional
    ...   // https://developer.paypal.com/webapps/developer/docs/api/#itemlist-object
  },
  description: 'Payment description',       // optional
  redirect_urls: {                          // required when payment_method = paypal
    return_url: ...,
    cancel_url: ...
  }
};

You may notice that, things like intent, payment_method and redirect_urls are not necessarily be different for each payment. You can set the default value for them when building the middleware.

...
}, kaching.create('paypal', {
  intent: 'sale',
  payment_method: 'paypal',
  redirect_urls: { ... } 
}), 
...

Then you can omit these fields in req.payment.

PaypalStrategy#approve

Build the payment approval middleware. Mainly redirect to the approval_url in payment.links.

PaypalStrategy#execute

Build the approved payment execution middleware. The middleware find the payment in req.payment and execute it with req.payment.payer_id.

Credits

• Greg Wang

License

The MIT License

Copyright (c) 2013 Greg Wang http://gregwym.info/