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.

❗️

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 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: '[email protected]',
  notif_email: '[email protected]',
  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 https://api.opennode.co/v1/charges \
    -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{ "description": "My test charge",
        "amount": 10.5,
      "currency": "USD",
      "order_id": "823320",
      "customer_name": "John Doe",
      "customer_email": "[email protected]e.com",
      "notif_email": "[email protected]",
      "callback_url": "https://example.com/webhook/opennode",
      "success_url": "https://example.com/order/abc123",
      "auto_settle": false }'

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

{
    "data": {
        "id": "1543f881-5b86-46f0-b0ec-8f2d3a6b9498",
        "name": null,
        "description": "My test charge",
        "created_at": 1559566069,
        "status": "unpaid",
        "callback_url": "https://example.com/webhook/opennode",
        "success_url": "https://example.com/order/abc123",
        "order_id": "823320",
        "notes": "Order: 823320\nCustomer Email: N/A",
        "currency": "USD",
        "source_fiat_value": 10.5,
        "fiat_value": 10.5,
        "auto_settle": false,
        "notif_email": null,
        "lightning_invoice": {
            "expires_at": 1559569669,
            "payreq": "LNTB1230250N1PW029H4PP55A5L9MULUWDU9DF8R3JYAJTGL64YU60MRSLP98QZHDD9L29ZXE8SDQHF4UJQAR9WD6ZQCMGV9EXWEGCQZPG6G0SY8DDA8PV9HYJ65EXG9NENW0VCLELHNKN0TA20R03FVL6EK2NE7MNETPNDHWR0TMTXR6RCXA5AN6XY732RLZ6L23KHLGKW3Y4F7SPZR5Z5V"
        },
        "chain_invoice": {
            "address": "2NAVFQaNg2y3QAoh6nZ5WrvWpxp7YQ7Yaed"
        },
        "address": "2NAVFQaNg2y3QAoh6nZ5WrvWpxp7YQ7Yaed",
        "amount": 123025,
        "uri": "bitcoin:2NAVFQaNg2y3QAoh6nZ5WrvWpxp7YQ7Yaed?amount=0.00123025&label=My test charge&lightning=LNTB1230250N1PW029H4PP55A5L9MULUWDU9DF8R3JYAJTGL64YU60MRSLP98QZHDD9L29ZXE8SDQHF4UJQAR9WD6ZQCMGV9EXWEGCQZPG6G0SY8DDA8PV9HYJ65EXG9NENW0VCLELHNKN0TA20R03FVL6EK2NE7MNETPNDHWR0TMTXR6RCXA5AN6XY732RLZ6L23KHLGKW3Y4F7SPZR5Z5V"
    }
}

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.


What’s Next