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