GoUrl.io Bitcoin/Altcoin - PHP API

  • bitcoin payment api
  • litecoin payment api
  • dogecoin payment api
  • dash payment api
  • speedcoin payment api
  • reddcoin payment api
  • potcoin payment api
  • feathercoin payment api
  • monetaryunit payment api
  • vericoin payment api
  • paycoin payment api
  • peercoin payment api
  • swiscoin payment api

PHP Class API


Here you will find everything you need to get started coding for bitcoin/altcoin on PHP.


If you use ASP, Python, Java, Wordpress, C#, Node.js, etc. please go to HERE »




Start Now

Note: If you want to integrate Bitcoin/altcoin payments in your Wordpress Plugin, please use our other wordpress instructions »




I. Payment Box Installation -


  • Register for Free or Login on the website and create new payment box
  • Download Free PHP Payment API Class/Script and read How It Works
  • Edit file cryptobox_config.php, add your db details and your private key (screenshot)
  • Run SQL query in your database to create new table crypto_payments
  • When you setup Cryptocoin Payment Box, you can enter the original amount in USD or in cryptocoins. The USD amount will be automatically converted to cryptocoin amount using today's LIVE cryptocurrency exchange rates (updated every 30 minutes) and the cryptocoin amount will be displayed.
  • For example, if you entered 20 USD, it will display 0.059 BTC in the payment box.
  • Place your public/private keys from the new payment box in any example
  • You can use this example (screenshot) and run it

THAT'S IT! CRYPTOCOIN PAYMENT BOX SHOULD NOW BE WORKING ON YOUR SITE




 Download PHP Class       100% Free Open Source on Github »







II. PHP Developer's Guide



Crypto Payment box configuration


Every instance of a Cryptobox Class can have different set of instance configuration variables (example). It use in $box1 = new Cryptobox ($options);   see below -


<?
	// Remove all the characters from the string other than a..Z0..9_-@. 
	$orderID = preg_replace('/[^A-Za-z0-9\.\_\-\@]/', '', $orderID);
	$userID = preg_replace('/[^A-Za-z0-9\.\_\-\@]/', '', $userID);

	// All Default Configuration variables
	$options = array( 
			"public_key"  => "",
			"private_key" => "",
			"orderID"     => $orderID, 
			"userID"	  => $userID,	// optional
			"userFormat"  => "COOKIE", 	// SESSION, IPADDRESS
			"amount"      => 0,
			"amountUSD"   => 0,
			"period"      => "",	// 2 HOUR, 1 DAY, 1 MONTH, NOEXPIRY, etc..
			"iframeID"    => "",	// optional
			"language"    => "EN"	
	);  

	// Initialise Payment Class
	$box1 = new Cryptobox ($options);
	... ...
?>

  • public_key
    Crypotcoin Payment Box Public Key from your new payment box. Example
  • private_key
    Crypotcoin Payment Box Private Key from your new payment box. Example
  • orderID
    Your order id or product name; allow symbols: a..Z0..9_-@.; max size: 50 symbols, examples: 'order44', 'premium_page', 'product123
    Some 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 visitors: orderID="premium" and userID="" (empty; therefore system will automatically generate unique userID).
  • userID
    Optional, manual setup unique identifier each of your users. By default the Payment Box uses randomly generated string in userID and saves it in user cookies.
    You need to use a variable userID when you use Cryptocoin Payment Box for registered users on your website. You don't need to use userID if using Cryptobox for unregistered website visitors (for example, on website sign-up form).
    IMPORTANT:
    If you use Payment Box for registered users on your website, you need to set userID manually with a unique value for each of your registered user. It is better than to use cookies by default. Examples: 'user1', 'user2', '3vIh9MjEis'
    allow symbols: a..Z0..9_-@.; max size: 50 symbols
  • userFormat
    System uses variable userFormat only if userID above is empty - it will save random auto-generated userID in cookies, sessions or use user IP address as userID.
    Default: COOKIE. Available values: COOKIE, SESSION, IPADDRESS, *MANUAL.
    *If userID above is not empty, use userFormat=MANUAL.
  • amount
    Amount of cryptocoins which will be used in the payment box/captcha, 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).
  • 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 LITECOIN currency and amountUSD = 4.2 USD - we will convert it to litecoins and it will be 0.86 LTC. 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. For convert fiat currencies Euro/GBP/etc. to USD, use function convert_currency_live()
  • 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 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
  • iframeID
    Optional, html iframe cryptobox element id; when iframeID value is empty - system will autogenerate iframe id. Allow symbols: a..Z0..9
  • 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.

