Receiving Bitcoin (On-chain)

How to receive Bitcoin transactions on your application

The Bitnob API allows you to securely and easily receive bitcoin payments from anyone in the world.
In order to receive Bitcoin payments, you need to generate an address. The API supports generating millions of addresses


Avoid Address Reuse

We recommend using a new address whenever you want to receive payments. This makes it easier to preserve your customer's privacy. For more flexibility, you can give your customer's the ability to generate a new address at will.

When payments come to their old addresses, we will still send a webhook to you verifying the payment.

Bitnob API supports receiving Bitcoin using all the address formats:

There are 3 types of bitcoin address formats:

  • P2PKH(Pay-to-Public-Key-Hash) or Legacy address (old address format) is the oldest version of Bitcoin addresses. It starts with the number “1” and contains 26 to 36 characters.

Transaction fees when using this address format are usually higher than when using segwit addresses because transactions with this address format are larger in size.
Example: 1K1cP1eP0QTefi5DMPTfTL53smv7DivfNa

  • P2SH(Pay-To-Script Hash) is a new address format structured similarly to P2PKH, but starts with “3” instead of “1”. P2SH provides more complex functionality than the previous type of address. Average transaction fees using this format are less than the legacy address ones.

Example: 3GRdnTq18LyNveWa1gQJcgp8qEnzijv5vR

  • P2WPKH(Pay-to-Witness-Public-Key-Hash ) or Bech32 is an advanced address format that is used to reduce blockchain block sizes to speed up transaction response time. They start with “bc1” and are longer than P2PKH and P2SH. Bech32 is the native Segwit addressing format (although P2SH can also be a Segwit address).
    The advantage is the lowest transaction sending fee and high processing speed.

Example: bc1qnkyhslv83yyp0q0suxw0uj3lg9drgqq9c0auzc

You can specify use either of legacy, p2sh-segwit, and bech32 but by default we generate a bech32 address for you.

Processing Received Payments

Once you generate an address, we will be listening for incoming transactions to that address and notify you via webhooks with the event type btc.onchain.received.success.

We recommend you wait for at least 3 confirmations before giving the customer value on your application.

You can always re-query a transaction to see the number of confirmations it has


Verify webhook notifications

Properly set up and verify all notifications sent from us via webhooks. Use the webhook guide to see how you can verify webhook notifications from Bitnob