You provide an extended public key (xPub) and we generate a unique, unused corresponding address for your customers to send payment to. We notify you of payments to that address instantly using a callback URL of your choosing.

The Blockchain Receive Payments API V2 is the quickest and easiest way to begin accepting automated bitcoin payments. Consisting of just a simple HTTP GET request, you can be up and running in minutes.

One of the difficulties involved with receiving bitcoin payments is the need to generate a unique address for each new user or invoice. These addresses need to monitored and stored securely. The blockchain receive payments API takes care of the generation and monitoring of addresses. We will notify your server using a simple callback whenever a payment is received.

In order to use the Receive Payments API V2, please apply for an API key at This API key is only for our Receive Payments API. You cannot use the standard blockchain wallet API key for Receive Payments V2, and vice versa.

This API requires you to have a BIP 32 account xPub in order to receive payments. The easiest way to start receiving payments is to open a Blockchain Wallet at You should create a new account inside your wallet exclusively for transactions facilitated by this API. When making API calls, use the xPub for this account (located in Settings -> Addresses -> Manage -> More Options -> Show xPub).

This method creates a unique address which should be presented to the customer. For any payments sent to this address, you will be sent an HTTP notification. Please note that every call to the server will increment the `index` parameter. This is done so you do not show the same address to two different customers. However, all funds will still show within the same account.$xpub&callback=$callback_url&key=$key

As defined in BIP 44, wallet software will not scan past 20 unused addresses. Given enough requests from this API that don't have a matching payment, you could generate addresses past this horizon, which would make spending funds paid to those addresses quite difficult. For this reason, this API will return an error and refuse to generate new addresses if it detects it would create a gap of over 20 unused addresses. If you encounter this error, you will either need to switch to a new xPub (within the same wallet is fine), or receive a payment to one of the previous 20 created addresses

You can control this behavior by optionally passing `gap_limit` as an extra URL parameter. Please note, this will not increase the number of addresses that will be monitored by our servers. Passing the `gap_limit` parameter changes the maximum allowed gap before the API will stop generating new addresses. Using this feature will require you understand the gap limitation and how to handle it (for advanced users only):$xpub&callback=$callback_url&key=$key&gap_limit=$gap_limit

Derive an unused address using your xPub:

curl "[yourkeyhere]"

Have your customer send bitcoin to the address contained in the response:

Response: 200 OK, application/json

PHP Example Full source code (PHP, Python, Ruby)

$secret = 'ZzsMLGKe162CfA5EcG6j';

$my_xpub = '{YOUR XPUB ADDRESS}';
$my_api_key = '{YOUR API KEY}';

$my_callback_url = ''.$secret;

$root_url = '';

$parameters = 'xpub=' .$my_xpub. '&callback=' .urlencode($my_callback_url). '&key=' .$my_api_key;

$response = file_get_contents($root_url . '?' . $parameters);

$object = json_decode($response);

echo 'Send Payment To : ' . $object->address;

This method monitors an address of your choice for received and / or spent payments. You will be sent an HTTP notification immediately when a transaction is made, and subsequently when it reaches the number of confirmations specified in the request.

You are required to specify the request's notification behaviour. Setting the behaviour to 'DELETE' will delete the request after the first relelvant notification is sent to your callback address. Setting the behaviour to 'KEEP' will send additional notifications every time a transaction with the specified confirmations and operation type is sent to or from the address in the request.

Operation type is an optional parameter indicating whether the address will be monitored for received or spent transactions, or both. By default both operation types are monitored.

You may also optionally specify the number of confirmations a transaction reaches before being sent a notification. Note that you will receive a notification at 0 confirmations (i.e. immediately when the transaction is made), and again when it reaches the number of confirmations specified in the request (3 confirmations by default).

Monitor an address for every received payment with 5 confirmations:

curl -H "Content-Type: text/plain" --data '{"key":"[your-key-here]","addr":"183qrMGHzMstARRh2rVoRepAd919sGgMHb","callback":"","onNotification":"KEEP", "op":"RECEIVE", "confs": 5}'
Response: 200 OK, application/json
  "id" : 70,
  "addr" : "183qrMGHzMstARRh2rVoRepAd919sGgMHb",
  "op" : "RECEIVE",
  "confs" : 5,
  "callback" : "",
  "onNotification" : "KEEP"

The id in the response can be used to delete the request:

curl -X DELETE "[your-key-here]"
Response: 200 OK, application/json
{ "deleted": true }

This method allows you to request callbacks when a new block of a specified height and confirmation number is added to the blockchain.

As with balance update requests, you are required to specify the request's notification behaviour to either 'KEEP' or 'DELETE'.

