Introduction

BlockchainAPI is a Bitcoin payment processor API designed for simplicity, reliability, and compatibility.

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. Our API takes care of the generation and monitoring of addresses. We will notify your server using a simple callback whenever a payment is received.

Our API here at BlockchainAPI.org was designed to be extremely easy to use. No need to sign up, pay for a plan, or submit a merchant application. Just send a simple GET request to the API to generate a deposit address for your customer, and handle GET request callbacks sent when payments are received.

Remember that this API is fully compatible with existing applications based on Blockchain.info's old Receive Payments API v1. The API methods work exactly the same way. The API is structured in this way because after Blockchain.info took down their original Receive Payments API v1, many users were left without a merchant payment solution. We are now here to provide that solution to merchants like you. Feel free to use your existing code or applications to utilize our API; simply change your system's configured root API URL from "blockchain.info" to "blockchainapi.org" and you'll be good to go.

Main features

Our system was designed from the ground up to be the most easy-to-use Bitcoin payment processor possible.

As Bitcoin enthusiasts, our main goal is to make it easier for businesses both small and large to accept Bitcoin as a payment method. We have worked to eliminate all potential obstacles and annoyances while ensuring your safety and security as a merchant.

No Registration Required

No need to worry about getting a merchant application accepted or going through any tedious signup processes. Go ahead and get up and running now!

No Branding

No logos or external pages or branded buttons. Our API returns a simple JSON document for you to handle on your server however you would like.

Low Fees

In order to continue to keep our API online, we take a 1% commission. Other than this small commission and the 0.0005 BTC transaction fee, there are no other costs.

Safe and Secure

Our API and backend systems are secured with HTTPS and high-grade firewalls. Bitcoins are transferred to you ASAP, so there's nothing to worry about!

Compatibility

As we mentioned earlier, this API is fully compatible with existing applications based on Blockchain.info's old Receive Payments API v1!

100% Tested and Error-free

Our API has protections in place for every possible problem, so you won't have to worry about strange errors or issues when using the API.

Getting started

If you do not have a Bitcoin wallet yet, it's time to get one.

Our API requires that you have at least one Bitcoin address to which all payments will be forwarded. The private key for this address does not need to be shared with us and can be kept offline for increased security. There are many different ways to get a Bitcoin address. If you do not already have one, you can get one easily; see potential wallet options below.

Some things you need to know

If you are about to explore Bitcoin, there are a few things you should know. Bitcoin lets you exchange money in a different way than with usual banks. As such, you should take time to inform yourself before using Bitcoin for any serious transaction. Bitcoin should be treated with the same care as your regular wallet, or even more in some cases! Please see this link to the note on the official Bitcoin website.

Cold Storage

Receive protection from hackers by receiving payments directly into an offline cold storage address or paper wallet.

Exchange Wallet

Use the deposit address of your Bitcoin exchange to directly receive BTC ready for exchange into your local currency.

Bitcoin Client

Use a Bitcoin address from a desktop client such as Bitcoin Core.

Online Wallet

Sign up for an online wallet like Blockchain.info's My Wallet or Coinbase.

API structure

This is a hierarchy of our current API endpoints and methods.

While it is currently relatively small, our current array of endpoints and methods will grow in the future. The file tree below shows the hierarchy we have online currently so you can visualize the structure of our system.

API endpoint/method hierarchy
  • Expand all
  • Collapse all
  • /api/receive - methods related to receiving payments from customers
    • ?method=create - generate a new deposit address to present to a customer
    • ?method=check_logs - check logs for payments with callbacks sent to a given callback URL

Generate addresses

The create method of the receive endpoint generates a unique Bitcoin address to which the customer may send payments.

Please note that payments of less than 0.0005 BTC will be ignored by our server and will not be forwarded. Additionally, you should know that the amount to be forwarded is computed as follows (the variable $amount is the original payment amount and 546 is the Bitcoin Core dust threshold): (min(floor($amount * ((100 - 1) / 100)), floor($amount - 546)) / 100000000) - 0.0005

Request

  • HTTP Method: GET
  • URL: https://blockchainapi.org/api/receive?method=create

The following table lists all additional GET parameters for the request:

Parameter Description Required
address The address you would like for payments to be forwarded to. This must be a valid Bitcoin address. Yes
callback The URL you would like for callbacks to be sent to. This must be a valid URL. Maximum length is 1024 characters. See more information on callbacks in the section below. Yes

