Paylike client (Node.js)

With browserify you can use this library in the browser as well. Be aware that you should not bundle your private API keys for public websites though.

Writing your own client? Checkout the raw HTTP service.

Make sure to subscribe to our mailling list for deprecation notices, API changes and new features, or you can watch this repository for changes.

Getting an API key

An API key can be obtained by creating a merchant and adding an app through our dashboard. If your app's target audience is third parties, please reach out and we will make your app's API key hidden.

Install

npm install paylike --save

varpaylike=require('paylike')(appKey);

Methods

// change key for authentication.setKey(key)// create an app (requires no authentication)apps.create(opts)->Promise(app)// fetch current app (based on key)apps.findOne()->Promise(app)// list app's merchantsapps.merchants.find(appId)->Cursor(merchants)merchants.create(opts)->Promise(merchantId)merchants.update(merchantId,opts)->Promisemerchants.findOne(merchantId)->Promise(merchant)merchants.users.add(merchantId,opts)->Promisemerchants.users.revoke(merchantId,userId)->Promisemerchants.users.find(merchantId)->Cursor(users)merchants.apps.add(merchantId,opts)->Promisemerchants.apps.revoke(merchantId,appId)->Promisemerchants.apps.find(merchantId)->Cursor(apps)merchants.lines.find(merchantId)->Cursor(lines)merchants.transactions.create(merchantId,opts)->Promise(transactionId)merchants.transactions.find(merchantId)->Cursor(transactions)transactions.capture(transactionId,opts)->Promisetransactions.refund(transactionId,opts)->Promisetransactions.void(transactionId,opts)->Promisetransactions.findOne(transactionId)->Promise(transaction)cards.create(merchantId,opts)->Promise(cardId)cards.findOne(cardId)->Promise(card)

A webshop would typically need only capture, refund and void. Some might as well use transactions.findOne and for recurring subscriptions transactions.create.

Promises or callbacks (we support both)

All asynchronous methods will return promises or accept a callback as the last argument (node style).

The Promise implementation is Bluebird and you can utilize all of their API.

// Promise stylepaylike.transactions.capture(transactionIdA,{amount: 100,}).then(function(){// capture is successfully done},function(){// capture failed});// Callback stylepaylike.transactions.refund(transactionIdB,{amount: 100,},function(err){if(err)returnconsole.error(err);// refund failed// refund was successful});

Cursors (pagination)

after(id)->cursorsince(Date)->cursorbefore(id)->cursoruntil(Date)->cursorlimit(limit)->cursor// keep the stream open and poll each `delay` mskeepAlive([delay])->pullstreamtoArray->Promise(Array)// convenience for pull(cursor, ...)pull(streamA,streamB...)->pullstream

All find methods return cursors.

A cursor is a pull-stream wrapping the requested data. It polls the server in batches as needed.

If you do not already know about pull streams, I would like to encourage you to read Dominic Tarr's introduction.

If you specify a starting point using before() you will get the newest objects first (which is also the default), but using after you will receive them in reverse order. This fits nicely into the stream pattern and infinite lists that expand in both directions.

The rationale for using after/before as opposed to skip is to achieve stable lists and reliable data synchronization.

varcursor=paylike.transactions.find(merchantId);// get a promise for an array of the last 5 transactionscursor.limit(5).toArray();varpull=require('pull-stream');// print all transactionspull(paylike.transactions.find(merchantId),pull.log())// live stream transaction amounts as they occurpull(paylike.transactions.find(merchantId).since(newDate()).keepAlive(),pull.map(t=>t.currency+' '+t.amount),pull.log())// stream all transactions to a HTTP response (interop with a classic Node.js// stream)vartoStream=require('pull-stream-to-stream');toStream(paylike.transactions.find(merchantId)).pipe(JSONStream.stringify()).pipe(response);

Error handling

The API will throw errors when things do not fly. All errors inherit from PaylikeError. A very verbose example of catching all types of errors:

paylike.transactions.capture(transactionId,{amount: 100,currency: 'EUR',}).catch(paylike.NotFoundError,function(){console.error('The transaction was not found');}).catch(paylike.AuthorizationError,paylike.PermissionsError,function(){console.error('The API key does not have access to the transaction');}).catch(paylike.ValidationError,function(e){console.error('The capture failed:',e.data);}).catch(paylike.PaylikeError,function(e){console.error('Something went wrong',e);});

In most cases catching NotFoundError and ValidationError as client errors and logging PaylikeError would suffice.

Example (capturing a transaction)

paylike.transactions.capture(transactionId,{amount: 1200,currency: 'USD',descriptor: 'Awesome #5011',}).then(function(){console.log('Captured USD 12.00 appearing as "Awesome #5011" on customers bank statement');});