paymill-wrapper

2.2.0 • Public • Published

PAYMILL icon

PAYMILL-JS

NPM version Build Status Code Climate Test Coverage
Dependency Status devDependency Status

An universal JavaScript API wrapper. Works with Node, Parse, apiOmat and potentially any other javascript-based backend.

Please open an issue and let us know if you find any bugs, have a feature request or have successfully integrated it into your project.

Getting started

  • If you are not familiar with PAYMILL, start with the documentation.
  • Install the latest release.
  • Check the API reference. For code snippets select "JS".
  • Check the full JSdoc documentation.
  • Check the tests / samples.

Installation

Node

Install the package using npm: npm install paymill-wrapper or npm install -g paymill-wrapper to install globaly. You can also add paymill-wrapper to your package.json dependecies.

Use the module with var paymill = require("paymill-wrapper");.

Parse

Copy paymill.parse.js to your your cloud code folder.

Use the module with var paymill = require("cloud/paymill.parse.js");.

apiOmat

In your apiOmat dashboard add the Modules 'Paymill' and 'Server Code' to use paymill function in 'Server Code' module. See documentation of the module for further informations.

Usage

Initialization

Before using the wrapper you have to create a PaymillContext using your private PAYMILL key: paymill.getContext(yourApiKey);.

Services

Each endpoint of the PAYMILL API has a corrseponding service in a PaymillContext . For example, to access transaction functions you can use paymill.transactions.

Available methods are (depending on the service):

  • create ( or createXXX ) A service may include multiple create methods, depending on the parameters. You cannot create an object locally and call create with it, you have to supply the input parameters.
  • ** fromXXX(mandatory).withXXX(optional)...withXXX(optional).create()** Some services have a lot of optional parameters. For those services you can call one of the fromXXX() methods (with the mandatory parameters). These methods return a "creator". You can add optional parameters by chain calling withXXX() on the creator. Don't forget to call create() at the end.
  • update Accepts an object. The same object will be updated and returned.
  • remove Accepts an object or an objects id and returns an object. If the parameter is an object, the same object will be updated and returned.
  • detail Accepts an object or an objects id. If the parameter is an object, acts like a "refresh" and updates it.
  • list Accepts count and offset parameters for pagination, as well as order and filter. Returns a List object, which holds the global count in count and an array of the objects in items

Removing, updating and retrieving

When you use methods like remove, update or detail with an object as argument, the wrapper will use the response from the API to update the same object and will return the same object. If you use the id of an object as a string, the wrapper will create a new object and return it.

Example:

var transaction; // some transaction you created
paymill.transactions.detail(transaction).then(function(detail){
    if (detail===transaction) {
        console.log("Wrapper works!");
    }
});

Listing entities

All list interfaces return a PaymillList. The total count is contained in the count variable, the actual array is in the items variable. You can always (optionally) define count, offset, filter or order to a list request. For example, if you like to show all transactions from a praticular client, paginated and order by the creation date, you would use following code:

pmc.transactions.list(pageSize,pageNumber*pageSize,
(newpmc.Transaction.Filter()).client("client1234"),
pmc.Transaction.Order().created_at().desc())

Callbacks and promises

All service methods are asynchronous. To receive the result you either have to specify a callback function or you use the returned Promise.

Callbacks

The last parameter of every service method is a callback. The callback will be executed after the request. The format of the callbacks is platform specific.

  • Node In Node, the wrapper expects the callback to be a function in the form function(error,result) .
  • Parse In Parse, the wrapper expects the callback to be an object in the form
var callback= {
    success: function(result) {…},
    error: function(error) {..}
}

Promises

All service methods return an A+ compliant Promise. The promise is resolved with the result or rejected with an error. You can chain promises like this:

paymill.clients.create().then(function(client) {
    //client created, lets create a payment
    return paymill.payments.create(atoken,client);
}).then(function(payment){
    //payment created, do something with it
},function(error) {
    // an error occured
});

Deserialization

The Wrapper deserializes all responses from the API. If you need to access the original json, all PAYMILL objects include the originalJson member, which holds the json used for deserialization.

Contributors

Getting started:

  • Install node.js
  • Run npm install to install dependencies or sudo npm install -g to install dependecies globally.
  • run npm test to run jshint and mocha tests. Note: you have to have a valid private key in a PMAPIKEY environment variable.
  • run npm run-script docs to generate documentation

(if Error: Cannot find module X, check if $NODE_PATH is correct)

Adding a new platform

To add a new platform (XXX), you have to:

  • Create a folder libXXX.
  • Implement an ExternalHandler.
  • Make sure underscore.js is available for your platform.
  • In Gruntfile.js add
XXX : {
    src : ['paymill.js', 'lib/*.js','lib/models/*.js','lib/services/*.js','libXXX/*.js'],
    dest : 'paymill.XXX.js',
},

Changelog

2.2.0

  • Upgraded objects to latest version
  • Added checksum service for PayPal integration
  • Updated project dependencies

2.1.0

  • Upgraded objects to latest version
  • TransactionService now supports a Creator.
  • Updated project dependencies

2.0.0

  • Upgraded to PAYMILL API v2.1
  • Changed library interface to support multiple instances (e.g. for marketplaces)
  • Added Travis and Codeclimate
  • Updated project dependencies

1.1.0

  • Added support for preauthorization description #8
  • updated project dependencies

1.0.1

  • Added support for source identifier

1.0.0

  • Stable release

License

Copyright 2015 PAYMILL GmbH.

MIT License (enclosed)

Dependencies (2)

Dev Dependencies (9)

Package Sidebar

Install

npm i paymill-wrapper

Weekly Downloads

0

Version

2.2.0

License

MIT

Last publish

Collaborators

  • paymill