The following block shows an example of the request URL:

copy
https://blockchainapi.org/api/receive?method=create&address=1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z&callback=http://example.com/callback?invoice_id=1234

Response (Success)

  • HTTP Status Code: 200
  • Content Type: application/json

The following table lists all potential properties of the JSON object returned in the response body:

Property Description Present
fee_percent An integer representing the percentage of the payment that is taken as a fee. This will always be set to 1. Always
destination The supplied destination Bitcoin address; payments will be forwarded here, so ensure that it's the right one. Always
input_address The generated Bitcoin address; give this to the customer. Always
callback_url The supplied callback URL; callbacks will be sent here, so ensure that it's the right one. See more information on callbacks in the section below. Always

The following code shows an example of the response body:

copy
{
    "fee_percent": 1,
    "destination": "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z",
    "input_address": "1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb",
    "callback_url": "http://example.com/callback?invoice_id=1234"
}

Response (Error)

  • HTTP Status Code: 500
  • Content Type: text/plain

The following code shows an example of the response body in the event of an error:

copy
The supplied address is not a valid Bitcoin address.

PHP Example

The following PHP code shows an example of how to make a request to this API endpoint and how to process the response:

copy
$secret = "7j0ap91o99cxj8k9";
$my_address = "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z";
$my_callback_url = "http://example.com/callback?invoice_id=1234&secret=" . $secret;
$api_base = "https://blockchainapi.org/api/receive";

$curl = curl_init();
curl_setopt_array($curl, array(
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_URL => $api_base . "?method=create&address=" . $my_address . "&callback=" . urlencode($my_callback_url)
));
$response = curl_exec($curl);
$http_status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($http_status_code == 200) {
	$decoded = json_decode($response, true);
	echo "Please send the payment to the following Bitcoin address: " . $decoded["input_address"];
} else {
	echo "Sorry, an error occurred: " . $response;
}

Receiving callbacks

You'll need some server-side code to handle the callbacks sent by our system when a payment is detected.

As mentioned before, each time a payment is received and forwarded to your Bitcoin address, your callback URL will be sent data about the payment. This is necessary for automated systems to know when a specific payment is sent. Our server will forward the payments and send these callbacks to your server immediately after payments are received and confirmed 1 times.

Callbacks will always be sent as GET requests containing the details of the payment and the forwarded transaction, in addition to any parameters already present in the callback URL. Once again, please recall that callback URLs have a maximum length of 1024 characters.

Remember that for security, you should make sure that you include a unique, secret parameter in your callback URL. This secret string will be passed back to the callback script when the callback is sent, along with any other parameters already present in the callback URL. It should be checked against the original secret string to ensure that the callback is coming from us and is not forged.

Callback Request

  • HTTP Method: GET
  • Source IP: 162.255.116.24 (could change in the future)

The following table lists all GET parameters that will be sent in the request to your server:

Parameter Description Present
value The amount of Bitcoin sent by the customer in satoshi (1 BTC = 100,000,000 satoshi). Make sure to convert this to BTC when necessary by dividing by 100,000,000. Always
input_address The Bitcoin address (generated by the API earlier) to which customer sent the payment. Always
confirmations The number of times the transaction has been confirmed at the time the callback is sent. This will always be 1. Always
transaction_hash The hash of the transaction in which the payment was forwarded to your Bitcoin address. Always
input_transaction_hash The hash of the customer's transaction sent to the generated address. Always
destination_address The destination address (that you supplied when generating the address) to which the payment was forwarded. Always

The following block shows an example of the callback request URL:

copy
http://example.com/callback?invoice_id=1234&secret=7j0ap91o99cxj8k9&value=100000000&input_address=1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb&confirmations=1&transaction_hash=0e3e2357e806b6cdb1f70b54c3a3a17b6714ee1f0e68bebb44a74b1efd512098&input_transaction_hash=4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b&destination_address=1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z

Expected Response

Callbacks will be marked as successful when if the exact text below is returned by your server:

copy
*ok*

You can find failed callbacks using the callback log endpoint described later.

PHP Example

The following PHP code shows an example of handle the callback sent to you by our server:

copy
$secret = "7j0ap91o99cxj8k9";
if ($_GET["secret"] !== $secret) die();

$my_address = "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z";
if ($_GET["destination_address"] !== $my_address) die();

