Daimyo: Samurai payment gateway integration library

v0.1.5

Created at Herd Hound Copyright (c)2011, by Branko Vukelic [email protected].

Some rights reserved.

Licensed under MIT license (see LICENSE)

Overview

Daimyo (pronounced as dah-e-myoh) is a client library for the Samurai payment gateway from Fee Fighters. By the time 1.0 release is made, Daimyo will support all of Samurai's API, but the current immediate goal is to support the sale transactions and provide robust error reporting facilities.

Daimyo vs samurai-client-nodejs

Daimyo is an unofficial client library for the Samurai gateway. Fee Fighters maintain a fork of Daimyo that is called samurai-client-nodejs. While the latter is meant to address every possible scenario required by all Samurai users, Daimyo was written for the sole purpose of catering the needs of Herd Hound. While I tried to cover the whole Samurai API with Daimyo, not all parts of the API will get equal attention, as Herd Hound itself doesn't use all Samurai functionality.

Of course, this does not mean that Daimyo's developer will not respond to bug reports or refuse to answer your emails. On the contrary, I would be very happy to help you out.

This also doesn't mean that we don't keep an eye on the samurai-client-nodejs. We will merge or copy anything and everything that can benefit Daimyo users (ourselves included). What we won't do is break the Daimyo API for the sake of synchornizing with samurai-client-nodejs, because that would break software that already uses Daimyo.

Status

For now, Daimyo is used in production at Herd Hound. It is still being polished for prime time, but the core functionality should work as documented/expected since v0.0.7. Keep track of changes on Github, and keep an eye on the issue tracker there.

0.1.5 (latest)

• Transactions will now return AVS results as info messages. The actual messages returend by Daimyo will have the AVS result code prepended.

0.1.4

• Fixed bad API URL in transaction module

0.1.3

• Changed API URL for Ashigaru

0.1.2

• Prevent Daimyo from crashing when Samurai responds with HTTP 500.

0.1.1

• Payment token (card object) is no longer required for processing transactions that do not use them (credit, void).

0.1.0

• Fixed issue where _check token verification would fail for credit and void transaction because Samurai does not honor custom data for those transaction types.

0.0.9

• samurai/developers/api_reference#processing-payments-complex

0.0.8

• Rebranded to Herd Hound

0.0.7

• Resolved issue with success flag in transaction responses.
• Ashigaru now supports sandbox parameter for creating sandbox payment methods.
• Fixed failing tests which weren't updated to reflect the changes in 0.0.6 API. The 0.0.6 version of tests are expected to fail (see issue #15), but that doesn't affect correct behavior of documented API.

0.0.6

• Fixed daimyo.Card constructor not handling custom data.
• Removed card.method.custom which was returned after loading a payment method, and which always contained unused, empty object.
• Fixed previously broken checkamd makefile target.
• Fixed Ashigaru not properly handling custom field.
• Made Ashigaru's timeout checking more robust.
• Fixed Daimyo crashing looking for messages in wrong places.

0.0.5

• Prevents crash when invalid token is passed to daimyo.Card constructor.
• If a token is provided, but it's invalid, an error will be thrown. Previous behavior was that it is completely ignored if invalid.
• daimyo.Card constructor will throw a proper DaimyoError on errors, instead of generic Error object as in previous versions.

0.0.4

• allowedCurrencies setting which limits the currencies that can be used
• transaciton.Transaction.process() will check allowed currencies and block transactions that use disallowed currency.
• transaction.Transaction.process() no longer throws exceptions. All errors are passed to the callback instead.
• Ashigaru now supports the custom field.
• checkamd make target now generates file with version number.

0.0.3

• Tamper-proofed all properties set with accessors in daimyo.Card and transaction.Transaction objects.
• Made data and path properties on transaction.Transaction objects set-once properties similar to configuration locking.
• Custom fields are implemented in both daimyo.Card and transaction.Transaction objects. They can store any JSON-serializable object, and that will be stored in Samurai gateway, and restored later with methods like card.load() or when transaction is completed.
• All transaction requests embed a SHA1 hexdigest of 100-character random string, which is checked when the response is received. All transactions will fail the integrity check if this hash doesn't match.
• If methods like daimyo.Card.load() are missing a token, the error will now not be thrown, but passed to the callback instead, like all other methods.

0.0.2

• daimyo no longer has settings property. You should use daimyo.option() to access options instead.
• After calling daimyo.configure() successfully for the first time, configuration will now be permanently locked until you restart the app. This is a feature not a bug. It prevents malicious code from tricking your app into resetting some of the critical Daimyo options.
• Returns a proper 'Declined' error message when the card is declined.

0.0.1

The first release is a public preview release and it's not meant to be production-ready. There are still quite a few things to implement, and error handling is not very robust. Note that API might change as well. For starters, you should not rely on any method that has the @private tag in the inline comments (that do not appear in API documentation, that is), but the public methods may change as well, as well as method signatures.

Although there are unit tests, and Daimyo's development is test-driven, the tests do not currently provide complete coverage, and it is expected that some functionality may break in production. Target for first production-ready Daimyo is v0.1.

Installation

Easiest way to install Daimyo is by using npm:

npm install daimyo

That will install the latest release that we have made. Not that releases prior to 0.1 are not considered production-ready. See the Status section of this file to find out more about the current progress.

