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.


The form version of our API allows you to easily insert a html form into your website with your specific values such as amount, currency, destination_address etc.

This method was created for users with less knowledge.

The form directs your customers to BlockchainAPI's checkout page where the customer will be shown the amount and address to send the funds to.


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.

Using The Form

We created this version of the API as it is much easier than writing your own code such as showing addresses and amounts to your customers.

You just insert the form code below on your checkout page, change the values to suite your desired values and the customer will be taken to BlockchainAPI's checkout screen where they will be asked to make the payment or return to the sellers website.


QUERY PARAMETERS

Parameter Type Description
AMOUNT String The amount in the chosen currency your product is.
TOR String Is your website on the TOR network or not? "true" or "false" as a string, NOT Boolean!
CURRENCY String The currency in which the amount set should be converted from into your selected crypto coin.
COIN String The crypto coin(s) you will allow the customer to pay with. (Seperated by comma) - e.g. BTC, LTC, ETH etc.
DESTINATION_ADDRESS String The destination address to which the funds should be forwarded once a payment is made.
PRODUCT_NAME String The name of the product you're selling.
CANCEL_URL String The url at which the customer will be redirect to if they hit cancel on BlockchainAPI's checkout page.
CALLBACK_URL String Your callback url to which you want to receive data sent by our system. (Needs to be unique for each payment).
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 code shows an example of the response body in the event of an error:

"error": [{
    "The coin you entered is not in our list of accepted coins. Please check our documentation for a list of accepted coins."
}]

Example Code

Below is a piece of example code written in HTML/PHP to create a form where users will be taken to a checkout page to complete their order:

# PHP Example To Generate Address Using HTML Form
$CANCEL_URL = 'https://blockchainapi.org//home.php';
$CALLBACK_URL = 'https://blockchainapi.org//callback.php';
$TOR = 'false';
$DESTINATION_ADDRESS = '3Hpu14TBY15Gy23GcCStoCuEETbuULXtnt';
$PRODUCT_NAME = 'Test Product';
$AMOUNT = 20;
$CURRENCY = 'GBP';
$COIN = 'BTC';
$SETTING = 'catch_instant';

<form method="POST" action="https://blockchainapi.org/index">
    <input type="hidden" name="AMOUNT" value="<?php echo $VALUE; ?>" />
    <input type="hidden" name="TOR" value="<?php echo $TOR; ?>" />
    <input type="hidden" name="CURRENCY" value="<?php echo $CURRENCY; ?>" />
    <input type="hidden" name="COIN" value="<?php echo $COIN; ?>" />
    <input type="hidden" name="DESTINATION_ADDRESS" value="<?php echo $DESTINATION_ADDRESS; ?>" />
    <input type="hidden" name="CALLBACK_URL" value="<?php echo urlencode($CALLBACK_URL); ?>" />
    <input type="hidden" name="PRODUCT_NAME" value="<?php echo $PRODUCT_NAME; ?>" />
    <input type="hidden" name="CANCEL_URL" value="<?php echo urlencode($CANCEL_URL); ?>" />
    <input type="hidden" name="SETTING" value="<?php echo $SETTING; ?>" />
    <button type="submit">Submit form</button>
</form>

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 BigInt 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.
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?

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": 50000,
        "input_address": "1E2VSRsaW3Kb1gDkdRUGDo6knAKfi9iYsb",
        "confirmations": 1,
        "transaction_hash": "1afb2eebe6ee69ab52da0a3ed98f5506c4ef00edcad852e98da346f42c568960",
        "input_transaction_hash": "02cb603c6066b22e23d6d998fbe7672776a098f93387fa86e362d18c9f496750",
        "destination_address": "1LisLsZd3bx8U1NYzpNHqpo8Q6UCXKMJ4z"
    }]
}]

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;

// MySQL Settings
$MYSQL_HOST = "localhost";
$MYSQL_NAME = "main";
$MYSQL_USER = "root";
$MYSQL_PASSWORD = "jsd8ue8rijewjru";

// 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"];
$value_in_satoshi = $value_in_btc * 100000000;

try {
    $conn = new PDO("mysql:host=$MYSQL_HOST;dbname=$MYSQL_NAME", "$MYSQL_USER", "$MYSQL_PASSWORD");
} catch (PDOException $e) {
    die($e->getMessage());
}

// 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
    $stmt = $conn->prepare("INSERT INTO payments (input_address, input_transaction_hash, transaction_hash, value) VALUES (:input_address, :input_transaction_hash, :transaction_hash, :value)");
    $stmt->execute(array("input_address" => $input_address, "input_transaction_hash" => $input_transaction_hash, "transaction_hash" => $transaction_hash, "value" => $value_in_satoshi));

    if ($stmt->rowCount()) {
        // Good, we have now inserted the payment into the database
        echo "Successfully inserted payment into database";
    } else {
        // Failed to insert payment into database
    }
} 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"!"
}]