$invoice_id = $_GET["invoice_id"];
$input_address = $_GET["input_address"];
$input_transaction_hash = $_GET["input_transaction_hash"];
$transaction_hash = $_GET["transaction_hash"];
$value_in_satoshi = $_GET["value"];
$value_in_btc = $value_in_satoshi / 100000000;

try {
	$conn = new PDO("mysql:host=localhost;dbname=test", "root", "");
} catch (PDOException $e) {
	die();
}

$stmt = $conn->prepare("INSERT INTO payments (invoice_id, input_address, input_transaction_hash, transaction_hash, value) VALUES (:invoice_id, :input_address, :input_transaction_hash, :transaction_hash, :value)");
$stmt->execute(array("invoice_id" => $invoice_id, "input_address" => $input_address, "input_transaction_hash" => $input_transaction_hash, "transaction_hash" => $transaction_hash, "value" => $value_in_satoshi));

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

Check logs

The check_logs method of the receive endpoint returns logs for payments with callbacks sent to a given callback URL.

Request

  • HTTP Method: GET
  • URL: https://blockchainapi.org/api/receive?method=check_logs

The following table lists all additional GET parameters for the request:

Parameter Description Required
callback The callback URL for which you would like to retreive a list of sent callbacks and corresponding payments. This must be a valid URL. Maximum length is 1024 characters. Yes

The following block shows an example of the request URL:

copy
https://blockchainapi.org/api/receive?method=check_logs&callback=http://example.com/callback?invoice_id=1234

Response (Success)

  • HTTP Status Code: 200
  • Content Type: application/json

The following table lists all potential properties of the JSON object returned in the response body:

Property Description Present
callback_url The callback URL for which you have requested this list of sent callbacks and corresponding payments. Always
callbacks An array of objects. Each one is a callback and its respective payment. The properties of these objects are self-explanatory. Always

The following code shows an example of the response body:

copy
{
    "callback_url": "http://example.com/callback?invoice_id=1234",
    "callbacks": [{
        "timestamp": "2016-03-16 16:57:45",
        "result": true,
        "fee_percent": 1,
        "value": 50000,
        "input_address": "1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb",
        "confirmations": 1,
        "transaction_hash": "1afb2eebe6ee69ab52da0a3ed98f5506c4ef00edcad852e98da346f42c568960",
        "input_transaction_hash": "02cb603c6066b22e23d6d998fbe7672776a098f93387fa86e362d18c9f496750",
        "destination_address": "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z"
    }]
}

Response (Error)

  • HTTP Status Code: 500
  • Content Type: text/plain

The following code shows an example of the response body in the event of an error:

copy
The supplied callback URL has never been sent any callbacks/notifications.

Test endpoints

You can demo all of our API endpoints and methods below using our handy in-browser API testing client.

copy
// Choose a URL to request, fill out the parameter values, and hit "Send Request"!

FAQ

We want to make your experience with BlockchainAPI as easy as possible. If there's anything you don't understand, try looking for answers here. Type some keywords into the search bar below and try to find the information you need. If you can't find what you're looking for, just head over to the contact page and send us a message!

  • What exactly is Bitcoin?

    Bitcoin is a digital currency (also called crypto-currency) that is not backed by any country's central bank or government. Bitcoins can be traded for goods or services with vendors who accept Bitcoins as payment. Bitcoin-to-Bitcoin transactions are made by digitally exchanging anonymous, heavily encrypted hash codes across a peer-to-peer (P2P) network. The P2P network monitors and verifies the transfer of Bitcoins between users. Each user's Bitcoins are stored in a program called a digital wallet, which also holds each address the user sends and receives Bitcoins from, as well as a private key known only to the user.
  • What does BlockchainAPI do?

    BlockchainAPI is a Bitcoin payment processor. Bitcoin has been growing very quickly into a very popular and unique currency, so it is becoming increasingly desirable for merchants to accept Bitcoin as a payment method on their websites. Merchants like you who want to accept Bitcoin as payment for goods or services on a website can use our API to generate unique Bitcoin addresses to which customers can send payments. Your server will be notified of all of your customers' payments.
  • How does BlockchainAPI work?

    Your server will send a request to our API for a unique payment address which it can present to the customer. Our server will send callbacks/notifications to your server immediately after payments are received and confirmed 1 times. You'll need to have server-side code to handle these callbacks by placing the invoice data in your database and/or whatever else you need to do.