Coinbase Commerce

The official Node.js library for the Coinbase Commerce API.

Table of contents

• Node.js Versions
• Documentation
• Installation
• Usage
  • Checkouts
  • Charges
  • Events
  • Webhooks
• Testing and Contributing

Node.js versions

Node.js v0.10.48 and above are supported.

Documentation

For more details visit Coinbase API docs.

To start using this library register an account on Coinbase Commerce. You will find your API_KEY from User Settings.

Next initialize a Client for interacting with the API. The only required parameter to initialize a client is apiKey, however, you can also pass in baseUrl, apiVersion and timeout. Parameters can be also be set post-initialization:

1var coinbase = require('coinbase-commerce-node');
2var Client = coinbase.Client;
3
4var clientObj = Client.init('API_KEY');
5clientObj.setRequestTimeout(3000);

The API resource class provides the following static methods: list, all, create, retrieve, updateById, deleteById. Additionally, the API resource class also provides the following instance methods: save, delete, insert, update.

Each API method returns an ApiResource which represents the JSON response from the API. When the response data is parsed into objects, the appropriate ApiResource subclass will automatically be used.

Client supports the handling of common API errors and warnings. All errors that occur during any interaction with the API will be raised as exceptions.

Error	Status Code
APIError	*
InvalidRequestError	400
ParamRequiredError	400
ValidationError	400
AuthenticationError	401
ResourceNotFoundError	404
RateLimitExceededError	429
InternalServerError	500
ServiceUnavailableError	503

Installation

Install with npm:

1npm install coinbase-commerce-node --save

Type definitions are available for TypeScript users:

1npm install @types/coinbase-commerce-node --save-dev

Usage

1var coinbase = require('coinbase-commerce-node');
2var Client = coinbase.Client;
3
4Client.init('API_KEY');

Checkouts

Checkouts API docs More examples on how to use checkouts can be found in the examples/resources/checkout.js file

Load checkout resource class

1var coinbase = require('coinbase-commerce-node');
2var Checkout = coinbase.resources.Checkout;

Retrieve

1Checkout.retrieve(<checkout_id>, function (error, response) {
2  console.log(error);
3  console.log(response);
4});

Create

1var checkoutData = {
2    'name': 'The Sovereign Individual',
3    'description': 'Mastering the Transition to the Information Age',
4    'pricing_type': 'fixed_price',
5    'local_price': {
6        'amount': '100.00',
7        'currency': 'USD'
8    },
9    'requested_info': ['name', 'email']
10};
11Checkout.create(checkoutData, function (error, response) {
12  console.log(error);
13  console.log(response);
14});
15
16// or
17
18var checkoutObj = new Checkout();
19
20checkoutObj.name = 'The Sovereign Individual';
21checkoutObj.description = 'Mastering the Transition to the Information Age';
22checkoutObj.pricing_type = 'fixed_price';
23checkoutObj.local_price = {
24    'amount': '100.00',
25    'currency': 'USD'
26};
27checkoutObj.requested_info = ['name', 'email'];
28
29checkoutObj.save(function (error, response) {
30  console.log(error);
31  console.log(response);
32});

Update

1var checkoutObj = new Checkout();
2
3checkoutObj.id = <checkout_id>;
4checkoutObj.name = 'new name';
5
6checkoutObj.save(function (error, response) {
7  console.log(error);
8  console.log(response);
9});
10// or
11var newParams = {
12    'name': 'New name'
13};
14
15Checkout.updateById(<checkout_id>, newParams, function (error, response) {
16  console.log(error);
17  console.log(response);
18});

Delete

1var checkoutObj = new Checkout();
2
3checkoutObj.id = <checkout_id>;
4checkoutObj.delete(function (error, response) {
5 console.log(error);
6 console.log(response);
7});
8
9// or
10
11Checkout.deleteById(<checkout_id>, function (error, response) {
12 console.log(error);
13 console.log(response);  
14});

List

