This module is a thin client for interacting with Button's API.
Please see the full API Docs for more information. For help, check out our Support page or get in touch.
- Node
6,8,10
- None
npm install @button/button-client-nodeTo create a client capable of making network requests, invoke button-client-node with your API key.
const client = require('@button/button-client-node')('sk-XXX');You can optionally supply a config argument with your API key:
const client = require('@button/button-client-node')('sk-XXX', {
timeout: 3000, // network requests will time out at 3 seconds
hostname: 'api.usebutton.com' // default hostname for api requests
});timeout: The time in ms for network requests to abort. Defaults to false.hostname: Defaults toapi.usebutton.comport: Defaults to443ifconfig.secure, else defaults to80.secure: Whether or not to use HTTPS. Defaults to true. N.B: Button's API is only exposed through HTTPS. This option is provided purely as a convenience for testing and development.
button-client-node uses native Promises for all requests:
const client = require('@button/button-client-node')('sk-XXX', {
timeout: 3000
});
client.orders.get('btnorder-XXX')
.then(handleResult)
.catch(handleError);The returned promise will either reject with an Error or resolve with the API response object.
All responses will assume the following shape:
{
data,
meta: {
next,
previous
}
}The data key will contain any resource data received from the API and the meta key will contain high-order information pertaining to the request.
next: For any paged resource,nextwill be a cursor to supply for the next page of results.previous: For any paged resource,previouswill be a cursor to supply for the previous page of results.
We currently expose the following resources to manage:
const client = require('@button/button-client-node')('sk-XXX');
client.accounts.all()
.then(handleResult)
.catch(handleError);Transactions are a paged resource. The response object will contain properties meta.next and meta.previous which can be supplied to subsequent invocations of #transactions to fetch additional results.
#transactions accepts an optional second parameter, options which may define the follow keys to narrow results:
cursor: An API cursor to fetch a specific set of resultsstart: An ISO-8601 datetime string to filter only transactions afterstartend: An ISO-8601 datetime string to filter only transactions beforeendtime_field: Which time field start and end filter on.
const client = require('@button/button-client-node')('sk-XXX');
// without options argument
//
client.accounts.transactions('acc-1')
.then(handleSuccess)
.catch(handleError);
// with options argument
//
client.accounts.transactions('acc-1', {
cursor: 'cXw',
start: '2015-01-01T00:00:00Z',
end: '2016-01-01T00:00:00Z',
time_field: 'modified_date'
}).then(handleResult)
.catch(handleError);status: Partnership status to filter by. One of ('approved', 'pending', or 'available')currency: ISO-4217 currency code to filter returned rates by
const client = require('@button/button-client-node')('sk-XXX');
// without options argument
//
client.merchants.all()
.then()
.catch();
// with options argument
//
client.merchants.all({
status: 'pending',
currency: 'USD'
}).then(handleResult)
.catch(handleError);const crypto = require('crypto');
const client = require('@button/button-client-node')('sk-XXX');
const hashedEmail = crypto.createHash('sha256')
.update('user@example.com'.toLowerCase().trim())
.digest('hex');
client.orders.create({
total: 50,
currency: 'USD',
order_id: '1989',
purchase_date: '2017-07-25T08:23:52Z',
finalization_date: '2017-08-02T19:26:08Z',
btn_ref: 'srctok-XXX',
customer: {
id: 'mycustomer-1234',
email_sha256: hashedEmail
}
}).then(handleResult)
.catch(handleError);const client = require('@button/button-client-node')('sk-XXX');
client.orders.get('btnorder-XXX')
.then(handleResult)
.catch(handleError);const client = require('@button/button-client-node')('sk-XXX');
client.orders.getByBtnRef('srctok-XXX')
.then(handleResult)
.catch(handleError);const client = require('@button/button-client-node')('sk-XXX');
client.orders.update('btnorder-XXX', { total: 60 })
.then(handleResult)
.catch(handleError);const client = require('@button/button-client-node')('sk-XXX');
client.orders.del('btnorder-XXX')
.then(handleResult)
.catch(handleError);const crypto = require('crypto');
const client = require('@button/button-client-node')('sk-XXX');
const hashedEmail = crypto.createHash('sha256')
.update('user@example.com'.toLowerCase().trim())
.digest('hex');
client.customers.create({
id: 'customer-1234',
email_sha256: hashedEmail
}).then(handleResult)
.catch(handleError);const client = require('@button/button-client-node')('sk-XXX');
client.customers.get('customer-1234')
.then(handleResult)
.catch(handleError);client.links.create({
url: "https://www.jet.com",
experience: {
btn_pub_ref: "my-pub-ref",
btn_pub_user: "user-id"
}
}).then(handleResult)
.catch(handleError);client.links.getInfo({ url: "https://www.jet.com" })
.then(handleSuccess)
.catch(handleError);Transactions are a paged resource. The response object will contain properties meta.next and meta.previous which can be supplied to subsequent invocations of #all to fetch additional results.
Unlike the accounts.transaction resource, which only queries a single account's transactions, the transactions.all resource queries all of an organizations transactions.
#all accepts an optional second parameter, options which may define the follow keys to narrow results:
cursor: An API cursor to fetch a specific set of resultsstart: An ISO-8601 datetime string to filter only transactions afterstartend: An ISO-8601 datetime string to filter only transactions beforeendtime_field: Which time field start and end filter on.
const client = require('@button/button-client-node')('sk-XXX');
// without options argument
//
client.transactions.all()
.then(handleSuccess)
.catch(handleError);
// with options argument
//
client.transactions.all({
cursor: 'cXw',
start: '2015-01-01T00:00:00Z',
end: '2016-01-01T00:00:00Z',
time_field: 'modified_date'
}).then(handleResult)
.catch(handleError);Utils houses generic helpers useful in a Button Integration.
Used to verify that requests sent to a webhook endpoint are from Button and that their payload can be trusted. Returns true if a webhook request body matches the sent signature and false otherwise. See Webhook Security for more details.
Example usage with body-parser
const express = require('express');
const bodyParser = require('body-parser');
const utils = require('@button/button-client-node').utils
const app = express();
function verify(req, res, buf, encoding) {
const isAuthentic = utils.isWebhookAuthentic(
process.env['WEBHOOK_SECRET'],
buf,
req.headers['X-Button-Signature']
);
if (!isAuthentic) {
throw new Error('Invalid Webhook Signature');
}
}
app.use(bodyParser.json({ verify: verify, type: 'application/json' }));- Installing development dependencies:
npm install - Running tests:
npm test - Running lint:
npm run lint