Initiating LNURL-Withdrawal

LNURL-Withdrawal provides users with a seamless QR code-initiated Lightning Network withdrawal experience.

Users can simply scan a QR code or click a button, and their Bitcoin wallet will recognize the withdrawal attempt and display the corresponding description and amount.

Example

πŸ“˜

Fixed withdrawal amount

To enable users to withdraw a specific fixed amount, just set both min_amt and max_amt variables to the same value.

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


const withdrawal = {
  min_amt: 5000,
  max_amt: 5000,
  description: "claim 5000 sats",
  external_id: "my-external-uuid",
  callback_url: "https://example.com/webhook/opennode",
};


opennode.createLnUrlWithdrawal(withdrawal)
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.error(`${error.status} | ${error.message}`);
  });
curl https://api.opennode.com/v2/lnurl-withdrawal \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Authorization: YOUR_API_KEY" \
	-d '"min_amt": 5000, "max_amt": 5000, "description": "claim 5000 sats", "external_id": "my-external-uuid", "callback_url": "https://example.com/webhook/opennode"'

When the request is correctly sent, the API replies with 200 and retrieves the LNURL-Withdrawal information.

{
	"data": {
		"id": "f21000-0000-0000-0000-sample",
		"min_amt": 5000,
		"max_amt": 5000,
		"description": "claim 5000 sats",
		"callback_url": "https://example.com/webhook/opennode",
		"external_id": "my-external-uuid",
		"uri": "lightning:LNURLSAMPLEGHJ7CTSDYH8QUN9WPEX7EPWDACX2MNWDAJX2TNRDAKJ7A3J9AKXUATJDSKHW6T5DPJ8YCTHV9KZ7UN9V9JZ7E3NXGURSVFEXSKNXV3HXVKNGWPCXUKKZVFNXSKK2DMRXD3KXER9XYEKVDSS5EXVM",
		"lnurl": "LNURLSAMPLE8GHJ7CTSDYH8QUN9WPEX7EPWDACX2MNWDAJX2TNRDAKJ7A3J9AKXUATJDSKHW6T5DPJ8YCTHV9KZ7UN9V9JZ7E3NXGURSVFEXSKNXV3HXVKNGWPCXUKKZVFNXSKK2DMRXD3KXER9XYEKVDSS5EXVM",
		"created_at": "2022-08-18T04:35:12.277Z",
		"expiry_date": "2023-08-18T04:35:12.275Z",
		"used": false
	}
}

LNURL-Withdrawal can be encoded to a QR code or a hyperlink, and is supported by all Lightning Network-enabled Bitcoin wallets.

Webhooks

Once a LNURL-encoded QR code is scanned by a wallet, you will receive an webhook on the callback_url provided. This webhook let's you know wether the withdrawal attempt was succeeded or failed. If the latter, an error reason is provided.

πŸ“˜

To confirm that a withdrawal was initiated using LNURL-Withdrawal, verify that a lnurl_withdrawal parameter is included in the payload.

## Webhook

`POST application/x-www-form-urlencoded`

When a `callback_url` is provided upon the LNURL-Withdrawal creation, an webhook is sent when it's consumed

`{
	id: string,
	type: string,
	amount: integer,
	reference: string,
	processed_at: unix timestamp,
	address: string,
	fee: integer,
	status: string,
	lnurl_withdrawal: object ( { id: string, external_id: string })
	hashed_order: string
}`

What’s Next

LNURL-Withdrawal API reference