SlidePay Node.js SDK

Helper package for working with the SlidePay REST API.

Installation

npm install slidepay

Design Principles

This library uses promises to handle asynchronous behavior (Bluebird). Promises are a powerful asynchronous control flow pattern and make it easy to pass around and manipulate asynchronous operations. However, if you'd prefer to use callbacks, the library uses Bluebird's nodeify to call node-style callbacks for API operations.

Most of the inner workings of the SlidePay API are obfuscated—objects are properly typed and HTTP errors are transformed into Node errors, for example. You should rarely need to think know the right API endpoint or worry about implementation details.

Getting Started

Create a new instance:

var SlidePay = require('slidepay');
var slidepay = new SlidePay();

Authentication

If you have an existing API key or token, you can supply it when creating your instance:

new SlidePay({token: 'token'});
// OR
new SlidePay({apiKey: 'apiKey'});

If you don't have a token or API key, you can call login, which returns a promise:

var slidepay = new SlidePay();
slidepay.login({email: 'email', password: 'password'}).then(function(token) {
    // token is now stored on slidepay, but you could save it to a database
});

Or using a callback:

slidepay.login(credentials, function(err, token) {
    if (err) {
        // handle login error
    } else {
        // login succeeded and token is defined
    }
});

A separate client instance should be used for each user/session (token or API key). The library will always attempt to use the apiKey if defined, falling back to the token.

Models

Common Properties

The library maps SlidePay resources to objects that can be more easily manipulated. All models share a few common attributes. You won't need to modify these attributes (except id) unless you're creating new models that aren't included here.

name

The name of the resource. By default, the model will resolve its endpoint using its name unless overriden.

idAttribute

By default, the idAttribute is *name*_id. In certain cases, such as authorization, the main object ID is different than the name(payment_id).

id

id is a useful getter/setter property that reads and writes from the idAttribute. For example:

new slidepay.Payment({payment_id: 1}).id // => 1

The library knows that the idAttribute for Payment is payment_id and provides a shortcut for accessing the payment_id.

Using Models

A model represents one or more SlidePay objects and provides access to associated data and methods. All models are created with the new operator and can accept a set of attributes on creation. For example:

var simplePayment = new slidepay.Payment(simplePaymentObj)
simplePayment.create().then(function(payment) {
    // payment was created successfully
});

Keep in mind that models will not mutate the original object created with new. In the above example, payment in the promise handler will not equal simplePayment. simplePayment will never change unless you manually update its properties. Models have static and instance methods—static methods are called without new (e.g. slidepay.Payment.search) and instance methods can only be called on objects created with new.

APIKey

• Instance
  • create
  • fetch
  • destroy
• Static
  • fetch

Authorization

• Instance
  • create
  • fetch
  • void
  • capture — type (auto|manual)
• Static
  • fetch
  • capture — type ({auto|manual}), ids (Array)

Bank Account

• Instance
  • create
  • fetch
  • destroy
• Static
  • fetch

Payment

• Instance
  • create
  • refund
  • fetch
• Static
  • fetch
  • search — fields (Array)

Settlement

• Instance
  • fetch
• Static
  • search — fields (Array)
  • balance — location_id (Integer)
  • create — settlement_object (Object)

StoredPayment

• Instance
  • create
  • fetch
• Static
  • fetch

Retrieval

• Instance
  • fetch
• Static
  • create

AccountReport

The single static method will run a real time report on a merchant's settlement account.

• Static
  • fetch - location_id (Integer)

PaymentReport

The single static method will run a real time report on a merchant's payments performed within the constraints supplied by a search filter array passed in.

• Static
  • fetch - search filter array (Array)

Merchant

Merchant models do not follow the REST conventions found in the other models. When creating a merchant, pass in the boarding application (new slidepay.Merchant(boarding). Then call create to submit it. That will populate a questions property on the original object with the boarding questions. Set the correct answers there, then call submitAnswers to submit the application.

• Instance
  • create
  • submitAnswers

Custom Requests

The library exposes the REST client on your SlidePay instance as slidepay.RestClient. You can make requests using RestClient.request to any endpoint with any request body and still take advantage of the library's stored credentials.

This package manages most of SlidePay's resources and methods. You don't need to use the actual HTTP endpoints. Resourced are properties of the RestClient.

Tests

Tests expect a credentials.json file in the project's test directory with a valid email and password.

That file should be provided in a format similar to the following:

{
    "credentials": {
        "email": "slidepay_account@example.com",
        "password": "SECRET_SLIDEPAY_PASSWORD",
    }
}

Run the mocha tests from the command line with:

$ npm test

Contributing

Please file an issue for any feature requests, questions, or bugs. If you'd like to contribute a new feature or fill gaps in the resources, fork the repository and issue a pull request. If you're adding new functionality, make sure to write appropriate tests.

License

The MIT License

© 2014 Ben Drucker and SlidePay