Since Daimyo is currently still very beta, if you wish to get a newer version with more features (please don't do this in production, though), you can add it as a dependency to your packages.json like this:

dependencies: {
   ....
  ,"daimyo": "https://github.com/HerdHound/Daimyo/tarball/master"
   ....
}

Using the above method, it is also possible to address individual commits. Go to GitHub, switch to a commit you want to depend on, click the download link, and right-click the tarball button, copy URL, and paste it into your dependency list like above.

Finally, you can clone the Daimyo repository using git and install from the cloned repository:

git clone https://github.com/HerdHound/Daimyo.git
cd /your/project/dir
npm install /path/to/daimyo/clone

Basic usage

var daimyo = require('daimyo');

// Configure Daimyo
daimyo.configure({
  merchantKey: 'xxxxxxxxxxxxxxxxxxxxxxxx',
  processorId: 'xxxxxxxxxxxxxxxxxxxxxxxx',
  apiPassword: 'xxxxxxxxxxxxxxxxxxxxxxxx',
  currency: 'USD', // default
  debug: false, // default, should stay off in production at all costs
  enabled: true, // default
  sandbox: false // default
});

// Using transparent redirect with Express
app.get('/redirect_target', function(req, res, next) {
    var token = req.param('payment_method_token');
    var card = new daimyo.Card({token: token});

    // Create a new transaction
    var transactionData = {
        amount: 100,
        billingReference: 'my billing ref #',
        customerReference: "user's customer ref #",
        type: 'purchase'
    }

    // Process the transaction using the card object
    transaction.process(card, function(err) {

       if (err) {
         // Handle error and return error page
         res.render('sorry', {});
         return;
       }

       if (!transaction.messages.info || 
           transaction.messages.info[0] === 'success') {
         // The transaction was not successful
         res.render('sorry', {messages: transaction.messages});
         return;
       }

       // Ah, finally! All ur moneys are belong to us!
       res.render('kthxbye', {});

       // Don't forget to Email receipt!
       emailReceipt({
         issuer: card.issuer,
         cardNo: '****-****-****-' + card.last4, 
         date: transaction.receipt.createdAt,
         amount: transaction.receipt.amount
       });
    });
});

Using the check as AMD module in browsers

The `lib/check.js`` module contains generic functions for performing various checks on credit cards. It performs Luhn Mod-10 check to ensure that the card number is valid (although the card itself may not be valid), get the name of the issuer, or make sure that the CSC (also called CVV, CVC, or CCV) has the right number of digits, etc. It is always a good idea to perform this check browser-side to ensure that obviously invalid cards do not make it to the system, or that any typing errors are caught early on.

This module can be used in browsers with minimal modifications. For convenience, the checkamd target is provided in the makefile, which builds an AMD module compatible with loaders like RequireJS.

To build the AMD version of check, simply type:

make checkamd

This will result in creation of a new file called check.js in the project directory. The file is not minified. If you want to minify it, you can use tools such as UglifyJS.

To use it, simply require it from your module as usual:

// mymodule.js
define(['jquery', 'check'], function($, check) {
    var cardNumber = $('input[name=card]).val();
    var csc = $('input[name=csc]').val();
    
    var isVaild = check.mod10check(cardNumber) ? true : false;
    var isValid = isValid && check.cscCheck(cardNumber, csc) ? true : false
    
    var issuer = check.getIssuer(cardNumber);
    alert('Your card was issued by ' + issuer);
});

You can find more details on this module in the API documentation.

API documentation

The dox-generated API documentation can be found at herdhound.github.com/Daimyo/. You can also generate the documentation for offline use using the provided makefile. See Offline documentaiton section for instructions.

Offline documentation

You can generate offline documentation for Daimyo using the dox utility from Visionmedia. Install dox by typing:

sudo npm install dox -g

Now you can simpy type make docs in the project directory. The documentation will be generated in a newly created docs directory. To remove the documentation, just type make clean.

Running unit tests

To run unit tests you need Expresso, and should.js. You also need to create a file called test/config.js, and add your keys there:

exports.merchantKey = 'xxxxxxxxxxxxxxxxxxxxxxxx';
exports.apiPassword = 'xxxxxxxxxxxxxxxxxxxxxxxx';
exports.processorId = 'xxxxxxxxxxxxxxxxxxxxxxxx';

The tests are run simply by simply typing make in the project directory. Alternatively, you can type:

expresso /test/*.tests.js

Do not run tests with your live processor. Make sure you are running in a sandbox.

Known issues and solutions

RangeError: Maximum call stack size exceeded

In some cases, you may see this error when trying to process a transaction. This is a known issue when any of the options passed to the daimyo.Transaction constructor is a Mongoose document key (or similar complex type). Mongoose document keys are not simple types (String, Number, etc) and they have to be converted first. Simple way to do it is to call valueOf() or toString() on the key first:

var transaction == new daimyo.Transaction({
  type: 'purchase',
  billingReference: myMongooseDocument.someKey.valueOf(),
  customerReference: myMongooseDocument.id.toString()
});

This also applies to situations where you are passing values that are not simple types (String, Number), Object, or Array instances.

Reporting bugs

You may use the issue tracker to report Daimyo bugs you find. Alternatively, you may contact the author directly at [email protected]. Of course, feature requests are also welcome, but currently, the basic functionality is top priority.