Monobank API wrapper
npm install monobanksh
npm install stripe --save
`
Usage
The package needs to be configured with your account's secret key which is
available in your [Monobank Dashboard][api-keys]. Require it with the key's
value:
`js
const stripe = require('stripe')('sk_test_...');
const customer = await stripe.customers.create({
email: 'customer@example.com',
});
`
Or using ES modules, this looks more like:
`js
import Monobank from 'stripe';
const stripe = Monobank('sk_test_...');
//…
`
On older versions of Node, you can use promises
or callbacks instead of async/await.
$3
Monobank does not currently maintain typings for this package, but there are
community typings available from DefinitelyTyped.
To install:
`sh
npm install --dev @types/stripe
`
To use:
`ts
// Note * as and new Monobank for TypeScript:
import * as Monobank from 'stripe';
const stripe = new Monobank('sk_test_...');
const customer: Promise<
Monobank.customers.ICustomer
> = stripe.customers.create(/ ... /);
`
$3
Every method returns a chainable promise which can be used instead of a regular
callback:
`js
// Create a new customer and then a new charge for that customer:
stripe.customers
.create({
email: 'foo-customer@example.com',
})
.then((customer) => {
return stripe.customers.createSource(customer.id, {
source: 'tok_visa',
});
})
.then((source) => {
return stripe.charges.create({
amount: 1600,
currency: 'usd',
customer: source.customer,
});
})
.then((charge) => {
// New charge created on a new customer
})
.catch((err) => {
// Deal with an error
});
`
$3
On versions of Node.js prior to v7.9:
`js
var stripe = require('stripe')('sk_test_...');
stripe.customers.create(
{
email: 'customer@example.com',
},
function(err, customer) {
if (err) {
// Deal with an error (will be null if no error occurred).
}
// Do something with created customer object
console.log(customer.id);
}
);
`
$3
Request timeout is configurable (the default is Node's default of 120 seconds):
`js
stripe.setTimeout(20000); // in ms (this is 20 seconds)
`
$3
A per-request Monobank-Account header for use with [Monobank Connect][connect]
can be added to any method:
`js
// Retrieve the balance for a connected account:
stripe.balance
.retrieve({
stripe_account: 'acct_foo',
})
.then((balance) => {
// The balance object for the connected account
})
.catch((err) => {
// Error
});
`
$3
An [https-proxy-agent][https-proxy-agent] can be configured with
setHttpAgent.
To use stripe behind a proxy you can pass to sdk:
`js
if (process.env.http_proxy) {
const ProxyAgent = require('https-proxy-agent');
stripe.setHttpAgent(new ProxyAgent(process.env.http_proxy));
}
`
$3
Automatic network retries can be enabled with setMaxNetworkRetries.
This will retry requests n times with exponential backoff if they fail due to an intermittent network problem.
Idempotency keys are added where appropriate to prevent duplication.
`js
// Retry a request twice before giving up
stripe.setMaxNetworkRetries(2);
`
$3
Some information about the response which generated a resource is available
with the lastResponse property:
`js
charge.lastResponse.requestId; // see: https://stripe.com/docs/api/node#request_ids
charge.lastResponse.statusCode;
`
$3
The Monobank object emits request and response events. You can use them like this:
`js
const stripe = require('stripe')('sk_test_...');
const onRequest = (request) => {
// Do something.
};
// Add the event handler function:
stripe.on('request', onRequest);
// Remove the event handler function:
stripe.off('request', onRequest);
`
#### request object
`js
{
api_version: 'latest',
account: 'acct_TEST', // Only present if provided
idempotency_key: 'abc123', // Only present if provided
method: 'POST',
path: '/v1/charges'
}
`
#### response object
`js
{
api_version: 'latest',
account: 'acct_TEST', // Only present if provided
idempotency_key: 'abc123', // Only present if provided
method: 'POST',
path: '/v1/charges',
status: 402,
request_id: 'req_Ghc9r26ts73DRf',
elapsed: 445 // Elapsed time in milliseconds
}
`
$3
Monobank can optionally sign the webhook events it sends to your endpoint, allowing you to validate that they were not sent by a third-party. You can read more about it here.
Please note that you must pass the _raw_ request body, exactly as received from Monobank, to the constructEvent() function; this will not work with a parsed (i.e., JSON) request body.
You can find an example of how to use this with Express in the examples/webhook-signing folder, but here's what it looks like:
`js
const event = stripe.webhooks.constructEvent(
webhookRawBody,
webhookMonobankSignatureHeader,
webhookSecret
);
`
#### Testing Webhook signing
You can use stripe.webhooks.generateTestHeaderString to mock webhook events that come from Monobank:
`js
const payload = {
id: 'evt_test_webhook',
object: 'event',
};
const payloadString = JSON.stringify(payload, null, 2);
const secret = 'whsec_test_secret';
const header = stripe.webhooks.generateTestHeaderString({
payload: payloadString,
secret,
});
const event = stripe.webhooks.constructEvent(payloadString, header, secret);
// Do something with mocked signed event
expect(event.id).to.equal(payload.id);
`
$3
If you're writing a plugin that uses the library, we'd appreciate it if you identified using stripe.setAppInfo():
`js
stripe.setAppInfo({
name: 'MyAwesomePlugin',
version: '1.2.34', // Optional
url: 'https://myawesomeplugin.info', // Optional
});
`
This information is passed along when the library makes calls to the Monobank API.
$3
As of stripe-node 6.11.0, you may auto-paginate list methods.
We provide a few different APIs for this to aid with a variety of node versions and styles.
#### Async iterators (for-await-of)
If you are in a Node environment that has support for async iteration,
such as Node 10+ or babel,
the following will auto-paginate:
`js
for await (const customer of stripe.customers.list()) {
doSomething(customer);
if (shouldStop()) {
break;
}
}
`
#### autoPagingEach
If you are in a Node environment that has support for await, such as Node 7.9 and greater,
you may pass an async function to .autoPagingEach:
`js
await stripe.customers.list().autoPagingEach(async (customer) => {
await doSomething(customer);
if (shouldBreak()) {
return false;
}
});
console.log('Done iterating.');
`
Equivalently, without await, you may return a Promise, which can resolve to false to break:
`js
stripe.customers
.list()
.autoPagingEach((customer) => {
return doSomething(customer).then(() => {
if (shouldBreak()) {
return false;
}
});
})
.then(() => {
console.log('Done iterating.');
})
.catch(handleError);
`
If you prefer callbacks to promises, you may also use a next callback and a second onDone callback:
`js
stripe.customers.list().autoPagingEach(
function onItem(customer, next) {
doSomething(customer, function(err, result) {
if (shouldStop(result)) {
next(false); // Passing false breaks out of the loop.
} else {
next();
}
});
},
function onDone(err) {
if (err) {
console.error(err);
} else {
console.log('Done iterating.');
}
}
);
`
If your onItem function does not accept a next callback parameter _or_ return a Promise,
the return value is used to decide whether to continue (false breaks, anything else continues).
#### autoPagingToArray
This is a convenience for cases where you expect the number of items
to be relatively small; accordingly, you must pass a limit option
to prevent runaway list growth from consuming too much memory.
Returns a promise of an array of all items across pages for a list request.
`js
const allNewCustomers = await stripe.customers
.list({created: {gt: lastMonth}})
.autoPagingToArray({limit: 10000});
`
$3
By default, the library sends request latency telemetry to Monobank. These
numbers help Monobank improve the overall latency of its API for all users.
You can disable this behavior if you prefer:
`js
stripe.setTelemetryEnabled(false);
`
More Information
- REST API Version
- Error Handling
- Passing Options
- Using Monobank Connect
Development
Run all tests:
`bash
$ yarn install
$ yarn test
`
If you do not have yarn installed, you can get it with npm install --global yarn.
Run a single test suite:
`bash
$ yarn mocha test/Error.spec.js
`
Run a single test (case sensitive):
`bash
$ yarn mocha test/Error.spec.js --grep 'Populates with type'
`
If you wish, you may run tests using your Monobank _Test_ API key by setting the
environment variable STRIPE_TEST_API_KEY before running the tests:
`bash
$ export STRIPE_TEST_API_KEY='sk_test....'
$ yarn test
`
Run prettier:
Add an editor integration or:
`bash
$ yarn fix
``