Using reCaptcha with your Stripe Web Widgets


You can set up your Stripe web widgets to use Google reCaptcha v3 - reCaptcha helps prevent fraudsters from using your Stripe web widgets for card testing. You can find out more about Google reCaptcha v3 here 

These are the steps you need to follow

Generate your reCaptcha keys

To protect your Stripe web widgets with reCaptcha v3 you need to generate the keys required to do this as follows:

  • Go to the Google reCaptcha page and login with a Google account.
  • When signed in, go to the 'Register a new site' box, 
  • Enter a suitable label - e.g. your website name
  • Choose 'reCaptcha v3'
  • Enter your website domain(s)
  • Click 'Register'.


After registering you will be provided with a Site key and a Secret key - you will need to enter these into Donorfy.

Important - Do you have Existing Widgets?

If you have existing widgets you must update them so they are ready to use reCaptcha - see the next section of this article for help with this - this should be done before you enter the reCaptcha keys into your Donorfy configuration.

If you enter the reCaptcha keys into your Donorfy configuration before updating your widgets then your existing widgets will no longer work.



Enter the reCaptcha keys into your Donorfy configuration

Sign into Donorfy - go to Settings | Configuration and search for Stripe Connect - enter your Site Key and  Secret Key into the appropriate fields in the Google reCaptcha section.

You can also adjust the Recaptcha Pass Threshold - Google will calculate a score each time a donation is made via a Stripe widget using reCaptcha - the score will be between 0.0 and 1.0, with scores closer to 1.0 being a valid donation and scores closer to 0.0 indicating a strong likelihood that the donation attempt was generated by a bot. This pass threshold is initialised to 0.5 - if you find bad requests are getting passed reCaptcha then increase the score - e.g. by increments of 0.1. You can see the scores Google calculates for your reCaptchas in the Score distribution graph on the Google reCaptcha page

Once you have entered the keys press Update.

New widgets you generate will now use reCaptcha.


Existing Widgets

Note only SCA compliant widgets are compatible with reCaptcha - we strongly recommend you update all your widgets to the SCA compliant - see this article for help with that

If you have existing widgets you need to make a few changes to them so that they can use reCaptcha - Important you must enable reCaptcha on all of your Stripe widgets - you cannot have some widgets protected with reCaptcha and some not using reCaptcha.

This is what you need to do

  • Log into your website or CMS and find the page(s) which contain your Donorfy web widgets
  • Edit your widget code as follows
    • Update to use the latest Stripe Payments Javascript file i.e. you will have a reference to a stripepayments javascript file similar to this
<script type="text/javascript" src=""></script> 

this needs to be changed to use stripepayments_2020.5.2.js - i.e. remove the existing reference and add this

<script type="text/javascript" src=""></script>
    • Below the line which loads the Stripe javascript - example below - add this line  <script src=" reCaptcha Site Key goes here"></script>  - make sure you put your reCaptcha Site Key where indicated
<script type="text/javascript" src=""></script>
    • You need to keep the reference and have added a new line below for
<script type="text/javascript" src=""></script> 
<script src=" reCaptcha Site Key goes here"></script>
    • Scroll down the widget HTML - near the bottom of the page you will find some hidden fields like these - note that the ?? will be replaced with actuals values 
<input type="hidden" id="PublishableKey" value="??" />
<input type="hidden" id="TenantCode" value="??" />
<input type="hidden" id="WidgetId" value="??" />
<input type="hidden" id="DonationPageId" value="??" />
<input type="hidden" id="RedirectToPage" value="??" />


Add these 2 lines below making sure you enter your recapture Sitekey where indicated - the value for ReCaptchaAction will identify where the reCaptcha requests came from and will be shown in your Google reCaptcha dashboard - you can change this if required.

<input type="hidden" id="ReCaptchaSiteKey" value="Your reCaptcha Site Key goes here" />
<input type="hidden" id="ReCaptchaAction" value="Donorfy" />

When you load your page you should see the  reCaptcha logo shown on the righthand side near the bottom of the browser window - e.g.


If you do not see this logo then there is a problem with the line that loads reCaptcha javascript - example below - check this line and that the site key is correct

<script src=" reCaptcha Site Key goes here"></script>

If there is a problem you may see a red error message displayed next to the reCaptcha logo - e.g. 

  • 'ERROR for site owner: Invalid domain for site key' - this means the domain you are using is not linked to the reCaptcha in the Google


Testing Your Updated Widgets

To test your widget works you need to put through a small donation using a live credit card - the details of the donation will appear in Donorfy under Financial | Online Donations - if, when you press the donate button on your widget, you get an error message - e.g.  There is a problem with your donation An unexpected error occurred (error code) - these are what the error codes mean

  • error code (11) - a reCaptcha token was not sent by the Widget - this might mean you have not upgraded the widget to use reCaptcha
    Or, it could be that the website browser being used has blocked tracking and cookies - the browser settings will need to be changed to allow cookies and tracking.

  • error code (12) - the reCaptcha token failed or is a bad request
    • this could be a problem with the site & secret keys - further details will be shown in Errors & Info tab under Financial | Online Donations
    • or it may be that the domain that the widget is hosted on is not registered on the reCaptcha settings - you will need to edit your Google reCaptcha to add the domain(s) as required





Please sign in to leave a comment.
Powered by Zendesk