What is BTCAPI?

Introduction

A Bitcoin payment processor 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 BTCAPI.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 "btcapi.org" and you'll be good to go.

What's so great about us?

Key features

Designed 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.

How to begin

Getting started

Four simple steps to accepting Bitcoin

Get a Bitcoin wallet, implement deposit address generation, handle payment callbacks, and you're good to go.

  • Get a Bitcoin wallet

    Our API requires that you have at least one Bitcoin address to which all payments will be forwarded. We will never ask for your private key, and you can keep it offline for increased security.

  • Implement address generation

    Implement a request to the create method of the receive endpoint to generate unique Bitcoin addresses to which your customers may send payments.

  • Implement callback handler

    Each time a payment is received and forwarded to your Bitcoin address, your callback URL will be sent data about the payment that you'll need to write some code to process.

  • Test the implementation

    Once you make a test payment and confirm everything is in working order, you're ready to accept payments in Bitcoin! Congratulations on all your hard work.

An overview

API structure

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/receivemethods related to receiving payments from customers
    • ?method=creategenerate a new deposit address to present to a customer
    • ?method=check_logscheck logs for payments with callbacks sent to a given callback URL
The most important endpoint

Generate addresses

The create method of the receive endpoint generates a unique Bitcoin payment address

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://btcapi.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:

https://btcapi.org/api/receive?method=create&address=1BRYmnsQnxRdi7e9J1592BChWvzSeuJdx6&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:

{
	"fee_percent": 1,
	"destination": "1BRYmnsQnxRdi7e9J1592BChWvzSeuJdx6",
	"input_address": "1LrNBzygeWFBuEsLTW528kXaVZjjhyhLt6",
	"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:

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:

$secret = "7j0ap91o99cxj8k9";
$my_address = "1BRYmnsQnxRdi7e9J1592BChWvzSeuJdx6";
$my_callback_url = "http://example.com/callback?invoice_id=1234&secret=" . $secret;
$api_base = "https://btcapi.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;
}
Last step in implementation

Receiving callbacks

Write 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: 199.188.204.234 (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:

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

Expected Response

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

*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:

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

$my_address = "1BRYmnsQnxRdi7e9J1592BChWvzSeuJdx6";
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*";
}
An additional feature

Check logs

The check_logs method of the receive endpoint returns payment logs for a given callback URL

Request

  • HTTP Method: GET
  • URL: https://btcapi.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:

https://btcapi.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:

{
    "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": "1LrNBzygeWFBuEsLTW528kXaVZjjhyhLt6",
        "confirmations": 1,
        "transaction_hash": "1afb2eebe6ee69ab52da0a3ed98f5506c4ef00edcad852e98da346f42c568960",
        "input_transaction_hash": "02cb603c6066b22e23d6d998fbe7672776a098f93387fa86e362d18c9f496750",
        "destination_address": "1BRYmnsQnxRdi7e9J1592BChWvzSeuJdx6"
    }]
}

Response (Error)

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

The supplied callback URL has never been sent any callbacks/notifications.
Debug your implementation

Test endpoints

Demo all of our API below using our handy in-browser testing client

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

FAQ

The most common questions about BTCAPI

We want to make your experience with BTCAPI as easy as possible. If there's anything you don't understand, try looking for answers here. 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 BTCAPI do?

    BTCAPI 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 BTCAPI 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.