FraudRecord Query

Check a client against the shared FraudRecord database, and file your own reports on the ones who burn you, without ever leaving their Blesta profile.

What it does

Chasing down a client's history with other hosts usually means leaving Blesta entirely, opening a separate site, and copying identity details back and forth by hand. FraudRecord Query puts that check on the client's own profile: one click looks the client up against the shared FraudRecord database and tells you how many reports exist against them, and another lets you file your own report on a client who has burned you, without your staff ever leaving the page they were already on.

Key features

• One-Click Client Check: A Check on FraudRecord action on any client profile runs the lookup and comes back with how many reports exist against that client, the reliability score behind them and a link straight to the full detailed report.
• Confirm Before Anything Is Sent: Opening a check first shows you exactly which details would be submitted and sends nothing until you press the button, so following the link out of curiosity never discloses a client to a third party.
• Report a Bad Client in Seconds: File a report straight from the client's profile, choosing from fifteen report types, a severity from 1 (low offense) to 10 (highly dangerous), and the description every other host who queries them will read.
• Edit the Details Before You File: The report form pre-fills everything the plugin holds on the client as an editable list, so you can correct a stale number, drop a value you would rather not submit, or add one it could not find, before the report goes anywhere.
• Client Identity Gathered Automatically: The client's name, company and address, phone numbers, email addresses across every contact on the account, and IP addresses they have signed in from are collected for you, taken only from the client's own record.
• Personal Data Is Hashed Before It Is Sent: Every identity value is one-way hashed before it leaves your install, exactly as FraudRecord expects, so you can take part in the shared database without publishing your client's real details.
• Fraud Status Badge on the Client Profile: A badge on the staff client profile shows that client's last known FraudRecord result and the time it was checked, with a re-check link, so staff see the warning before they act.
• Query and Report Audit Log: A FraudRecord Query Log screen under Tools lists every check and every report your staff have run, with the date, the client, the staff member responsible, the action and its result.
• Built-In Demo Mode: A Mock API mode serves fixture responses instead of contacting FraudRecord, so you can trial every screen before you have a reporter profile or an API key.
• Per-Staff-Group Permissions: Checking, reporting, viewing the audit log and viewing the status badge are each their own permission, granted per staff group.

Installing FraudRecord Query

Before you start

• Version 3.x requires Blesta 6.0 or later. On a Blesta 5 install, use version 2.x instead.
• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

plugins/fraudrecord_query/

For example, on a typical install: /var/www/html/blesta/plugins/fraudrecord_query/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has the Plugins permission (found under the Settings group in Manage Staff Groups).
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find FraudRecord Query in the list and click Install. You'll see a message confirming the plugin installed and reminding you that any permissions it registered still need to be granted to your staff groups.

3. Configure it

1. From the Installed tab, click Manage next to FraudRecord Query.
2. Enter the API Key - the reporter code you generate from your FraudRecord account under "My Reporter Profiles". Leaving it blank on a later save keeps whatever key is already stored.
3. Tick Enable Mock API if you want to try the plugin out first: it serves built-in sample responses instead of contacting FraudRecord, so you can see every screen without a reporter profile and without filing anything real. Turn it off once you have a live API key.
4. Click Save Settings.
5. Go to Settings > System > Staff > Staff Groups, edit each staff group that should use this plugin, and tick its four permissions under the FraudRecord Query section: Check Clients on FraudRecord, Report Clients to FraudRecord, View FraudRecord Query Log and View FraudRecord Status Badge. A fresh install grants none of these to anyone until you tick them here.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating FraudRecord Query

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Plugins.
4. Find FraudRecord Query and click Update to run the upgrade.

Version-specific notes