Height is an optional parameter indicating at which height you would like to receive a block notification - if unspecified, this will be the height of the next block to arrive.

Confs is another optional parameter indicating how many confirmations a block should have when a notification is sent.

Request a single notification when the Bitcoin Blockchain reaches 500,000 blocks:

curl -H "Content-Type: text/plain" --data '{"key":"[your-key-here]","height":500000,"callback":"","onNotification":"DELETE"}'
Response: 200 OK, application/json
  "id" : 64,
  "height" : 500000,
  "callback" : "",
  "confs" : 1,
  "onNotification" : "DELETE"

The id in the response can be used to delete the request:

curl -X DELETE "[your-key-here]"
Response: 200 OK, application/json
{ "deleted": true }

Please note, the callback url is limited to 255 characters in length.

When a payment is received by a generated address, or by an address monitored by a balance update request, will notify the callback URL you specify. For balance update callbacks and additional notification will be sent once the transaction reaches the specified number of confirmations.

A block notification is sent every time a new block is added to the blockchain, and matches the height and number of confirmations set in the notification request.

PHP Example Full source code (PHP, Python, Ruby)

An example callback as a result of the above PHP example.

$real_secret = 'ZzsMLGKe162CfA5EcG6j';
$invoice_id = $_GET['invoice_id']; //invoice_id is passed back to the callback URL
$transaction_hash = $_GET['transaction_hash'];
$value_in_satoshi = $_GET['value'];
$value_in_btc = $value_in_satoshi / 100000000;

//Commented out to test, uncomment when live
if ($_GET['test'] == true) {

try {
  //create or open the database
  $database = new SQLiteDatabase('db.sqlite', 0666, $error);
} catch(Exception $e) {

//Add the invoice to the database
$stmt = $db->prepare("replace INTO invoice_payments (invoice_id, transaction_hash, value) values(?, ?, ?)");
$stmt->bind_param("isd", $invoice_id, $transaction_hash, $value_in_btc);

if($stmt->execute()) {
   echo "*ok*";

In order to acknowledge successful processing of the callback, your server should respond with the text "*ok*" (no quotes), in plain-text, no HTML. If the server responds with anything else, or nothing, the callback will be resent again for every new block (approximately every 10 minutes) up to 1000 times (1 week). Callback domains which appear dead or never return the "*ok*" response may be blocked from the service.

Check the index gap between last address paid to and the last address generated using the using the checkgap endpoint. Use the xpub you want to check and your API key like so:

curl "[yourxpubhere]]&key=[yourkeyhere]"

See logs related to callback attempts using the callback_logs endpoints. Use the exact callback in question and your API key like so:

curl "[yourkeyhere]"
       "callback": "[yourkeyhere]",
       "called_at": "2015-10-21T22:43:47Z",
       "raw_response": "*bad*",
       "response_code": 200
       "callback": "[yourkeyhere]",
       "called_at": "2015-10-21T22:43:55Z",
       "raw_response": "*bad*",
       "response_code": 200

A custom secret parameter should be included in the callback URL. The secret will be passed back to the callback script when the callback is fired, and should be checked by your code for validity. This prevents someone from trying to call your servers and falsely mark an invoice as 'paid'.

Use the Exchange Rates API to convert values in local currencies to BTC. The Demo Apps below include examples of how to do this.

If you would like convert payments received in Bitcoin to fiat currency quickly use a bitcoin address from an exchange wallet.

A double spend occurs when a malicious user spends the same BTC twice. A payment that initial appears successful could be reversed at a later date. This is counteracted by waiting for the transaction to be included in the blockchain and reaching a number of confirmations. 6 confirmations is generally considered safe for high value transactions.

Validate the transaction confirmations in the callback script by checking $_GET['confirmations'] parameter. It is recommended you acknowledge the transaction at zero confirmations but only trust the transaction after one confirmation. For example, if purchasing a product, we would show the order as successful at zero confirmations (the first callback, but do not echo "*ok*" yet), but only ship the product when 4 or more confirmations are reached. See the PHP demo callback.php for an example.

if ($_GET['confirmations'] >= 6) {
    //Insert into confirmed payments
    echo '*ok*';
} else {
    //Insert into pending payments
    //Don't print *ok* so the notification resent again on next confirmation

Receive addresses never expire and will continue to be monitored until an "*ok*" is received in the callback response or has notified the callback 1000 times.

There is no limit to the number of receiving address which can be generated (as long as the 20 address gap limitation is met), the service is designed to monitor millions of addresses.

Callback domains which appear dead or never return the "*ok*" response may be blocked from the service.