Receive Payments API

The Incredibly Easy Way To Process Bitcoin Payments. All you need is one bitcoin address - No Sign Up, No Downloads, No Fees!

No Signup Required

No account or approval is needed. You can be up and running in a few minutes.

Receive Payment For Free

Receiving transactions is completely free, any network fees will be paid by us.

No Branding

Integrates into your existing payment system with no branding.

Secure & Low Trust

Payments typically only pass through our servers for a few seconds. We do not need to store or hold any bitcoins.

Over 2 Million BTC Processed

The blockchain receive payments API is the quickest and easiest way to begin accepting automated bitcoin payments. Consisting of just two simple http GET requests you can be up and running in minutes with no account or approval needed.

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.

You provide a bitcoin address we generate unique addresses that forwards payments to that address instantly notifying a callback URL.

The receive payment API requires that you have at least one bitcoin address in which all payments will be forwarded to. The private key for this address does not need to be shared with us and can be kept offline for increased security.

This method creates a unique address which should be presented to the customer. Any payments sent to this address will be forwarded to your own bitcoin address. Each time a payment is forwarded the callback URL will be called.

The minimum supported transaction size is 0.0005 BTC. Forwarding transactions will include a network fee paid by blockchain.info.

https://blockchain.info/api/receive?method=create&address=$receiving_address&callback=$callback_url

Response: 200 OK, application/json
{
    "fee_percent":0,
    "destination":"1A8JiWcwvpY7tAopUkSnGuEYHmzGYfZPiq",
    "input_address":"1KZoUuPWFAeyVySHAGqvTUDoX6P3ntuLNF",
    "callback_url":"http://yoururl.com"
}

If you do not receive the callback double check the callback_url provided in the response is correct.

Error Response: Error 500, text/plain
Error Generating Receiving Address

PHP Example

$secret = 'ZzsMLGKe162CfA5EcG6j';

$my_address = '{YOUR BITCOIN ADDRESS}';

$my_callback_url = 'https://mystore.com?invoice_id=058921123&secret='.$secret;

$root_url = 'https://blockchain.info/api/receive';

$parameters = 'method=create&address=' . $my_address .'&callback='. urlencode($my_callback_url);

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

$object = json_decode($response);

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

Call The API Call the generate receiving address api

This is the bitcoin address you want to receive the payment to.

This is the http URL you want to be notified at. Add custom parameters to identify which user the payment belongs to e.g. http://mydomain.com?username=danny_919


            

            
To pay with bitcoin please send to: 

Callback Test Fire a test callback

Callbacks sent with this tool will not be retried on failure.



            

This is the URL which will be called when the address receives a payment. A Random transaction will be simulated.

Check Callback Response Log Enter a Callback URL to view the log of callback attempts

The URL must be exactly equal to when it was passed to the create address method (including parameters). There is no fuzzy matching.

When a payment is received blockchain.info will notify the callback URL passed using the create method. The parameters will be supplied in a http GET request. The callback url is limited to 255 characters in length.

Parameters

Expected Response

In order to acknowledge successful processing of the callback the server should respond with the text "*ok*". If the server responds with anything else the callback will be resent again every new block (approximately every 10 minutes) up to 1000 times (1 week).

A notification will never be sent for the same transaction twice once acknowledged with "*ok*". It is a good idea to record the transaction hash even if not needed to detect duplicates for logging purposes.

PHP Example

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'];
$input_transaction_hash = $_GET['input_transaction_hash'];
$input_address = $_GET['input_address'];
$value_in_satoshi = $_GET['value'];
$value_in_btc = $value_in_satoshi / 100000000;

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

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

//Add the invoice to the database
$query = "insert INTO invoice_payments (invoice_id, transaction_hash, value) values($invoice_id, '$transaction_hash', $value_in_btc)";

if($database->queryExec($query, $error)) {
   echo "*ok*";
}

//Select the amount paid into an invoice with select SUM(value) as value from invoice_payments where invoice_id = $invoice_id

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 check for validity.

Test notifications sent using the "Call the API" tool above will include the parameter "test" with a value of "true". Callback processing scripts should always check for this testing flag.

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, but only ship the product when 6 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
}

Normal addresses never expire and will continue to be monitored and notify the callback url forever.

  • Display An Invoice To the User. Convert USD to BTC.
  • Show a Payment Button.
  • Redirect the user to a status page on payment.
  • When payment is confirmed show an image.

https://github.com/blockchain/receive_payment_php_demo

A very simple Java example showing the basics of how to generate a server side address and process a payment callback.

https://github.com/blockchain/receive_payment_java

There is no limit to the number of receiving address which can be generated, the service is designed to monitor millions of addresses.

The minimum transaction size is 0.0005 BTC. There is no maximum payment or any other limitations.

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