Notes -


cryptocoin payment

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

If you change - public_key or orderID or userID - new cryptocoin payment box will be shown for existing paid user
(function $this->is_paid() starts to return 'false').

We store all your users successful payment results on our server and you have a copy of these results in your local database, mysql table crypto_payments with GMT time.


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

  • By Using html Iframe bitcoin payment box - example »
  • By using JSON data Client Side. It will allow you to easily customise your bitcoin payment box. Javascript & JQuery instruction here »
  • 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 »

JSON Examples -     Payment Not Received    Payment Received    jQuery & JSON Box Example    jQuery Result Example







III. PHP Class Cryptobox - List of Methods


Cryptocurrency Payment Class (file cryptobox.class.php) have following public methods -

  1. function display_cryptobox($submit_btn = true, $width = "530", $height = "230", $box_style = "", $message_style = "", $anchor = "")
    Display Cryptocoin Payment Box; the cryptobox will automatically display successful message if payment has been received. Usually user will see on bottom of payment box button 'Click Here if you have already sent coins' (option: $submit_btn = true) and when user click on that button, script will connect to our remote cryptocoin payment box server and check user payment.
    As backup, our server will also inform your server automatically through IPN every time a payment is received (file cryptobox.callback.php). I.e. if the user does not click on the button or you have not displayed the button, your website will receive a notification about a given user anyway and save it to your database. Next time your user goes to your website/reloads page they will automatically see the message that their payment has been received successfully. $style/$css - cryptobox html style/class. For big QR code size, please use $width >= 565px
  2. function cryptobox_json_url()
    It generates url with your paramenters to gourl.io payment gateway. Using this url you can get bitcoin/altcoin payment box values in JSON format and use it on html page with Jquery/Ajax - js function cryptobox_custom(..).
    See instruction instruction here.
    JSON Examples: Payment not received and Payment received successfully

    Alternatively, you can receive JSON values through php curl on server side - function get_json_values() and use it in your php/other files without using javascript and jquery/ajax.

    By default the user sees bitcoin payment box as iframe in html format - function display_cryptobox(). JSON data will allow you to easily customise your bitcoin payment boxes. For example, you can display payment amount and bitcoin payment address with your own text, you can also accept payments in android/windows and other applications. You get an array of values - payment amount, bitcoin address, text; and can place them in any position on your webpage/application.
  3. function get_json_values()
    Alternatively, you can receive JSON values through php curl on server side and use it in your php/other files without using javascript and jquery/ajax.
    Function return Array; Examples: Payment not received and Payment received successfully

    By default the user sees bitcoin payment box as iframe in html format - function display_cryptobox(). JSON data will allow you to easily customise your bitcoin payment boxes. For example, you can display payment amount and bitcoin payment address with your own text, you can also accept payments in android/windows and other applications. You get an array of values - payment amount, bitcoin address, text; and can place them in any position on your webpage/application.
  4. function cryptobox_hash($json = false, $width = 0, $height = 0)
    It generates security md5 hash for all values used in payment boxes.
    This protects payment box parameters from changes by end user in web browser.
    Parameters - $json = true - generate md5 hash for json payment data output or generate hash for iframe html box with sizes $width x $height
  5. function is_paid($remotedb = false)
    Checks your local database whether payment has been received and is stored on your local database.
    If use $remotedb = true, it will check also on our cryptocoin payment server (gourl.io), and if payment is received, it saves it in your local database. Usually user will see on bottom of payment box button 'Click Here if you have already sent coins' and when they click on that button, script it will connect to our remote cryptocoin payment box server. Therefore you don't need to use $remotedb = true, it will make your webpage load slowly if payment on gourl.io is checked during each of your page loadings.
  6. function is_confirmed()
    Function return is true if transaction/payment has 6+ confirmations. It connects with our payment server and gets the current transaction status (confirmed/unconfirmed). Some merchants wait until this transaction has been confirmed. Average transaction confirmation time - 10-20min for 6+ confirmations (altcoins)
  7. function amount_paid()
    Returns the amount of coins received from the user. Float value.
  8. function amount_paid_usd()
    Returns the approximate amount in USD received from the user using live cryptocurrency exchange rates on the datetime of payment. Live Exchange Rates obtained from sites bitstamp.net, poloniex.com and blockchain.info and are updated every 30 minutes!
  9. function set_status_processed()
    You can use this function when user payment has been received (function is_paid() returns true) and want to make one time action, for example display 'thank you' message to user, etc. This function helps you to exclude duplicate processing. Call set_status_processed() and after check status with function is_processed().
    Please note that the user will continue to see a successful payment result in their crypto Payment box during the period/timeframe you specify in cryptobox option $period
  10. function is_processed()
    If payment status in database is 'processed' - return true, otherwise return false. You need to use it with function set_status_processed() together.
  11. function cryptobox_type()
    Returns 'paymentbox' or 'captchabox'
    The Cryptocoin Payment Box and Crypto Captcha are absolutely identical technically except for their visual effect. It uses the same code to get your user payment, to process that payment and to forward received coins to you. They have only two visual differences - users will see different logos and different text on successful result page. For example, for bitcoin it will be - 'Bitcoin Payment' or 'Bitcoin Captcha' logos and when payment is received we will publish 'Payment received successfully' or 'Captcha Passed successfully'.
    We have made it easier for you to adapt our payment system to your website. On signup page you can use 'Bitcoin Captcha' and on sell products page - 'Bitcoin Payment'.
  12. function payment_id()
    Returns current record id from your mysql table crypto_payments. This table stores all payments from your users.
  13. function payment_date()
    Returns payment/transaction datetime in GMT format.
    Example - 2014-09-26 17:31:58 (is 26 September 2014, 5:31pm GMT)
  14. function payment_info()
    Returns object with current user payment details -
    * coinLabel - cryptocurrency label
    * countryID - user location country, 3 letter ISO country code
    * countryName - user location country
    * amount - paid cryptocurrency amount
    * amountUSD - approximate paid amount in USD on datetime of payment made
    * addr - your internal wallet address on gourl.io which received this payment
    * txID - transaction id
    * txDate - transaction date (GMT time)
    * txConfirmed - 0 - unconfirmed transaction or 1 - confirmed with 6+ confirmations
    * processed - true/false. True if you called function set_status_processed() before
    * processedDate - GMT time when you called function set_status_processed()
    * recordCreated - GMT time a payment record was created in your database
  15. function cryptobox_reset()
    Optional, it will delete cookies/sessions with userID and new cryptobox with new payment amount will be displayed after page reload. Cryptobox will recognize user as a new one with new generated userID. For example, after you have successfully received the cryptocoin payment and had processed it, you can call one-time cryptobox_reset() in end of your script. Use this function only if you have not set userID manually.
  16. function coin_name()
    Returns coin name (bitcoin, litecoin, dogecoin, etc)
  17. function coin_label()
    Returns coin label (BTC, LTC, DOGE, etc)
  18. function iframe_id()
    Returns payment box frame id


