Receiving bitcoin payments

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.
Charges Webhooks

❗️
Lightning Network limit
The API does not return a lightning invoice when creating a charge with an amount bigger than 500000000 sats (5 BTC).

Example

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'API_KEY'
  },
  body: '{"amount":"4.13","description":"sample_description","currency":"USD","customer_email":"[email protected]","notif_email":"[email protected]","customer_name":"nakamoto","order_id":"21","callback_url":"https://yourwebhook.com","success_url":"https://yoursuccessurl.com","auto_settle":false,"ttl":10}'
};

fetch('https://api.opennode.com/v1/charges', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

const opennode = require('opennode');
opennode.setCredentials('MY_API_KEY', 'dev');

const charge = {
  "amount":"4.13",
  "description":"sample_description",
  "currency":"USD",
  "customer_email":"[email protected]",
  "notif_email":"[email protected]",
  "customer_name":"nakamoto",
  "order_id":"21",
  "callback_url":"https://yourwebhook.com",
  "success_url":"https://yoursuccessurl.com",
  "auto_settle":false,
  "ttl":10
};

opennode.createCharge(charge)
    .then(charge => {
        console.log(charge);
    })
    .catch(error => {
        console.error(`${error.status} | ${error.message}`);
    });

curl --request POST \
  --url https://api.opennode.com/v1/charges \
  --header 'Authorization: API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "4.13",
    "description": "sample_description",
    "currency": "USD",
    "customer_email": "[email protected]",
    "notif_email": "[email protected]",
    "customer_name": "nakamoto",
    "order_id": "21",
    "callback_url": "https://yourwebhook.com",
    "success_url": "https://yoursuccessurl.com",
    "auto_settle": false,
    "ttl": 10
}'

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

{
    "data": {
        "id": "c9628482-2124-4e45-aa64-3708ccca8cdc",
        "description": "sample_description",
        "desc_hash": false,
        "created_at": 1661215876,
        "status": "unpaid",
        "amount": 19362,
        "callback_url": "https://yourwebhook.com",
        "success_url": "https://yoursuccessurl.com",
        "hosted_checkout_url": "https://checkout.opennode.com/c9628482-2124-4e45-aa64-3708ccca8cdc",
        "order_id": "21",
        "currency": "USD",
        "source_fiat_value": 4.13,
        "fiat_value": 4.13,
        "auto_settle": false,
        "notif_email": "[email protected]",
        "address": "2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm",
        "metadata": {
            "name": "nakamoto",
            "email": "[email protected]"
        },
        "chain_invoice": {
            "address": "2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm"
        },
        "uri": "bitcoin:2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm?amount=0.00019362&label=sample_description&lightning=lntb193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv",
        "ttl": 10,
        "lightning_invoice": {
            "expires_at": 1661216474,
            "payreq": "lntb193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv"
        }
    }
}

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

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

If you want to build your own checkout experience you can create BIP21 + BOLT11 QR code using the uri field.

Webhooks

❗️Lightning Network limit

Example

❗️
Lightning Network limit