CryptoGofer!

Documentation & Implementation

This is intended for people with some knowledge of code, php specifically...but having said that, if I continue to hear the same comments/questions about set-up I will begin work on a knowledgebase. Your feedback will help, & donations are appreciated!

Topics:

• Sending Transactions
• Getting Our Exchange Rates
• Variables You Can Send
• What We Return
• Security Hash
• Return URL
• Notification URL (IPN/Listener)

How To Send Transactions:

Sending a transaction (requesting your user pay) is quite simple, you can just use a normal hyperlink like this (of course you can fancy that up by using an image, or whatever):

<a href="http://CryptoGofer.com/send.php?u=YOUR_USER_ID&h=HASH&w=WALLETADDRESS&ad=50&c=BTC">Click To Pay</a>

Or you may wish to create a form on your site and post to us:

<form action="http://CryptoGofer.com/send.php" enctype="multipart/form-data" method="post">
  <input type="hidden" name="u" value="YOURUSERID" />
  <input type="hidden" name="h" value="HASH" />
  <input type="text" name="w" value="WALLET" />
  <input type="text" name="ad" value="50" />
  <input type="hidden" name="c" value="BTC" />
  <input type="submit" value="Pay Now" />
</form>

Exchange Rates:

Why would you do this?
To give your user an expectation of how much crypto they'll be paying...or whatever - it's kind of unessesary since you'll be able to just send them to our site with a price in USD and it will automatically convert...but I know this is a functionality I would want, so I made it.

Here's the code:

<php
$data = json_decode(@file_get_contents("http://CryptoGofer.com/crypto2usd.php"), true);
$ltc_price=$data['LTC'];

You can get the price of any coin we support by simply changing out the 'LTC' with any of the currencies found here: http://CryptoGofer.com/crypto2usd.php

You can access this in any language you're comfortable with...I'm just a php guy.

To avoid complications of people paying the wrong amount because of volatile currencies, we only update our prices a couple times per day.

This helps if someone isn't able to complete their transaction in the 10 minutes provided and needs to manually update their amount later on in the day...and as you may know, even 1 minute can make a difference in crypto.

Variables You Can Send:

Required Variables:
u	Your User ID
h	Hash how to create
w	Is walled address to send to
c	Currency ie. BTC, BCH, LTC...
NOTE: Send One OR The Other Amount, NOT both - if both are sent crypto will be used.
ad	Amount To Pay In USD
ac	Amount To Pay In Crypto
Optional Variables:
p	Product ID/Description
v	Variables you would like to send, ie a username or other identifying information for you to
r	return url, (where the user goes after payment) how to create Please Note: You cannot send your return url with any parameters, (ie. http://mydomain.com/?whatever=whatever) When we redirect back to you we will need to send variables to that page, and that leads to conflicts.

Allowed Characters:

As you may know, some characters can effect the functionality of a URL and/or database...as such we only allow:
• Alphanumeric characters (ie, A-Z a-z 0-9)
• @ (At Sign)
• , (comma)
• . (period)
• - (hyphen)
• / (forward slash)
• : (colon)
ALL other characters will be turned into a tilde (~), so we don't reccommend using it.

So you may need to check what we send back to you for a match like this:
$returned_var = $_GET["returned_var"];
$my_var='whatever';
$my_stripped_var=preg_replace("#[^0-9a-z @.,-]#i", "~", $my_var);

Now you can make a match for whatever functionality you need - but note this isn't 100% accurate, if someone else has a different illegal character in the same place, but the rest of the same allowed...statistically quite a low probability, and I've been doing this for years without issue.

What Do We Send Back?

CGhash	We will return a hash so you know this is from us: see example below.
CGstatus	success, cancel, fail, timeout, wronghash, usedtxn
CGnote	A note/comment; sent when status=fail or other unexpected events
CGtxn	Transaction hash/ID
CGconf	Transaction Confrimations
CGwallet	wallet address paid
CGcrypto	what crypto currency ie. BTC
CGamt	amount paid in crypto
CGprod	Product ID/Description (you sent this)
CGvars	Other variables you sent, if you need multiple simply send comma separated and create an array like "something:this,whatever:that" etc...then array it on your end

How To Create Your Security Hashes:

We create this hash so people aren't able to change payment amounts or wallets once they land on the payment page...and especially so you know the information we send back to you is correct.

Send Hash (this is for posting to us)

$send_hash=md5($amount.$currency.$wallet.$prod.$vars.md5($private_key));

Return Hash (this is what we send back to you)

$return_hash=md5($status.$txn.$wallet.$amount.$conf.$prod.$vars.md5($private_key));

Notes:
• Amount Returned To You Is In Crypto!
• Remember, your private key should NEVER be given out - The ONLY way someone can change the wallet or ammount is by knowing your private key!
• If 'the math' does not add up we simply return the user to your site.
• There is a send hash generator inside the members area, if you need to create static payment links for your site.

Return URL:

So when they land on your page you should do some basic checks...here is what a basic return url could look like - obviously you're going to need to make it beautiful, again, I'm just a php guy ;)

