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

Handling underpaid payments

When a customer pays via standard on-chain transaction, sometimes the invoice is underpaid by a few satoshis. This is most common when the buyer pays via an exchange or custodial wallet and these services take a fee on top of the payment.

You can choose to accept payments that are just slightly underpaid. To enable that feature, access Settings - Payments and Invoices and select a percentage that you feel comfortable with.

When a payment falls bellow the chosen threshold your charge's status will be marked as underpaid.

If you're using OpenNode's checkout experience (checkout.opennode.co), the buyer will be asked to send the remainder or cancel the payment and get their money back (refund). By choosing to cancel the payment, the buyer will pay 200 satoshis (0.00000200 BTC) which goes toward paying the on-chain network fees associated with the refund.

When underpaid, customer is asked to send the remainder.

When underpaid, customer is asked to send the remainder.

When underpaid, buyer has the option to get his money back and the order is canceled.

When underpaid, buyer has the option to get his money back and the order is canceled.

If you are not using our payment page, you should allow your user to pay the remainder or ask for a refund.

Pay the missing amount

A webhook event is sent whenever a charge status is underpaid.

The buyer can complete their payment by sending the remainder (missing_amt) to the given bitcoin address (address).

POST callback_url | application/x-www-form-urlencoded
{
  id: 'ba57e419-a6c9-41b2-a54c-b870d073d899',
  callback_url: 'https://5eaacde7.ngrok.io/',
  success_url: 'https://opennode.co',
  status: 'underpaid',
  order_id: 'N/A',
  description: 'N/A',
  price: '250413',
  fee: '0',
  auto_settle: '0',
  address: '2Mz4Sx2fmKpop4Hmi4jEtJhiuDCF9VVu2ds',
  missing_amt: '125366',
  transactions: [
    {
      address: '2Mz4Sx2fmKpop4Hmi4jEtJhiuDCF9VVu2ds',
      created_at: '1559657208',
      settled_at: '',
      tx: 'e1e6e522386948daeabfb5b017aa87a695a823c9f561e88f03b6f467f55ba735',
      status: 'pending',
      amount: '125047'
    }
  ],
  hashed_order: 'c2a3896d4c8bfdcc25bbff0f3f15278fd948b96035f0438372eee9d4898f53b7'
}

Refunding money

When a charge has been underpaid, you can optionally cancel the payment and send the money back to your buyer.

You can initiate the refund process using the Refunds API.

You will need to submit the checkout's ID (id) along with a bitcoin address and email (optional) that your buyer should provide. OpenNode will refund your buyer and update them on their refund status via email.

const request = new XMLHttpRequest();

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

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

let body = {
  checkout_id: 'ba57e419-a6c9-41b2-a54c-b870d073d899',
  address: '2MvPEjUGgE144amswWNxZh7634H42Lqzt6W',
  email: 'jonhdoe@example.com'
};

request.send(JSON.stringify(body));

After a refund is initiated, the charge's new status is refunded. If you initially passed a callback_url on the charge creation a webhook will be sent with the new status and the refund information:

POST callback_url | application/x-www-form-urlencoded
{
  id: 'ba57e419-a6c9-41b2-a54c-b870d073d899',
  callback_url: 'https://5eaacde7.ngrok.io/',
  success_url: 'https://opennode.co',
  status: 'refunded',
  order_id: 'N/A',
  description: 'N/A',
  price: '250413',
  fee: '0',
  auto_settle: '0',
  address: '2Mz4Sx2fmKpop4Hmi4jEtJhiuDCF9VVu2ds',
  missing_amt: '125366',
  transactions: [
    {
      address: '2Mz4Sx2fmKpop4Hmi4jEtJhiuDCF9VVu2ds',
      created_at: '1559657208',
      settled_at: '',
      tx: 'e1e6e522386948daeabfb5b017aa87a695a823c9f561e88f03b6f467f55ba735',
      status: 'pending',
      amount: '125047'
    }
  ],
  refund: {
        "id": "97f6bee9-c36b-4b1f-a7e5-f9ab6e695c44",
        "email": "johndoe@example.com",
        "address": "tb1qm9jn6l66eeap72e5meu3jwl5wnv4lg6x79e3zu",
        "amount": '125047',
        "fee": '200',
        "tx": null,
        "status": 'pending',
        "created_at": 1560349045,
        "processed_at": null,
        "checkout_id": 'ba57e419-a6c9-41b2-a54c-b870d073d899'
  }
  hashed_order: 'c2a3896d4c8bfdcc25bbff0f3f15278fd948b96035f0438372eee9d4898f53b7'
}

Handling underpaid payments


Suggested Edits are limited on API Reference Pages

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