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.

Existing users, beginning January 1st 2016 you will need to upgrade your implementation to use the V2 API. Please open a Blockchain Wallet at and follow the instructions below.

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 can not use the standard blockchain 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 -> Accounts & Addresses -> 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.

You can control this behavior by optionally passing one of `gap_limit` or `index` as extra URL parameters (please not they're mutually exclusive). Passing the `gap_limit` parameter changes the maximum allowed gap before the API will stop generating new addresses:$xpub&callback=$callback_url&key=$key&gap_limit=$gap_limit

Passing `index` allows you to take direct control over which keys are generated. The API will simply return the address at the requested index:$xpub&callback=$callback_url&key=$key&index=$index

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;

When a payment is received, will notify the callback URL you specify. Please note, the callback url is limited to 255 characters in length.

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, 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.