<?php
// you'll need to update your private key:
$private_key='YOUR_CRYPTO_GOFER_PRIVATE_KEY';
$user_message='';

// we'll send this info to you in the url
$CGhash = isset($_REQUEST["CGhash"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGhash"]) : '';
$CGstatus = isset($_REQUEST["CGstatus"]) ? preg_replace("#[^0-9a-z ._-]#i", "", $_REQUEST["CGstatus"]) : '';
$CGnote = isset($_REQUEST["CGnote"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGnote"]) : '';
$CGtxn = isset($_REQUEST["CGtxn"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGtxn"]) : '';
$CGwallet = isset($_REQUEST["CGwallet"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGwallet"]) : '';
$CGcrypto = isset($_REQUEST["CGcrypto"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGcrypto"]) : '';
$CGamt = isset($_REQUEST["CGamt"]) ? preg_replace("#[^0-9.]#", "", $_REQUEST["CGamt"]) : 0;
$CGconf = isset($_REQUEST["CGconf"]) ? preg_replace("#[^0-9]#i", "", $_REQUEST["CGconf"]) : 0;
$CGprod = isset($_REQUEST["CGprod"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGprod"]) : '';
$CGvars = isset($_REQUEST["CGvars"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGvars"]) : '';

// create a hash to verify the post is from us:
$verify_hash=md5($CGstatus.$CGtxn.$CGwallet.$CGamt.$CGconf.$CGprod.$CGvars.md5($private_key));

// start the logic to check what to do with the transaction
if ($CGstatus=='success') {
  if ($verify_hash!=$CGhash) {
	// SECURITY HASH CHECK FAILED:
    // here you may choose to record user information, or set up some kind of security against people trying to cheat you...
	$user_message='<h3 align="center" style="color:#F00">Payment Failed. Please <a href="order.php">Click Here</a> to try again</h3>';
    
	
  } else {
	$user_message='<h3 align="center" style="color:#090;">Payment Successful! It may take a few minutes or hours till the payment is confirmed on the blockchain, but <a href="continue.php">Click Here</a> to continue to the next step</h3><p align="center">Your transaction hash is: '. $CGtxn .' you may want to save that for your records</p>';

	// after this you may choose to update a database with the user info, or simply send yourself an email...or do nothing if you're using the notification URL
    // worth checking in your database if you've already got this transaction before doing anything (it's good practice to do this all the time, but here especially).
  }
    

} elseif ($CGstatus=='fail') {
	$user_message='<h3 align="center" style="color:#F00">Payment Failed. Please <a href="order.php">Click Here</a> to try again</h3>';
    $status.=$note;
    // you may want to store these or email yourself

} elseif ($CGstatus=='timeout') {
	$user_message='<h3 align="center" style="color:#03F;">Looks like your transaction timed out...<a href="order.php">Click Here</a> to start your order again</h3>';
    
} elseif ($CGstatus=='usedtxn') {
	$user_message='<h3 align="center" style="color:#03F;">This transaction has already been used...<a href="order.php">Click Here</a> to start your order again, or <a href="continue.php">Click Here</a> to continue</h3>';
	// you'll probably want to check if you have it, then verify it with our hash before doing anything
    
} else {
	$user_message='<h3 align="center" style="color:#03F;">OOPS, not sure how you got here, but we are missing some critical information - if this continues to happen, please contact me and let me know!</h3>';
}

?>
<html>
<head>
<title>Payment Return</title>
</head>
<body>
<h1 align="center">Welcome Back...</h1>
<?php echo $user_message; ?>
</body>
</html>

Notes:
• The messages & links in this example obviously need to be updated to work/make sense on your site.
• If you only have one thing the user could pay for from your site, you can simply use your payment link directly on this page instead of your own "order.php" page

Notification URL:

This is a 'back end' type page where notifications of successful transaction details are sent - this will include the initial transaction, and when your set number of confirmations has been reached.

We require that you echo out a '1' to the the page so we know the message was received.

Example script:

<?php
// YOU NEED TO ECHO A 1 TO THE PAGE SO WE KNOW YOU RECEIVED OUR NOTIFICATION:
echo '1';
// you'll need to update your private key:
$private_key='YOUR_CRYPTO_GOFER_PRIVATE_KEY';

// we'll send this info...
$CGhash = isset($_REQUEST["CGhash"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGhash"]) : '';
$CGstatus = isset($_REQUEST["CGstatus"]) ? preg_replace("#[^0-9a-z ._-]#i", "", $_REQUEST["CGstatus"]) : '';
$CGnote = isset($_REQUEST["CGnote"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGnote"]) : '';
$CGtxn = isset($_REQUEST["CGtxn"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGtxn"]) : '';
$CGwallet = isset($_REQUEST["CGwallet"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGwallet"]) : '';
$CGcrypto = isset($_REQUEST["CGcrypto"]) ? preg_replace("#[^0-9a-z]#i", "", $_REQUEST["CGcrypto"]) : '';
$CGamt = isset($_REQUEST["CGamt"]) ? preg_replace("#[^0-9.]#", "", $_REQUEST["CGamt"]) : 0;
$CGconf = isset($_REQUEST["CGconf"]) ? preg_replace("#[^0-9]#i", "", $_REQUEST["CGconf"]) : 0;
$CGprod = isset($_REQUEST["CGprod"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGprod"]) : '';
$CGvars = isset($_REQUEST["CGvars"]) ? preg_replace("#[^0-9a-z @/:.,_-]#i", "", $_REQUEST["CGvars"]) : '';

// create a hash to verify the post is from us:
$verify_hash=md5($CGstatus.$CGtxn.$CGwallet.$CGamt.$CGconf.$CGprod.$CGvars.md5($private_key));

$email_subject='';
$email_message="status: $CGstatus \r\n note: $CGnote \r\n transaction: $CGtxn \r\n amount: $CGamt \r\n wallet: $CGwallet \r\n product: $CGprod \r\n vars: $CGvars";

// start the logic to check what to do with the transaction
if ($CGstatus=='success') {
  if ($verify_hash!=$CGhash) {
	// SECURITY HASH CHECK FAILED:
	// here you may choose to record user information, or set up some kind of security against people trying to cheat you...
    $email_subject='IPN: FAILED To Verify Hash';
	
  } else {
	// after this you may choose to update a database with the user info, or simply send yourself an email.
    // it's worth checking in your database if you've already got this transaction before doing anything (it's good practice to do this all the time, but here especially).
    // You will likely receive 2 or even more pings from the same transaction, so you'll want to check if the confirmations have been reached
    
	$email_subject='IPN: Successful Transaction!';
    
  }
    
} elseif ($CGstatus=='usedtxn') {
	// transaction is already updated in our database, this can happen if someone manually updates a transaction, bookmarks a confirmation URL, refreshes, or returns to it in some other way.
    // you'll probably want to check if you have it, then verify it with our hash before doing anything
    
    $email_subject='IPN: Transaction Used';
    
} else {
	//  awe CRAP, we missed something (or maybe someone is trying some funny business), it's good to know what:
    $email_subject='IPN: What happened!?';
}

// you'll only get an email if we've set a subject...so set or don't set, as you see fit.
if ($email_subject!='') {
    $header = "From: Your_Site IPN <CHANGE@THIS.EMAIL> \r\n" . 
    'X-Mailer: PHP/' . phpversion() . "\r\n" .
    "MIME-Version: 1.0\r\n" .
    "Content-type: text/plain; charset=iso-8859-1\r\n" .
    "Content-Transfer-Encoding: 8bit\r\n\r\n";
    
    mail('your@email.change',$email_subject,$email_message,$header);
}

?>

Notes:
• The user should never see/go to/know about this page.
• To conserve resources the script will only check for confirmations on transactions for 3 days.
• You can use this script to update your database or simply email yourself, or not use it at all
• We will send you a notification instantly after a transaction, and then again after your specified number of confirmations has been reached/exceeded.
• We will attempt to ping your notification URL 6 times, if we do not see a '1' on this page. 2nd attempt will be made in about 10 minutes, the 3rd in about an hour after that, the 4th in about 12 hours, the 5th after 24 hours the 6th after 48 hours. If we don't see the required info we will assume your notification script isn't working - if a high percentage of your transactions fail, the script will deactivate your IPN service, and you will need to update manually inside your account.