A. The 36 character API Key that was emailed to you when you signed up for BadCustomer.

B. A server with scriptable web interface that can parse JSON or XML using PHP5 with PEAR Base and PEAR HTTP_Request package installed.

The BadCustomer.com database is designed to take data in "POST" payloads to: https://www.badcustomer.com/api/. This is what most HTML forms use to submit data to a server. A POST payload embeds the data into the stream of the request, rather than placing it into the URL of the request. To properly submit a request to the API, you will typically need a server with a scriptable web interface that can parse either JSON (JavaScript Object Notation) or XML (Extensible Markup Language).

You may use either JSON or XML format for your request, and BadCustomer.com will supply a response in the same language you used to make your request.

Review the combinations of search parameters below and decide which ones you want to use when querying the BadCustomer database.

Keep your business objectives and target audience in mind when choosing the search criteria to query the BadCustomer database. If you want to screen customers more diligently, you may want to consider searching by Cardholder Name & Card Number Hash. This combination of search criteria will return the most chargeback results.

If you wish to return less results in order to not impact immediate sales, you may want to search by Cardholder Name, Card Number Hash, Address, & Zip Code. We recommend you choose from the following combinations of information types that have been found to be the most effective.

Card Number Hash Only:
SEARCH RESULT: Will return a positive result if any chargebacks with this Card Number Hash are found.
POSSIBLE OUTCOME: A chargeback offender may have other Card Number Hashes that would not be found with this search parameter.

Card Holder Name & Card Number Hash:
SEARCH RESULT: Will return a positive result if the Card Holder Name and Card Number Hash are associated with any previous chargebacks, regardless of the Address associated with the Card Number Hash. 
POSSIBLE OUTCOME: If the chargeback offender has moved since the chargeback, this search parameter would still display a positive result.

Card Holder Name, Card Number Hash, Address, & Zip Code:
SEARCH RESULT: If you want to be sure the chargeback information on file is a match, then you should search by these categories.
POSSIBLE OUTCOME: This combination of search parameters would exclude any additional Addresses the chargeback customer may have had.

Card Holder Name, Address, & Zip Code:
SEARCH RESULT: Will return a positive result for any Card Number Hashes used at a chargeback customer's Address.
POSSIBLE OUTCOME: If a person has multiple Card Number Hashes associated with this “Chargeback Address”, positive results will be returned.

Card Number Hash, Address, & Zip Code:
SEARCH RESULT: Will return a positive result based on the customer’s information, regardless of the individual's name.
POSSIBLE OUTCOME: If a chargeback offender has a new surname after marriage, they would still be found with these search parameters.

Email Address Only:
Search by Email Address only is not recommended.

Should you have any questions or concerns, please contact BadCustomer for help:
partner_support@badcustomer.com

Have your developer integrate the request call to the BadCustomer API into your payment processing interface.

In order to submit a request to the API, you will need to have your API Key.

The request will also need to include the search parameters' data about the consumer you are inquiring about using at least one of the following:
card_number_hash (MD5)
card_holder_name
address
zip code
email_address

This data is encoded into either a JSON or an XML object and submitted to the API. In each case, the $response variable holds a PHP array derived from either a JSON or XML object that was returned by the API. The conversion from PHP array to JSON for transport, then converting the response back to PHP array, is handled by the HTTPClient class.

Examples
Several examples follow that use a class we created based on HTTP_Request's HTTPClient class. That class and examples are included in a zip file that can be downloaded here:
Download the example files
View the examples that convert PHP arrays into these encoded objects.

The examples above utilize PHP for scripting (any server side scripting language should be able to do this), JSON for data encapsulation, and leverage the HTTP_Request set of PHP classes available from PEAR for making requests over the internet and encoding the data. 

Requirements for these examples:

PHP5
Pear base installed
http://pear.php.net
Pear HTTP_Request package installed
http://pear.php.net/package/HTTP_Request

A response code of 0 means that a Chargeback was not found in the search results and the purchase is processed as normal. A response code of 1-14 means that a Chargeback was found in the search results. As a Merchant, you have the option of halting the purchasing process and redirecting your customer to BadCustomer.com where they can remove themselves from the list and pledge not to chargeback again before they can again purchase your products.

Response Codes
1+ will be generated along with one of the messages below when a chargeback is found. A return URL will also be provided, which should be used to redirect the customer to BadCustomer.com. The customer will then be given an opportunity to have themselves removed from the BadCustomer database by pledging to exhaust all possibilities for to first obtain a refund in the future if they have issues with a Merchant.

Found Results (one of the following):

Response Field Format

GUID           36 char
Error             1 char
Found            1 char
Response    250 varchar

An error code of 0 means that no errors were found. An error code of 2-12 means that an error was found when searching the database.

Transaction Errors
1+ will be generated along with one of the following messages if an error occurs.

Transaction Code
Error (0 for no errors, 1+ for error)
Found (0 for not found, 1+ if found)
Error Reason (one of the following):