The OpenNode Developer Hub

Welcome to the OpenNode developer hub. You'll find comprehensive guides and documentation to help you start working with OpenNode as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Receiving money through the Lightning Network

You need to create a 'charge' to receive payments through OpenNode. A charge contains both a Lightning Network BOLT11 invoice, capable of accepting payments through the LN protocol, and a on-chain address for standard on-chain transactions.

Webhooks

In order to receive notifications when a 'charge' changes its status, you need to subscribe to the 'charge' events. You can subscribe by passing a 'callback_url' parameter on the charge payload.

Lightning Network limit

The API does not return a lightning invoice when creating a charge with an amount bigger than 4294967 sats (~ 0.0429 BTC).

Example

var request = new XMLHttpRequest();

request.open('POST', 'https://api.opennode.co/v1/charges');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'API-Key');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

var body = {
  description: 'My test charge',
  amount: 10.5, // required
  currency: 'USD',
  order_id: '823320',
  customer_name: 'John Doe',
  customer_email: 'me@johndoe.com',
  callback_url: "https://example.com/webhook/opennode",
  success_url: 'https://example.com/order/abc123',
  auto_settle: false
};

request.send(JSON.stringify(body));
const opennode = require('opennode');
opennode.setCredentials('MY_API_KEY', 'dev');

const charge = {
  description: 'My test charge',
  amount: 10.5, // required
  currency: 'USD',
  order_id: '823320',
  customer_name: 'John Doe',
  customer_email: 'me@johndoe.com',
  callback_url: "https://example.com/webhook/opennode",
  success_url: 'https://example.com/order/abc123',
  auto_settle: false
};

opennode.createCharge(charge)
 .then(charge => {
   console.log(charge);
 })
  .catch(error => {
   console.error(`${error.status} | ${error.message}`);
 });
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: API-Key" \
     --data-binary "{
     	"description": 'My test charge',
      "amount": 10.5,
      "currency": 'USD',
      "order_id": '823320',
      "customer_name": 'John Doe',
      "customer_email": 'me@johndoe.com',
      "callback_url": "https://example.com/webhook/opennode",
      "success_url": 'https://example.com/order/abc123',
      "auto_settle": false
		}"
'https://api.opennode.co/v1/charges'

If the request was correctly sent, the API will reply with a 201 status code and charge object:

{
    "data": {
      "id": "0ca3e0f3-d1d9-4ad9-9523-6a41b1506078",
      "name": "John Doe",
      "description": "My test charge",
      "created_at": 1553870152,
      "status": "unpaid",
      "callback_url": "https://example.com/webhook/opennode",
      "success_url": "https://example.com/order/abc123",
      "order_id": "823320",
      "notes": "Order: 823320\nCustomer Email: me@johndoe.com",
      "currency": "USD",
      "source_fiat_value": 10.5,
      "fiat_value": 10.5,
      "auto_settle": false,
      "notif_email": null,
      "lightning_invoice": {
      "expires_at": 1553873752,
      "payreq": "lntb2564800n1pwfut2gpp54xmtfghdspg2htyfn8vxad9huelst8fa28zfmg7zqwa23yzwl2gqdqhf4ujqar9wd6zqcmgv9exwegcqzysc8ah3vvleqrxr2cx48qr9x74y33z5tkvn4y2wxmd3au9z490r3a46s9lc3uc6ujzf2dvs8te95np8dkha53hyc2925lgfkvnlh872hqqpsu7nn"
       },
       "chain_invoice": {
        	"address": "2Mt9V38hLFpHDPStmVWyNPGqWoMpdRHgo33"
       },
       "amount": 256480
    }
}

You can use OpenNode's native checkout experience by redirecting your user the checkout endpoint:

Development - https://dev-checkout.opennode.co/ {id}
Production - https://checkout.opennode.co/ {id}

If you want to build your own checkout experience you can create BIP21 + BOLT11 QR code:

function buildQRCode(data) {
  const bolt11 = data.lightning_invoice.payreq;
  const btc_amount = parseFloat(data.amount/100000000).toFixed(8);
  const bip21 = `bitcoin:${chain_invoice.address}?amount=${btc_amount}&label=${chain_invoice.description}&lightning=${lightning_invoice.payreq}`;
  return bip21;
}


console.log(buildQRCode(data));

What's Next

Charges Webhooks

Receiving money through the Lightning Network


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.