BlockchainAPI Logo
You must enable Javascript to continue to use this website.

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 be 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 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 all good.

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 see the note on the official Bitcoin website.

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 tree on the right shows the hierarchy we have online currently so you can visualize the structure of our system.

/api/btc 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

?method=check_fees check the current fees required for sending payments to our node

Check Fees

You can check the current fees being used to forward transactions below.

Request

  • HTTP Method: GET
  • URL: https://blockchainapi.org//api/btc?method=check_fees

The following block shows an example of the request URL:

https://blockchainapi.org//api/btc?method=check_fees

Response (Success)

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

Response (Error)

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

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

"error": [{
    "Failed to get fees."
}]

Example Code

Below is a piece of example code written in PHP to generate addresses using our api:

# PHP Example To Generate Address
$api_base = "https://blockchainapi.org/api/btc";

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => $api_base . "?method=check_fees
));

$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);
    $minersFee = $decoded['success']['miners_fee'];
    $transactionFee = $decoded['success']['estimated_transaction_fee'];

    echo 'Miners fee: '.$minersFee.'<br>';
    echo 'Transaction fee: '.$transactionFee.'<br>';

} else {
    echo "Failed to get fees";
}

Generate Address's

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

Request

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


QUERY PARAMETERS

Parameter Type Description
address String The address you would like for payments to be forwarded to. This must be a valid Bitcoin address.
callback String 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.
tor Boolean Is the website url a tor website or a normal website on the clearnet? This is important for if you want us to send callback requests to your tor website.
setting String catch_instant (Catch only the payments the customer sends to the node to your callback url) | catch_forwarded (Catch only the forwarded payments from our node to your callback url)

The following block shows an example of the request URL:

https://blockchainapi.org//api/btc?method=create&address=3G7vZbcC7L74UsFz62Hr4NC9nVZNfh7tQ3&callback=https://example.com/callback?invoice=1&secret=ewfi9sdufjmds

Response (Success)

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

Response (Error)

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

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

"error": [{
    "The supplied address is not a valid Bitcoin address."
}]

Example Code

Below is a piece of example code written in PHP to generate addresses using our api:

# PHP Example To Generate Address
$secret = "7j0ap91o99cxj8k9";
$my_address = "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z";
$my_callback_url = "http://example.com/callback?invoice_id=1234&secret=" . $secret;
$api_base = "https://blockchainapi.org/api/btc";

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => $api_base . "?method=create&address=" . $my_address . "&callback=" . $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["success"]["input_address"];
    echo "The current estimated fee is: ".$decoded["success"]["estimated_transaction_fee"].' BTC';
} else {
    echo "Sorry, an error occurred: " . $response["error"];
}

Not sure what to do? Check here.

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. After this, everytime the confimrations value changes, we will send another callback, up to 20 confirmations or 20 bad callback requests.


Callbacks will always be sent as POST 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: POST

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

QUERY PARAMETERS

Parameter Type Description
value Float The amount of Bitcoin sent by the customer in BTC.
input_address String The Bitcoin address (generated by the API earlier) to which customer sent the payment.
confirmations Int The number of times the transaction has been confirmed at the time the callback is sent. This will always be 1.
transaction_hash String The hash of the transaction in which the payment was forwarded to your Bitcoin address.
input_transaction_hash String The hash of the customer's transaction sent to the generated address.
destination_address String The destination address (that you supplied when generating the address) to which the payment was forwarded.
timestamp Int The timestamp at which the payment was created.
result Boolean Was the payment a success or not?
miners_fee Float The fee taken by the miners
BlockchainAPIFee_BTC Float The fee taken by BlockchainAPI

The following block shows an example of the response from our API in JSON:

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

Expected Response

Callbacks will be marked as successful when our system returns a http status code of 200 in the response of the request to your callback url.

Example Code

// Payment Settings
$my_address = "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z";
$desiredConfirmations = 3;

// If you're using a secret, put it in here
$secret = "7j0ap91o99cxj8k9";

// Start of checks
if(!isset($_GET['secret'])) {
    die('No secret found.');
}

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

// Make sure we have all the POST variables we want to get
if(!$_POST['input_address'] || !$_POST['input_transaction_hash'] || !$_POST['transaction_hash'] || !$_POST['value'] || !$_POST['confirmations'] || !$_POST['destination_address']) {
    die('One of more of the POST variables was not set in the request to our callback url.');
}
    
if ($_POST["destination_address"] !== $my_address) die();

$input_address = $_POST["input_address"];
$input_transaction_hash = $_POST["input_transaction_hash"];
$transaction_hash = $_POST["transaction_hash"];
$value_in_btc = $_POST["value"];
$confirmations = $_POST["confirmations"];

// Confirmation check to make sure the confirmations is above our desired amount
if($confirmations >= $desiredConfirmations) {
    // We should store the payment as soon as we receive it inside this callback file
    // We can later update details such as confirms if needed
} else {
    // Transaction has not reached our desired number of confirmations.
    // Keep waiting for confirmations to be larger
}

The following PHP code will check that 3 confirmations have passed before adding the payment to the database.

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/btc?method=check_logs

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

QUERY PARAMETERS

Parameter Type Description
callback String The callback URL, urlencoded, 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.

The following block shows an example of the request URL (urlencoded):

https://blockchainapi.org//api/btc?method=check_logs&callback=http%3A%2F%2Fexample.com%2Fcallback%3Finvoice_id%3D1234

Response (Success)

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

Response (Error)

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

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

"error": [{
    "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.


[{
    "Choose a URL to request, fill out the parameter values, and hit "Send Request"!"
}]