GoUrl.io Bitcoin/Altcoin API

  • bitcoin payment api
  • bitcoin cash payment api
  • bitcoin sv payment api
  • litecoin payment api
  • dash payment api
  • dogecoin payment api
  • speedcoin payment api
  • reddcoin payment api
  • potcoin payment api
  • feathercoin payment api
  • vertcoin payment api
  • peercoin payment api

Welcome Developers!

Here you will find everything you need to get started coding for bitcoin/altcoin - PHP, JSON, ASP, Python, Java, C#, Node.js, etc.



API for PHP Websites


Please use our official free PHP Bitcoin/Altcoin Payment Class -

 PHP Examples »    PHP Instruction »    Download from Github




API for Wordpress Plugins/Themes


You can easily integrate crypto payments to your own wordpress plugin using our official Wordpress Bitcoin Gateway Plugin -

  WP Instructions for Plugins »      WP Instructions for Themes »





API for Other Languages (ASP, Python, Java, C#, etc)


Please use general instructions below to add bitcoin/altcoin payments to scripts/websites -

  API Instructions Below      ASP.NET C#      Python's Django / Flask





Affiliate Program for Web Developers


33.3% lifetime revenue share - 0.50% from each bitcoin/altcoin payment made by users through your scripts with GoUrl Bitcoin/Altcoin Payment Gateway installed on various websites -

  Read more







Developer's Guide


Simple instructions on how to integrate GoUrl Payment Gateway to your scripts/website (ASP, Python, Java, C#, Node.js, etc).

If you use PHP language, please goto here, for other languages - read below.

Cryptocoin Payment Box and Crypto Captcha ("CRYPTOBOX") are very easy to use ! They are identical technically except their visual effect and will automatically display successful message if payment has been received. Default box size: 530 x 230 px






API Instruction - Python, ASP, Java, C#, Node.js...



For Python's Django/Flask Bitcoin Payment Gateway example click here »

For PHP API Class click here »

For Laravel Class click here »

For payments in JSON format click here »

For ASP.NET API Plugin click here »

Testing environment (free speedcoins) click here »

GoUrl Bitcoin/Altcoin Gateway operates as follows -


bitcoin api



GoUrl Payment Integrations. Please do the following steps -

  1. Register or Login on our website
  2. Create new bitcoin/altcoin payment box (you will get Public and Private keys of new created box)

  3. Step A -

    You have three choices to display crypto payment box/data on your webpage/applications -

    3.1 IFRAME - Create html empty iframe element on your webpage and call javascript function cryptobox_show(..), function description below. It will generate iframe html bitcoin/altcoin payment box on webpage. Example

    3.2 JSON Server Side - Alternatively, you can receive JSON values through curl on server side - function get_json_values() and use it in your application without javascript and iframe (code).

    3.3 JSON Client Side - Or You can use JQuery script with JSON values - Client side. Read here

  4. Step B - When a user has paid, our server will automatically send full payment data (userID, orderID, amount, etc) to your website on url specified in field Callback URL

  5. Then your website can process that data (for example, update user membership, etc.)
Also see full presentation how gateway works ( from buyer and seller sides ).





A. Javascript function cryptobox_show(..)



Please download javascript file from here.

Javascript function cryptobox_show (boxID, coinName, public_key, amount, amountUSD, period, language, iframeID, userID, userFormat, orderID, cookieName, webdev_key, hash, width, height) - generate a html iframe with a bitcoin/altcoin payment box on your webpage

Function cryptobox_show() Parameters -

  • boxID
    Cryptocoin Payment BoxID from your new payment box. Example
  • coinName
    Crypotcoin name from your new payment box. Example
  • public_key
    Crypotcoin Payment Box Public Key from your new payment box. Example
  • amount
    Amount of cryptocoins which will be used in the payment box, precision is 4 (number of digits after the decimal), example: 0.0001, 2.444, 100, 2455, etc. We will use this value of cryptocoins in the payment box with a small fraction after the decimal point to uniquely identify each of your visitors individually - (for example, if you enter 0.011 BTC, one of your user will see 0.011308 BTC, and another will see 0.011832 BTC, etc). How It Works
  • amountUSD
    You can directly specify your price in USD (float values allowed) and cryptobox will automatically convert that USD amount to cryptocoin amount using today live cryptocurrency exchange rates (updated every 30min). For example, if you select BITCOIN currency and amountUSD = 14.6 USD - we will convert it to bitcoins and it will be 0.063 BTC. We will display it in crypto payment box for payment by the user.
    User will pay you all times the actual price which is linked on current exchange price in USD on the datetime of purchase. Also you can use Poloniex.com, Bitstamp.net, etc autosell feature and auto trade your cryptocoins to USD/BTC after payment received. Using that functionality (price in USD), you don't need to worry if cryptocurrency prices go down or go up. You can use in cryptobox options one variable only: amount or amountUSD. You cannot place values of those two variables together.
  • period
    Period after which the payment becomes obsolete and new Cryptocoin Payment Box will be shown (you can use it to take new payments from existing users periodically on a daily/monthly basis). Allow values: NOEXPIRY, 1 MINUTE - 90 MINUTE, 1 HOUR - 90 HOURS, 1 DAY - 90 DAYS, 1 WEEK - 90 WEEKS, 1 MONTH - 90 MONTHS
  • language
    Cryptobox localisation. Languages currently available for GoUrl Payment Box: en - English, es - Spanish, fr - French, de - German, nl - Dutch, it - Italian, ru - Russian, pl - Polish, pt - Portuguese, fa - Persian, ko - Korean, ja - Japanese, id - Indonesian, tr - Turkish, ar - Arabic, cn - Simplified Chinese, zh - Traditional Chinese, hi - Hindi. We can add your language localisation in the cryptocoin payment box (all texts can be displayed in your local language). To do this please first download this language file with the text in English. At the end of each line, please add your translation from English and send this text file with your translation back to us on email and we will include your translation.
  • iframeID
    Html iframe cryptobox element id; allow symbols: a..Z0..9. See example below
  • userID
    A unique identifier for each of your users; allow symbols: a..Z0..9_-@.; max size: 50 symbols. Examples: 'user1', 'user2', '3vIh9MjEis'
  • userFormat
    Please use value 'MANUAL' all time. Other values available for PHP websites only.
  • orderID
    Your order id; allow symbols: a..Z0..9_-@.; max size: 50 symbols. Examples: 'order3332', 'product123
    A few of your users can have the same orderID but combination 'orderID'+'userID' should be unique. For example, on premium page you can use for all users: orderID="premium_access" and userID - user1, user2, etc
  • cookieName
    Please use empty value '' all time. Other values available for PHP websites only.
  • webdev_key
    Optional, your gourl affiliate key or leave empty value.
  • hash
    Security md5 all values hash. You should generate it on your server and place value in script; it protects payment box iframe parameters / json output from changes by end user in web browser. HASH value generate as - php code.
    Also we can activate debug mode for your bitcoin/altcoin payment box (show md5 hash calculation) - Contact us
    OR you can use demo box with debug mode activated already for tests
  • width
    Iframe html payment box width in pixels. Integer values. Default: 530
  • height
    Iframe html payment box height in pixels. Integer values. Default: 230

Notes: if you use the same public_key, orderID and userID in your multiple cryptocoin payment boxes on different your website pages and a user has made payment; a successful result for that user will be returned on all those pages (of course if period time not expired).


HTML Iframe Payment Box Example with cryptobox.js -

<html>
<head>
	<script src="cryptobox.js" type="text/javascript"></script>
</head>
<body>
	<div align="center" style="min-width:530px">
		<iframe id="box1913" style="border-radius:15px;border:1px solid #eee;padding:3px 6px;margin:10px;" scrolling="no" marginheight="0" marginwidth="0" frameborder="0" width="530" height="230"></iframe>
	</div>
	<script type="text/javascript"> <!-- Amount $5.50 -->
		cryptobox_show(1514, 'bitcoin', '1514AAf8QICBitcoin77BTCPUB7XBxPbmc4uK79CCWHEB5DAmY', 0, 5.5, '60 MINUTE', 'en', 'box1913', 'user4', 'MANUAL', 'product1', '', '', 'f2cea21af212b8a60a1620bc46ea8f79', 530, 230);
	</script>
</body>
</html>


or see alternative JSON/JQuery custom bitcoin payment box »




Result -







B. Instant Payment Notification/Callback


  • When a user has made a payment, our server will send payment data using HTTP POST method on your callback url specified in field Callback URL of your crypto payment box.
    Also as IPN backup (if your IPN url not configured/not response), user see on bottom of payment box button 'Click Here if you have already sent coins' and when he will click on that button, script will connect to our Gourl Gateway Server and check user payment status (receive copy of IPN data).
  • Your script, should check whether the payment box private key hash received in POST["private_key_hash"] is correct, POST["private_key_hash"] = hash("sha512", your_gourl_private_key). It will guarantee that payment data are valid and sent from our server.
  • You should publish result text on your callback webpage. Allow text - "Only POST Data Allowed", "cryptobox_newrecord", "cryptobox_updated", "cryptobox_nochanges"; it use for synchronise data store on our server with data on your website. No other text output on callback webpage! Example below.

-> Send DUMMY Test Payment Data to your website »

See examples of JSON DATA here »


Example of Your Callback Webpage -


Example in PHP. Simple convert that code to your own website language (ASP, Python, C#, etc). See full php version of script below here

<?
	$html = "";
	if (isset($_POST["status"]) && in_array($_POST["status"], array("payment_received", "payment_received_unrecognised")) &&
		$_POST["box"] && $_POST["box"] > 0 && $_POST["amount"] && $_POST["amount"] > 0 &&
		strtolower($_POST["private_key_hash"]) == strtolower(hash("sha512", "..place-here-your-gourl-box-private-key..")))
		{
			// check if new payment; sql example
			$obj = run_sql("select paymentID, txConfirmed from my_payments where boxID = ".intval($_POST["box"])." && 
							orderID = '".addslashes($_POST["order"])."' && userID = '".addslashes($_POST["user"])."' && 
							txID = '".addslashes($_POST["tx"])."' limit 1"); 
			$paymentID		= ($obj) ? $obj->paymentID : 0;
			$txConfirmed	= ($obj) ? $obj->txConfirmed : 0; 
			
			// Save new payment details in your database
			if (!$paymentID)
			{
				// your code here; for example update user membership
				$html = "cryptobox_newrecord"; // don't change text; it use by gourl.io server
			}
			// Update record; payment confirmed
			elseif ($_POST["confirmed"] && !$txConfirmed)
			{
				// your code here
				$html = "cryptobox_updated"; // don't change text
			}
			else 
			{
				// your code here
				$html = "cryptobox_nochanges"; // don't change text
			}
		}
	else
		$html = "Only POST Data Allowed"; // don't change text
		
	echo $html;	
?>



$_POST DATA which will receive your website callback url


For example, your user with userID = user26 bought product with orderID = order15620A. Product price was 11.5 USD and user paid in Bitcoins.

If payment received with correct amount, function receive status = 'payment_received'. If incorrectly paid amount, the system can not recognize user; status = 'payment_received_unrecognised'

Your callback url receive POST data -
'user' - user who has made payment, 'order' current order ID,
'amount' = 0.0479166 BTC paid by User (~11.5 USD),
private_key_hash - your private key for validation that data has been sent from Gourl.io; calculated as hash("sha512", your_gourl_private_key)
etc.

		
		I. IPN POST DATA (correct amount)
		{
			"status":"payment_received"
			"err":""
			"private_key_hash":"d91921eef5d136d5cd22bd5210b4494d417...." // hash("sha512", your_gourl_private_key)
			"box":"120"
			"boxtype":"paymentbox"
			"order":"order15620A"
			"user":"user26"
			"userformat":"MANUAL"
			"usercountry":"USA"
			"period":"NOEXPIRY"
			"amount":"0.00124166"
			"amountusd":"11.5"
			"coinlabel":"BTC"
			"coinname":"bitcoin"
			"addr":"14dt2cSbvwghDcETJDuvFGHe5bCsNPR8jW"
			"tx":"95ed924c215f2945e75acfb5650e28387deac382c9629cf0d3f31d0ec23db09d"
			"confirmed":0
			"timestamp":"1422624765"
			"date":"30 January 2015"
			"datetime":"2015-01-30 13:32:45"
		}
		 




Or if User Has Made INCORRECT Payment (wrong amount) -


We use amount value of cryptocoins in the payment box with a small fraction after the decimal point to uniquely identify each of your users individually. If user pay wrong amount on your internal wallet address, GoUrl Gateway cannot identify that user. You need to process all unrecognised payments manually. We forward you ALL coins received on your internal wallet address/es including all payments with incorrect amounts (unrecognised payments).

In example below, user paid wrong/incorrect amount in 0.0016 BTC to you -


		II. IPN POST DATA (wrong amount)
		{
			"status":"payment_received_unrecognised"
			"err":"An incorrect bitcoin amount has been received"
			"private_key_hash":"d91921eef5d136d5cd22bd5210b4494d417...." // hash("sha512", your_gourl_private_key)
			"box":"120"
			"boxtype":"paymentbox"
			"order":""
			"user":""
			"userformat":""
			"usercountry":""
			"period":""
			"amount":"0.0016"
			"amountusd":"15.26"
			"coinlabel":"BTC"
			"coinname":"bitcoin"
			"addr":"14dt4cSbvwghDcETJDuvFGHe5bCsCPR1jW"
			"tx":"6f1c6f34189a27446d18e25b9c79db90be55b0bb775b1768b5aa4520f23d71a8"
			"confirmed":0
			"timestamp":"1422623712"
			"date":"30 January 2015"
			"datetime":"2015-01-30 13:15:12"
		}
		 



POST Fields Description -


  • status - 'payment_received' (payment received with correct amount) or 'payment_received_unrecognised'
  • err - optional, error description
  • private_key_hash - your private key hash for validation that data has been sent from Gourl.io; calculated as hash("sha512", your_gourl_private_key)
  • box - your cryptobox id, the same as on gourl.io member page
  • boxtype - 'paymentbox' or 'captchabox'
  • order - your order id
  • user - identifier for every user
  • usercountry - your user's location (country), 3 letter ISO country code
  • amount - paid cryptocurrency amount
  • amountusd - approximate paid amount in USD with exchange rate on datetime of payment made
  • coinlabel - cryptocurrency label
  • coinname - cryptocurrency name
  • addr - your internal wallet address on gourl.io which received this payment
  • tx - transaction id
  • confirmed - 0 - unconfirmed transaction/payment or 1 - confirmed transaction/payment with 6+ confirmations
  • timestamp - transaction timestamp (GMT time)
  • date - transaction date (GMT time)
  • datetime - transaction datetime (GMT time)

NOTE: If user paid wrong amount, fields "order", "user", "userformat", "usercountry", "period" will be empty. Read here




Usually your callback url will automatically appear for each new payment two times :

  • a) when a new payment is received and unconfirmed yet, values: POST[confirmed] = 0, etc.
  • b) and a second time when existing payment is confirmed (6+ confirmations) with values: POST[confirmed] = 1, etc. All other values are the same.

But sometimes if the payment notification is delayed for 20-30min (for example, your site was unavailable and GoUrl Gateway auto re-send data later), the payment/transaction will already be confirmed and the function will appear once with values: POST[confirmed] = 1, etc.







Testing Environment


Alternatively you can use Dogecoins for testing, create dogecoin payment box.
The minimum account balance on GoUrl.io which our system will automatically transfer from your GoUrl internal wallet address to your external wallet address is 0.01 BTC for Bitcoin, 5 coins for Speedcoin and Dogecoin, etc

Additional actions after a payment has been received (update database records, send email to user, etc). Read here


Send DUMMY Test Payment Data to your website »


Instant Payment Notification/Callback JSON Data (examples) -



Extended JSON Data for website (examples) -





Speedcoin Demo Box (debug mode activated already) -


Please use it for test your generated MD5 HASH values

  • Correct MD5 Hash - live demo
  • Incorrect MD5 Hash - live demo
  • Speedcoin Demo Box ID: 20116
  • Public Key: 20116AA36hi8Speedcoin77SPDPUBjTMX31yIra1IBRssY7yFy
  • Private Key: 20116AA36hi8Speedcoin77SPDPRVNOwjzYNqVn4Sn5XOwMI2c









CONTACT US


We offer Free Support in the integration of our GoUrl Crypto Payment Gateway in your scripts/plugins/website.

Please feel free to contact us if you have any questions

Contact Us











March 2024
Back to Top