• UTC
  • :
  • :

BTCz/BTC: BTCz/USD: BTCz/EUR:

Getting started

This guide introduces you to the basics of using the API and its main feature. Find bellow the PHP example for creating a new gateway, fetch the information of it and to process the API pingback. For more details, visite the API section.

PHP Example

1) Using PHP's cURL module to create a new gateway

By using the bellow code, you will create a basic gateway that you can use in your online store.

// The func to create a new gateway
function CreateGateway($Amount, $CurrencyCode, $SuccessURL, $ErrorURL) {

  // This is the base API route
  $APIroute = "https://pay.btcz.app/api/request_payment/";

  // Set the pingback listens script
  $ipnPingback = $GLOBALS['MyStoreURL']."/utilities/btcz_pingback.php";

  // The seller (merchant) BTCz address
  $address = $GLOBALS['MerchantBTCzAddress'];

  // Set the API query string
  $queryURL = $APIroute."?expect=".$Amount."&currency=".$CurrencyCode."&ipnPingback=".urlencode($ipnPingback).""
              ."&cliSuccessURL=".urlencode($SuccessURL). "&cliErrorURL=".urlencode($ErrorURL)."&seller=".$address;

  // Init the cURL module
  $ch = curl_init();
  curl_setopt_array($ch, array(
      CURLOPT_URL => $queryURL,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array("cache-control: no-cache"),
  ));

  // Set some options
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERAGENT, "My store name ($GLOBALS['MerchantEmail'])");

  // Execute the query
  $result = curl_exec($ch);
  $info = curl_getinfo($ch);
  curl_close($ch);

  // Check the return code
  if($info['http_code'] != 200){return false;}

  // Return the result
  return $result;
}

// API call to create a new gateway
$APIresp = CreateGateway(13.56, "USD", $GLOBALS['MyStoreURL']."?paid=done", $GLOBALS['MyStoreURL']."?paid=error");

// Decode the json response
$JSON_RESP = json_decode($APIresp);

// Check the API response
if (!empty($JSON_RESP)) {

  // Check if error
  if (isset($JSON_RESP->error)) {
    echo "API error: ".$JSON_RESP->error;
  } else {

    // Else do somthing...
    // CAUTION: Never print_r the json result like this example in production !
    print_r($JSON_RESP);

    // Get the needed json informations
    $InvoiceURL = "https://pay.btcz.app/invoice/".$JSON_RESP->id;
    $Secret = $JSON_RESP->secret;
    $_SESSION[$InvoiceID] = $JSON_RESP->id;
  }

// If no answer from API, nomething is wrong...
} else {
  echo "No response from API";
}

The $JSON_RESP will be a json string like:

{
  "id":"c5e9631d-b107-4022-8de5-ae9f0efd03af",
  "secret":"7c3993319fdf14c5ac4510a0dd037a8dffad0a21",
  "address":"t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm",
  "link":"bitcoinz:t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm?amount=18556.54236&message=NA",
  "qr":"http://localhost:2222/generate_qr/bitcoinz%3At1gwku8spbCFUodyJ26njknnDxeZGM8hVmm%3Famount%3D14.77818972%26message%3DNA",
  "qr_simple":"http://localhost:2222/generate_qr/bitcoinz:t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm?amount=18556.54236"
}

You can use the invoice $InvoiceURL to include it as iframe in your onlide store. This invoice template will facilite the payment for the buyer:

<iframe id="iFrame" width="100%" frameborder="0" src="<%= $InvoiceURL %>" scrolling="no" onload="resizeIframe()"></iframe>

The $InvoiceURL URL is something like:

https://pay.btcz.app/invoice/c5e9631d-b107-4022-8de5-ae9f0efd03af

If something is wrong in your code, you will receive a error string in the json answer. Check also the error element:

  • If you don't set the all mandatory parameters:
    {"error":"Mandatory query param not set"}
  • If the amound for instant checkout is set higher than autorized:
    {"error":"To high amound for speed sweep"}
  • If you create more gateway as autorited:
    {"error":"To many gateway open"}
  • If you set a currency code that is not managed:
    {"error":"Bad currency"}
  • If a other error happen:
    {"error":"API error, please contact the pay.btcz.app admin"}

2) Using PHP's cURL module to fetching information from the created gateway

By using the bellow code, you will fetch the information from the created gateway.

// The func to fetch a gateway
function QueryGateway($gateway_id) {

  // This is the base API route
  $APIroute = "https://pay.btcz.app/api/check_payment/";

  // Init the cURL module
  $ch = curl_init();
  curl_setopt_array($ch, array(
    CURLOPT_URL => APIroute."/".$gateway_id,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array("cache-control: no-cache"),
  ));

  // Set some options
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERAGENT, "My store name ($GLOBALS['MerchantEmail'])");

  // Execute the query
  $result = curl_exec($ch);
  $info = curl_getinfo($ch);
  curl_close($ch);

  // Check the return code
  if($info['http_code'] != 200){return false;}

  // Return the result
  return $result;
}

// Check if variable with the invoice ID is set
if (isset($_SESSION[$InvoiceID])) {

  // API call to fetch a gateway
  $APIresp = QueryGateway($_SESSION[$InvoiceID]);

  // Decode the json response
  $JSON_RESP = json_decode($APIresp);

  // Check the API response
  if(!empty($JSON_RESP)) {

    // Check if error
    if (isset($JSON_RESP->error)) {
      echo "API error: ".$JSON_RESP->error;
    } else {

      // If gateway is paid
      if ($JSON_RESP->state == 5) {

        // Do something if gateway is paid...

      // If gateway is expired
      } else if ($JSON_RESP->state == 2) {

        // Do something if gateway is expired...

      }
    }

  } else {
    echo "No response from API";
  }

}

The $JSON_RESP will be a json string like:

{
  "generated":"t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm",
  "btcz_expected":18556.5423,
  "speed_sweep_fee":0,
  "btcz_actual":0,
  "btcz_unconfirmed":0,
  "currency":"USD",
  "amount":13.56,
  "timestamp_start":1537815608394,
  "timestamp_now":1537816142575,
  "timestamp_stop":1537816808394,
  "state":0,
  [optional] "tx": {
                    "tx":"TX Hex string",
                    "broadcast":{
                                  "result":"broadcast Hex string",
                                  "error":null,"id":"621680ed-ae85-4db3-bd84-58d5ed2edff8"
                                }
                   }
  [optional] "success_callback_url":"https://mysite_or_IP/result/?Hello=1",
  [optional] "err_callback_url":"https://mysite_or_IP/result/?Hello=0"
}

3) Using PHP's GET/POST module to process the API pingback

// Include DB managment script
require '../../utilities/db.inc.php';

// Check if somthing is sent
if(!isset($_POST["data"]))
    die();

// Get the sent param from the API pingback
$txn_id = $_GET['secret'];
$status = $_GET['state'];

// Check in the local DB if the secret phrase exist
$sql = $db->prepare("select count(*) from orders where txn_id = :txn_id");
$sql->execute(array(':txn_id' => $txn_id));
$status_count = $sql->fetchColumn(0);

// If the secrete phrase is correct (and exist)
if ($status_count >= 1) {

  // If gateway is expired
  if ($status == 2) {

    // Do something if gateway is expired...

  // If gateway is paid
  } else if ($status == 5) {

    // Do something if gateway is paid...

  }

} else {

  // Do something if the secret is false...
  return false;

}

arrow_upward