Join 59,299 users and earn money for participation

Tutorial: Integrating CASHBOX on a Website for Foolproof BCH CAPTCHA

2 707 boost
Avatar for RandomLibertarian
Written by   7
11 months ago

The forum at was the inspiration for CASHBOX, due to a weak CAPTCHA allowing loads of spam signups. It uses open source software from Simple Machines Forum written in PHP, the same as used for the original BTC forum at, started by Satoshi.

CASHBOX is designed to work simply (please see guide). Unfortunately, integration on this forum does require programming ability due to the not very intuitive way it's set up. Knowledge of HTML is also necessary.

Let's start by trying to register.

Our difficulty begins with the fact that when clicking 'Register' we navigate to index.php, which is followed by a query string. Indeed, whatever we click navigates to index.php, followed by a query string. What happens on the back end is the script uses the query string value to dynamically generate the page.

This complicates things because we use URL navigation with query string parameters from the payment gateway to know someone has successfully paid. It would make more sense to click 'Register' and be taken to a page named something like register.php. A visitor filling out the form could go next to register2.php. That would make sense and be SEO friendly. It's unlikely search engines will ever recognize pages as being different based only on query string values, because underlying script behavior can change.

So our first task is finding out what script actually displays the registration page.

Here we see the CAPTCHA needing replacement, but also another problem. Our plan is setting our Pay Success URL to return to this location with expected paid parameters. However, the URL we come back to '' is the exact same one that shows the initial registration agreement above. What is happening is the script is only showing the CAPTCHA page depending on whether the 'I accept the terms of the agreement' button was clicked. We'll circle back to handling this. Let's first find the script generating the CAPTCHA page.

After tracking the script's action through variables, arrays and directories we locate the target file, Register.template.php, inside the Themes > default directory. Let's have a look.

Our target area is a PHP if block echoing some HTML mixed with PHP. After saving a backup file we verify this is the section we want by replacing all the FIELDSET area HTML with the words 'This is a test' and viewing the result.

Success! Our modified text appears where we want without breaking any formatting. Now we simply add in our customized HTML and PHP code.

The SPAN tags in the original HTML only added padding so we end up using only the original two DIV and H4 tags in our modification. We use variables named $HTML_paid and $HTML_unpaid to keep things neat, also writing in the word 'Verification' for a heading as it will no longer be dynamically generated. Then we create another conditional check. Since the file Register.template.php is included in the parent file executing the script the passed associative array of variables should still be available via $_REQUEST. That being the case, the only way a variable of 'addr_bch' should be set is if it was part of the URL query string, which we imagine only happens if the URL is coming from our gateway on successful payment. In that case we show a payment success message, but also include two hidden form values which will be submitted along with everything else on the registration form. The values are the wallet address payment was sent to and a verification hash. Otherwise we show our unpaid HTML which has our CASHBOX prompt. Let's see how it looks.

That's close! We just need a few modifications to our CASHBOX generated HTML.

Note the generated HTML does have a few quotes needing to be escaped with backslashes, but otherwise drops right into the PHP code. We then simply modify the style of the DIV tag to include margin:auto; to center the CASHBOX and add a P tag pair enclosing a non-breaking space afterward to add padding on the bottom. Let's see the result.


Our upgraded CAPTCHA appears where we want. We're almost ready to handle the form submission. Before that, though, we should verify our CASHBOX is working as expected. Upon sending a successful payment we're redirected back to the URL we want, basically index.php followed by 'action=register' with our CASHBOX values for addr_bch and vhash appended.

Whoops. While we were successfully redirected back to our desired URL with appropriate parameters the page shows the registration agreement again. This is because, being directly sent to this URL, we never clicked the 'I accept the terms of the agreement' button.

The easiest way to handle this is remove the registration agreement. We can instead link to the site's terms and say clicking the register button on the CAPTCHA page indicates acceptance. Fortunately, there is an admin option to remove it. Otherwise we'd need to disable it in the code.

Okay, with that disabled let's try again...

Nice. Let's view the page's source HTML to verify our hidden form fields are there.

Yep. Everything is there. Okay, now we can finally move to the registration form submission. Leaving everything blank we click 'Register'.

Okay, so while we're still navigating to index.php our query string has changed to 'action=register2'. Notice our CAPTCHA area still indicates a payment success message. This is because we didn't care whether the addr_bch variable was sent via GET or POST. We only check to see if it's there. If so, we assume the visitor has paid and doesn't need to pay again just because of form errors.

We also notice the error message relates to validating the old CAPTCHA. It turns out the 'action=register2' loads a main Register.php file located in the Sources directory. We'll modify this file to replace the old validation with our upgraded validation.

Nicely commented code makes it easy to locate the validation code section. All together the code here looks complicated, mostly as a result of the old validation. Our new validation code, beginning with variables headed $cashbox_, is pretty simple.

Just like before this PHP file should have access to the passed associative array of variables. So using the visitor's provided values for addr_bch and vhash we try reconstructing the verification hash from the CASHBOX gateway as described in the help guide. If the hashes, which include a secret code only we have access to, don't match validation fails and we simply continue using the existing process, and rewriting our own error message.

It's now impossible to register without sending information containing our secret code, which is only gained upon successful payment.

Let's see if everything works.

It works! Upon successful payment we can register straightaway. We're all done.

Note there is one hack currently available to a spammer. That's to pay and then reuse the addr_bch and vhash values. However, it's easy to record either of these and ensure they are only used once.

This was a fairly difficult integration, but CASHBOX can be used more simply. To recap, the basic idea is inserting a CASHBOX as a paywall. Set the Pay Success URL to redirect payer back to that page with addr_bch and vhash parameters included. Use scripting to check for the presence of these values; if they are present show a paid message and include the values in hidden form fields. Submit those values to the next page for a validation check, using the verification hash which includes the CASHBOX secret code. If the hashes don't match the visitor doesn't gain access. To prevent reuse of the same paid credentials simply record the vhash value. (Also, don't forget to sanitize text inputs.)

Bring it on spammers!

$ 0.35
$ 0.25 from @Read.Cash
$ 0.10 from @tula_s
Avatar for RandomLibertarian
Written by   7
11 months ago
Enjoyed this article?  Earn Bitcoin Cash by sharing it! Explain
...and you will also help the author collect more tips.


Could something like hcaptcha with BCH payouts work? Would also be a (small) extra source of income for the site, but wouldn't require the user to hold any coins.

$ 0.00
11 months ago


Looking at the hcaptcha site it appears the human-proof-challenge is still computer generated/assessed with different levels of difficulty (Easy, Medium, Hard etc). So bots can still get through, while operators have the ability to adjust the difficulty. The goal with a CASHBOX is removing all uncertainty. There are only two conditions: paid or unpaid. In this way, even if a bot comes through, the site earns the specified amount which can go toward spam clean up. The difference for spammers is they must pay some (adjustable) cost. That's what's missing with all existing CAPTCHAs.

Site operators could certainly choose hcaptcha, but I think many would prefer CASHBOX, because the main goal is reducing/removing spam headaches, and I think the CASHBOX approach does that best.

$ 0.00
11 months ago