Common Functions

  1. function payment_history($boxID = "", $orderID = "", $userID = "", $countryID = "", $boxType = "", $period = "7 DAY")

    Returns array with history payment details of any of your users / orders / etc. from table crypto_payments (except unrecognised payments) for custom period - $period. You will have a copy of the statistics on member page

    It includes -
    * paymentID - current record id in the table crypto_payments.
    * boxID - your cryptobox id, the same as on gourl.io member page
    * boxType - 'paymentbox' or 'captchabox'
    * orderID - your order id / page name / etc.
    * userID - identifier for every user
    * countryID - your user's location (country)
    * coinLabel - cryptocurrency label
    * amount - paid cryptocurrency amount
    * amountUSD - approximate paid amount in USD with exchange rate on datetime of payment made
    * addr - your internal wallet address on gourl.io which received this payment
    * txID - transaction id
    * txDate - transaction date (GMT time)
    * txConfirmed - 0 - unconfirmed transaction or 1 - confirmed with 6+ confirmations
    also you can use function is_confirmed() above, it will connect with our payment server and get transaction status (confirmed/unconfirmed)
    * processed - true/false. True if you called function set_status_processed() before
    * processedDate - GMT time when you called function set_status_processed()
    * recordCreated - GMT time a payment record was created in your database


  2. function payment_unrecognised($boxID = "", $period = "7 DAY")

    Returns array with unrecognised payments for custom period - $period. (users paid wrong amount to your internal wallet address). You will need to process unrecognised payments manually.

    We forward you ALL coins received to your internal wallet address including all possible incorrect amount/unrecognised payments automatically every 30 minutes. Therefore you need to deal with your user directly to resolve the situation or return that incorrect payment back to your user. You will have a copy of the statistics on your member page with details of incorrect received payments. You have copy of that statistics on your member page with details of incorrect received payments.

    It includes -
    * paymentID - current record id in the table crypto_payments.
    * boxID - your cryptobox id, the same as on gourl.io member page
    * boxType - 'paymentbox' or 'captchabox'
    * coinLabel - cryptocurrency label
    * amount - paid cryptocurrency amount
    * amountUSD - approximate paid amount in USD on datetime of payment made
    * addr - your internal wallet address on gourl.io which received this payment
    * txID - transaction id
    * txDate - transaction date (GMT time)
    * recordCreated - GMT time a payment record was created in your database


  3. function cryptobox_sellanguage($default = "en")
    Get cryptobox current selected language by user (english, spanish, etc)

  4. function cryptobox_selcoin($coins = array(), $defCoin = "")
    Get cryptobox current selected coin by user (bitcoin, dogecoin, etc. - for multiple coin payment boxes)

  5. function display_language_box($default = "en", $anchor = "gourlcryptolang", $select_list = true)
    Language selection dropdown list for cryptocoin payment box
    $select_list = true - use <SELECT> tag for dropdown list, <UL> tag for dropdown list (using in bootstrap)


  6. function display_currency_box($coins = array(), $defCoin = "", $defLang = "en", $iconWidth = 50, $style = "width:350px; margin: 10px 0 10px 320px", $directory = "images", $anchor = "gourlcryptocoins")
    Multiple crypto currency selection list. You can accept payments in multiple crypto currencies. For example you can setup product price in USD and accept payments in bitcoin, litecoin, dogecoin.


  7. function get_country_name($countryID, $reverse = false)
    Get country name by country code (i.e. CAN => Canada, FRA => France, etc)

  8. function convert_currency_live($from_Currency, $to_Currency, $amount)
    Fiat Currency Converter using Google Finance live exchange rates.
    Examples - convert_currency_live("EUR", "USD", 22.30) - convert €22.30 => $25.17
              convert_currency_live("EUR", "BTC", 22.30) - convert €22.30 => 0.0334 BTC

  9. function validate_gourlkey($key, $type)
    Validate gourl private/public/affiliate keys. It includes -
    * key - gourl payment box key
    * type - type of key, available values: public, private, affiliate
    If key valid, return true otherwise return false

  10. function run_sql($sql)
    Run SQL queries and return result in array/object formats





