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

Guide: V1

Getting Started

So you're probably here if you're not sure how to either setup our system or how to use our system, or... maybe even both! It's actually simpler than you may think.

We'll walk you through exactly how to setup our API so you can start accepting payments with your desired coding language and detect if payments are paid.

Step 1 Generating Addresses

First things first, of course you'll need an address to give to your customers so they can pay you. Currently, BlockchainAPI | Bitcoin Payment Processor | Bitcoin Payment Gateway only allows for Bitcoins to be transacted at the moment but in the future, we're looking to expand this to Ethereum, Bitcoin cash and a few others.

Guide image, looking at addresses inside the docs for BlockchainAPI | Bitcoin Payment Processor | Bitcoin Payment Gateway

As we can see from the picture above, taken from our docs, we'll need to use the method=create method of the endpoint to create a unique address for your users to pay to.

The fact that it's unique is very important! As it's unique, it means everyone has a different, newly generated address. This is essential for tracking specific users payments and to know when a payment has reached desired confirmations.

# 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/v1";

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

The PHP code above will use CURL to send a request to our method=create endpoint and will return a response depending on if the API successfully executed your inputs or whether it failed.

If the API returned a successful response, you'll be able to decode the JSON array returned by CURL, such as: <?php echo $decoded["success"]["input_address"] ?> in PHP.

If the API returned an error, the error will be contained inside a JSON error array such as: {"error":"The supplied Bitcoin address is not a valid Bitcoin address."}

When you create an address, you're required to enter the following variables inside the GET request:
- address (required)
- callback (required)
- tor (optional)
- setting [catch_instant | catch_forwarded] (Optional - Defaults to catch_instant)

Feel free to use our handy in-browser tool which will generate the correct PHP code to generate addresses to insert into your application.
It's really simple... even you can do it! Just enter your secret, Bitcoin address and callback url and hit generate code!

Step 2 Receiving Callbacks

Whenever a payment is made to your Bitcoin address that you generated above, you need to track whether the payment has been paid or not... whether it has reached the desired confirmations to be classed as paid.

Thanks to our hard-working development team, they've fully re-made our complete API system, including more features, better connections and easier user interface. This means the way callbacks are handled by you (the develoepr) is super easy!

Our system checks for all in-coming payments and forwards them to their correct output (the address you supplied above when creating an address to give to your users).
Our service fee is taken from the initial input transaction (from the user paying to your address) and then forwarded to your address (the developer).

You will receieve a callback on the first confirmation and after that, everytime the confirmations number in the response of the request to your callback url changes value.

We send data to your callback url inside a POST request.
This request contains the following variables:
- value
- input_address
- confirmations
- transaction_hash
- input_transaction_hash
- destination_address

// 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
}

Above, is an example of PHP code to detect if the payment has been made and found.

You can see that first, we add some security by making sure our secret matches the secret inside our callback url we used when creating an address to send to customers.

The only GET parameter should be the secret you chose. Everything else will be receieved as a POST request.

Once setting the security, we will make sure all the POST variables are found. If one or more of the POST variables are not found, we will kill the script there as the server didn't get the POST data from our API.

At this stage, we should now have the POST data from the API.
From here, you can dig into the variables such as: <?php echo $_POST["confirmations"]; ?>

The best way for the callback to handle this payment is to store this payment's details inside something like a database.

Then, if we ever need to (which we will if your project is a shop or similar), we can check the payment details at a later date.

In our example above, we will check for 3 confirmations before the payment is added inside our database.

Remember, our API will keep sending data to your callback url everytime its confirmations change in value upto 20 confirmations.

If your callback url does not return a 200 or 201 (successful) http status code, our system will count the bad callbacks sent and stop sending when it reaches 20 bad callbacks.

That's it!

We told you it's really simple, why didn't you believe us? 😊

You should now be able to: firstly, generate addresses to show to your customers. Secondly, handle the callbacks sent from our API.

This guide was last updated 23/02/2021 (4 weeks ago)