1var params = {
2    'limit': 2,
3    'order': 'desc'
4};
5
6Checkout.list(params, function (error, list, pagination) {
7  console.log(error);
8  console.log(list);
9  console.log(pagination);
10});

Get all checkouts

1var params = {
2    'order': 'desc'  
3};
4
5Checkout.all(params, function (error, list) {
6  console.log(error);
7  console.log(list);
8});
9

Charges

Charges API docs More examples on how to use charges can be found in the examples/resources/charge.js file

Load charge resource class

1var coinbase = require('coinbase-commerce-node');
2var Charge = coinbase.resources.Charge;

Retrieve

1Charge.retrieve(<charge_id>, function (error, response) {
2  console.log(error);
3  console.log(response);
4});

Create

1var chargeData = {
2    'name': 'The Sovereign Individual',
3    'description': 'Mastering the Transition to the Information Age',
4    'local_price': {
5        'amount': '100.00',
6        'currency': 'USD'
7    },
8    'pricing_type': 'fixed_price'
9
10}
11Charge.create(chargeData, function (error, response) {
12  console.log(error);
13  console.log(response);
14});
15
16// or
17var chargeObj = new Charge();
18
19chargeObj.name = 'The Sovereign Individual';
20chargeObj.description = 'Mastering the Transition to the Information Age';
21chargeObj.local_price = {
22    'amount': '100.00',
23    'currency': 'USD'
24};
25chargeObj.pricing_type = 'fixed_price';
26chargeObj.save(function (error, response) {
27  console.log(error);
28  console.log(response);
29});

List

1Charge.list({}, function (error, list, pagination) {
2  console.log(error);
3  console.log(list);
4  console.log(pagination);
5});

Get all changes

1Charge.all({}, function (error, list) {
2  console.log(error);
3  console.log(list);
4});

Events

Events API Docs More examples on how to use events can be found in the examples/resources/event.js file

Load event resource class

1var coinbase = require('coinbase-commerce-node');
2var Event = coinbase.resources.Event;

Retrieve

1Event.retrieve(<event_id>, function (error, response) {
2    console.log(error);
3    console.log(response);
4});

List

1Event.list({}, function (error, list, pagination) {
2  console.log(error);
3  console.log(list);
4  console.log(pagination);
5});

Get all events

1Event.all({}, function (error, list) {
2  console.log(error);
3  console.log(list);
4});

Using Promises

In addition to using callbacks, every method also return a promise.

1// Try create and retrieve created charge
2var chargeObj = new Charge({
3    'description': 'Mastering the Transition to the Information Age',
4    'metadata': {
5        'customer_id': 'id_1005',
6        'customer_name': 'Satoshi Nakamoto'
7    },
8    'name': 'Test Name',
9    'payments': [],
10    'pricing_type': 'no_price'
11});
12
13chargeObj.save().then(function (response) {
14    console.log('Created charge(promise)');
15    console.log(response);
16
17    if (response && response.id) {
18        return Charge.retrieve(response.id);
19    }
20}).then(function (response) {
21    console.log('Retrieved charge(promise)');
22    console.log(response);
23}).catch(function (error) {
24    console.log('Unable to retrieve charge(promise)');
25    console.log(error);
26});

Webhooks

Coinbase Commerce signs the webhook events it sends to your endpoint, allowing you to validate and verify that they weren't sent by someone else. You can find a simple example of how to use this with Express in the examples/webhook folder

Verify Signature header

1var Webhook = require('coinbase-commerce-node').Webhook;
2
3try {
4    Webhook.verifySigHeader(rawBody, signature, sharedSecret);
5    console.log('Successfully verified');
6} catch(error) {
7    console.log('Failed');
8    console.log(error);
9}

Testing and Contributing

Any and all contributions are welcome! The process is simple: fork this repo, make your changes, run the test suite, and submit a pull request. To run the tests, clone the repository and run the following commands:

1npm install
2npm run test

License

MIT