how to get this module to work

[timbowhite]

After an afternoon of struggling with this thing and its documentation, I'm going to share how I was able to create a basic invoice. Bitpay: please update and improve the docs, feel free to use any of this.

Install and Setup Bitpay Module (*nix platform)

NOTE: the bitpay module automatically creates a .bitpay directory in your home directory that contains your public & private key, and config file. If you want that stuff stored elsewhere (and you probably do, especially if your app runs as a different user), do this first:

export HOME=/path/where/you/want/the/.bitpay/directory

Then install the bitpay module. Note that we're also installing the bitauth module (it's required later on for decrypting your private key when making requests).

npm install bitpay bitauth

Set up your client's private key:

./node_modules/bitpay/bin/bitpay.js keygen
< enter a password, or hit enter for no password >

Next set the environment. Bitpay's test platform is used by default, so if you want to use the regular production platform (ie. bitpay.com and not test.bitpay.com), do this:

./node_modules/bitpay/bin/bitpay.js config --use prod

Next you have to pair up your client's private key with your bitpay account. This is done by requesting a pairing code:

./node_modules/bitpay/bin/bitpay.js pair
Do you have a pairing code?
no < hit enter twice >
Okay, we can get a pairing code, please choose a facade:
  1) Point of Sale
  2) Merchant
  : 
1

This will spit out a bunch of output. At the end of it will be a URL:

 Pair this client with your organization: 
 https://bitpay.com/api-access-request?pairingCode=XXX

Visit this URL in your browser and hit the approve button. Afterwards, you can test creating a basic invoice from the command line like this:

./node_modules/bitpay/bin/bitpay.js request -T pos -X post -R invoices -P '{"price": 1, "currency": "USD"}'

If it worked, you'll see some JSON outputted regarding the newly created invoice. If you get an error like this:

Error: { error: 'Invalid token' }

It's probably because you specified the "Merchant" facade (option 2) when generating your pairing code. For invoices, you want the "Point of Sale" facade (option 1).

Usage in Node.js

Here's how you can create a basic invoice:

// NOTE: if you changed your home environment variable
// when installing bitpay, you'll need to change it again in your code
// before requiring the bitpay module.  If not, just require the bitpay module
// without messing with the process.env.HOME variable
var home = process.env.HOME;
process.env.HOME = '/path/where/you/want/the/.bitpay/directory';
var bitpay = require('bitpay');

// and change it back
process.env.HOME = home;

// need bitauth too
var bitauth = require('bitauth');

// NOTE: necessary to decrypt your key even if you didn't enter a password when you generated it.
// If you did specify a password, pass it as the first param to bitauth.decrypt()
var privkey = bitauth.decrypt('', fs.readFileSync('/path/to/.bitpay/api.key', 'utf8'));

var client = bitpay.createClient(privkey);
client.on('error', function(err) {
    // handle client errors here
    console.log(err);
});
client.on('ready', function(){
        var data = {
        price: 1,
        currency: 'USD'
    };

    // NOTE: the .as('pos') is necessary for Point of Sale requests, 
        // otherwise you'll get an "Invalid token" error
    client.as('pos').post('invoices', data, function(err, invoice) {
        if (err){
            // more error handling
            console.log(err);
        }
        else{
            // success
            console.log('invoice data', invoice);
        }
    });
});

Arguments for creating invoices can be viewed here: https://bitpay.com/api#resource-Invoices

Also, the current README and examples bundled in this module conflict, but the examples are more accurate, so it's best to use them as a starting point.

Hope this helps someone else.

[braydonf]

+1

[martindale]

Thanks a ton, @timbowhite! I think what you've written is a great candidate for a pull request to the guide for this plugin. What do you think?

[timbowhite]

@martindale sounds good, but may want to get some feedback on it from other users.

[mitchellhuang]

The client.as('pos') part of this writeup saved me. I was stuck implementing this module for a long time. Thanks so much for this write up @timbowhite. The README right now is not good. Instead of having all these API docs in the README they should just put a simple example like this to generate an invoice. Cause what do most websites do with BitPay when integrating a module like this? Generate invoices. I don't care about different facades, streaming, etc... just show me an example of how to generate a damn invoice with no prior knowledge of bitauth and node-bitpay-client.

[martindale]

@timbowhite just pinging you again, as per the above comment – might be a great opportunity to submit a full-on pull request!

[aiouy]

This was great, thanks. Please add this to the README docs.

[timbowhite]

@martindale all due respect, but bitpay is a for profit company, and I think it's a bit much asking your customers to perform the task of updating the docs for this clunky module. It shouldn't be hard for a bitpay employee to spend 15 minutes copy/pasting the key parts of the content above into the README.md. All due respect.

[samuelbohler]

@timbowhite, I'm sure @martindale's request was not about making customers do our work, but to allow those who have written code, patches, documentation, etc.. to get commit credit for their work. I personally hate it when I write up a patch or PR only to have it copied by the maintainer. It discourages me from wanting to contribute.

But, if you aren't concerned about that and we have your permission to use your content above under the MIT license, we would be more than happy to add it ourselves.

PS/Edit: I would like to personally thank you for the documentation comment you wrote up as well. It was very thorough and well thought out!

[timbowhite]

But, if you aren't concerned about that and we have your permission to use your content above under the MIT license, we would be more than happy to add it ourselves.

Not concerned with credit, full permission is granted on content under MIT, etc (see 2nd sentence of my original post)... I'm really just interested in making it as easy as possible for merchants using node.js to accept Bitcoin. Cheers.