Captcha (reCAPTCHA, hCaptcha)

A captcha asks a guest to tick a box, such as “I’m not a robot”, before the form can be sent. It keeps bots from filling your review queue with fake applications. Sami B2B Onboarding supports two providers: Google reCAPTCHA v2 with the “I’m not a robot” checkbox, and hCaptcha.

The store has one pair of keys from one provider. Each form turns the captcha on or off.

Note

Buyers who are signed in to their customer account never see the captcha. They already proved who they are when they signed in.

Get your keys

1. Open the reCAPTCHA admin console and sign in with your Google account.
2. Give the site a label, such as your store’s name.
3. For the type, choose Challenge (v2), then “I’m not a robot” Checkbox. Keys of another type, such as v3, don’t work with the app.
4. Under Domains, add every domain your store is reached on: your own domain, such as example.com, and your myshopify.com domain.
5. Submit the form, then copy the site key and the secret key.

1. Open the hCaptcha dashboard and sign in.
2. Under Sites, add a new site.
3. Add every domain your store is reached on as a hostname: your own domain, such as example.com, and your myshopify.com domain. Save the site.
4. Copy the site key and the secret key the dashboard gives you.

Add the keys to the app

1. Open the Captcha panel

   Go to Forms and click Edit beside the form. In the rail on the left, click Integrations. Under Connected apps, click Set up on the Captcha row.

   The Captcha panel opens with two sections: Account and This form.

2. Fill in the keys

   Under Account, click Set up. In the Captcha dialog:

   1. In Captcha type, choose Google reCAPTCHA or hCaptcha, to match where your keys come from.
   2. Paste the site key into Site key.
   3. Paste the secret key into Secret key.

   The link under the boxes, Get your keys from the reCAPTCHA admin console or Get your keys from the hCaptcha dashboard, follows the type you picked.

   

   Pick the provider that issued your keys, then paste both keys.

3. Save the keys

   Click Save. You see Keys saved. The Account row shows the captcha type, the site key and the start and end of the secret key.

   If a box is empty, it asks for the key, for example Enter the site key from your account.

Turn it on for the form

1. Choose the language

   Under This form, pick the Language of the captcha. Match the buyer’s browser is the default. Pick a language to show the captcha in that language for every buyer.

2. Enable it

   At the bottom of the panel, click Enable. The button changes to Disable, and the Captcha row in Connected apps shows Active. If the keys aren’t saved yet, a banner reads Add both the site key and the secret key first.

   The preview now shows a stand-in captcha box, I’m not a robot or I am human, above the buttons on the form’s last page. The real captcha only loads on your storefront.

   

   Once the captcha is on, the button at the bottom reads Disable and the row shows Active.

3. Save the form

   Click Save in the save bar. You see Form saved. Buyers get the captcha from now on.

Check it on your storefront

1. Open the form as a guest

   Go to Forms and click Copy link beside the form. Open the link in a private browser window, so you aren’t signed in to your store.

2. Find the captcha

   Fill in the form. On its last page, the captcha sits above the buttons. Click Submit application without ticking it: the form says Please complete the captcha. under the box.

   

   Guests tick the captcha box before they can send the form.

3. Submit

   Tick the box, solve the challenge if one appears, and submit. The thank-you screen appears, and the application arrives in Companies › Applications.

Who sees the captcha

• Guests applying see it on the form’s last page.
• Guests answering a request for more information from the link in their email see it too.
• Signed-in buyers don’t see it, on either.

A ticked box expires after a minute or two. The form then clears the tick and asks the buyer to tick it again. On a form too narrow for the normal captcha box, such as a block in a sidebar, the captcha shows in its compact size. On a dark form, it uses its dark look.

To change Please complete the captcha., open After submit in the rail, expand Error message and type your own wording in the Captcha box.

If the app can’t get an answer from the captcha provider when the buyer submits, it accepts the application rather than turning the buyer away. It still lands in your review queue.

Fix common problems

What you see	Why	What to do
The captcha box shows an error such as “ERROR for site owner: Invalid site key”, and nobody can submit.	Captcha type doesn’t match the provider that issued the keys, or the site key wasn’t copied in full.	Under Account, click Change. Set Captcha type to the provider that issued the keys, and paste the site key again.
The captcha box says the domain isn’t valid for the site key.	The domain the buyer is on isn’t registered with the provider.	Add that domain in the reCAPTCHA admin console or the hCaptcha dashboard.
Every application is refused with That captcha check failed. Please try again.	The secret key is wrong, or belongs to another site.	Under Account, click Change, paste the right secret key and click Save.
No captcha on the form.	The captcha isn’t enabled on this form, the keys were removed, or you’re signed in.	Check the Captcha row shows Active, then test in a private window.

Caution

A wrong secret key can’t be spotted when you save it. Always do the storefront check above after you add or change keys.

Turn it off

• On one form: open its Captcha panel, click Disable, then Save.
• On every form: under Account, click Change, then Remove keys. The dialog warns Every form in this store stops using Captcha until you add keys again. Click Remove keys to confirm. The captcha disappears from every form at once.

Next steps

• Ask buyers to log in before applying — only accept applications from signed-in buyers.
• Rules that decide applications — reject or flag applications that slip through, based on their answers.
• Address autocomplete (Google Maps) — help real buyers fill in their address.