• v3.0.0: Requires Blesta 6.0 or later - upgrade Blesta first, then the plugin. Blesta 5 installs should stay on 2.x. Nothing changes in your data, settings or permissions: the settings page, the check and report screens, the FraudRecord Query Log and the client-profile status badge simply take on the Blesta 6 admin theme, and what the plugin sends to FraudRecord is unchanged.
• v2.2.0: Adds a FraudRecord Query Log (under Tools) and a status badge on the client profile - both gated by new permissions that are granted to nobody by default, so grant "View FraudRecord Query Log" and "View FraudRecord Status Badge" to each staff group that should see them (Settings > System > Staff > Staff Groups). Checking a client is now a two-step action: "Check on FraudRecord" opens a page listing exactly what would be submitted, and nothing is sent until you press the button on that page - a bookmark to the old direct-check link now lands on this confirmation screen instead. The stored API key is now masked on the Manage screen and never redisplayed; leaving the field blank on save keeps the key you already have.
• v2.1.0: Adds staff permissions for "Check on FraudRecord" and "Report to FraudRecord" - also granted to nobody by default, so grant them per staff group the same way. Your stored API code is encrypted in place automatically; no re-entry is needed. Also adds a Mock API option on the Manage screen so you can demonstrate or test the plugin without a reporter profile and without filing real records.

Using FraudRecord Query

This is a staff tool - your clients never see anything it adds to Blesta.

For your staff

Checking a client on FraudRecord

Open any client's profile, open Account Actions > Show All Actions, and choose Check on FraudRecord. This does not contact FraudRecord yet: it opens a confirmation page listing every identity value the plugin holds on that client as a "Queried Data" table - name, address, company, phone numbers, email addresses and IP addresses it has on file - so you can see exactly what would be sent before anything leaves your installation. A banner reminds you that nothing has been sent anywhere yet. Opening this page never discloses anything by itself, even if the link is opened by accident.

Press Check on FraudRecord on that page to actually run the check. The page reloads with a Query Result section: the FraudRecord value, how many reports exist against the client, a reliability score, and a "Click Here" link through to the full detailed report on FraudRecord's site. A banner tells you either that the client appears to have reports, or that none could be found. Either way, the check is recorded in the FraudRecord Query Log and the button changes to Check Again for next time.

Reporting a client to FraudRecord

From the same Show All Actions menu, choose Report to FraudRecord. The form pre-fills the same identity data as the check, as an editable list of key/value rows - correct a stale number, remove a value you would rather not submit with the trash button on its row, or add one the plugin could not find with the Add button below the table. Choose a Type (Non-payment, Chargeback, Stolen Card, Fraud, Spammer, and more - fifteen in total), a Value (Severity) from 1 (low offense) to 10 (highly dangerous), and write a Description - the text anyone else who queries the client will read. Click Report Client to file it. A successful report shows a banner with the FraudRecord report identifier it was filed under, and is recorded in the FraudRecord Query Log alongside the severity you chose.

The FraudRecord status badge

Every client profile carries a FraudRecord panel showing the outcome of the last check run against that client: a green shield and "No FraudRecord reports found", or a red one and the number of reports, plus when it was last checked and a Re-check on FraudRecord button. A client nobody has checked yet shows "This client has not been checked on FraudRecord yet." with a Check on FraudRecord button instead, so staff see the gap rather than assuming a check has already happened.

The FraudRecord Query Log

Under Tools, the FraudRecord Query Log lists every check and report your staff have run against any client, newest first: the date (UTC), the client (linked to their profile), the staff member who ran it, whether it was a Query or a Report, and the result - the report count for a check, or the severity filed for a report.

Good to know

• Checking and reporting, viewing the query log, and viewing the status badge are each their own staff permission - a staff group sees none of this until it is granted the relevant permission in Manage Staff Groups.
• A report you file is permanent on FraudRecord's shared database once submitted - there is no undo. Review the identity rows and description before clicking Report Client.
• With Enable Mock API turned on in the plugin's settings, checks and reports are served from built-in sample data instead of reaching FraudRecord, so you can try every screen before you have a reporter profile.