IV. PHP - 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.
  • Please use php file cryptobox.callback.php as your callback url (https://www.example.com/cryptobox.callback.php). As 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).
  • You can use additional actions after a payment has been received (update database records, send email to user, etc).
    Simply edit function with the name - cryptobox_new_payment($paymentID, $payment_details, $box_status) in your php file cryptobox.newpayment.php. It is a IPN function. This function is used every time a new payment from any user is received successfully. Function receives paymentID - current payment ID (record id in your mysql table crypto_payments), payment details as array and box_status - 'cryptobox_newrecord' OR 'cryptobox_updated'.
  • Please note, all received payments store in your mysql table `crypto_payments` also.
    To retrieve data from this table, you can use standard functions - payment_history(..) and payment_unrecognised(..)




Cloudflare & Mod_Security & other CDN services -




cryptocoin payment

If you use Cloudflare & Mod_Security & other CDN services, please add our server IPs in Whitelist !
Our Server IPs:   51.255.140.174 & 51.254.199.21   and IPv6:   2001:41d0:1008:b15:b174::1 & 2001:41d0:1008:b15:b21::1

Instruction for Cloudflare - screenshot and source (6. Allow the IPs of the services you use to access your website).
Instruction for Mod_Security - http://serversitters.com/mod-security-whitelist-ip.html.





IPN Example -


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'


A. User Has Made Correct Payment -


Your callback url & function cryptobox_new_payment(...) (file cryptobox.newpayment.php) receive 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 hash / calculated as hash("sha512", your_gourl_private_key) for validation that data has been sent from Gourl Gateway Server
etc.

<?   
	function cryptobox_new_payment($paymentID, $payment_details, $box_status)
	{
		// IPN Function will receive -  
		$paymentID = 1; // record id in your table crypto_payments 
		$payment_details = Array
		{
			"status":"payment_received"
			"err":""
			"private_key_hash":"d91921eef5d136d5cd22bd5210b4494d417...." // hash("sha512", your_gourl_private_key)
			"box":"120"
			"boxtype":"paymentbox"
			"order":"order15620A"
			"user":"user26"
			"usercountry":"USA"
			"amount":"0.0479166"
			"amountusd":"11.5"
			"coinlabel":"BTC"
			"coinname":"bitcoin"
			"addr":"14dt2cSbvwghDcETJDuvFGHe5bCsCPR9jW"
			"tx":"95ed924c215f2945e75acfb5650e28384deac382c9629cf0d3f31d0ec23db08d"
			"confirmed":0
			"timestamp":"1422624765	"
			"date":"30 January 2015"
			"datetime":"2015-01-30 13:32:45"
		} 
		$box_status = "cryptobox_newrecord"; // or "cryptobox_updated" (description below)
	?>




B. 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.05 BTC to you -

<?   
	function cryptobox_new_payment($paymentID, $payment_details, $box_status)
	{
		// IPN Function will receive -  
		$paymentID = 2; // record id in your table crypto_payments
		$payment_details = Array 
		{
			"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":""
			"usercountry":""
			"amount":"0.05"
			"amountusd":"12.26"
			"coinlabel":"BTC"
			"coinname":"bitcoin"
			"addr":"14dt2cSbvwghDcETJDuvFGHe5bCsCPR9jW"
			"tx":"6f1c6f34189a27446d18e25b9c79db78be55b0bb775b1768b5aa4520f27d71a8"
			"confirmed":0
			"timestamp":"1422623712"
			"date":"30 January 2015"
			"datetime":"2015-01-30 13:15:12"
		}
		$box_status = "cryptobox_newrecord"; // or "cryptobox_updated" (description below)
	?>



Fields in $payment_details -

  • paymentID - current record id in the table crypto_payments
  • 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)



Usually the function cryptobox_new_payment() will automatically appear for each new payment two times -

  • a) when a new payment is received, with values: $box_status = cryptobox_newrecord, $payment_details[confirmed] = 0.
  • b) and a second time when existing payment is confirmed (6+ confirmations) with values: $box_status = cryptobox_updated, $payment_details[confirmed] = 1. 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: $box_status = cryptobox_newrecord, $payment_details[confirmed] = 1



Original PHP Sources - cryptobox.callback.php and cryptobox.newpayment.php.







Testing Environment


You can use 500 free Speedcoins or Dogecoins for testing, create dogecoin/speedcoin 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.005 BTC for Bitcoin, 5 coins for Speedcoin and Dogecoin, etc










CONTACT US


We offer Free Support in the integration of our GoUrl Crypto Payment Gateway in your scripts/plugins/website (accepting Bitcoin/Dogecoin/etc payments from users online).

Please feel free to contact us if you have any questions

Contact Us











May 2017
Back to Top