Best Practices


Response checking/error handling: Merchants should make sure that all responses messages from Bluefin are captured and utilized to confirm a successful transaction.


Daily Reporting

RSAPI reports return all transactions from a 24-hour period. RSAPI reports should not be run for the current day because too many transaction statuses are subject to change until all batches for that day are settled at the end of the day.

ACH Reporting

As mentioned previously in this portal, ACH transactions can take several days and sometimes even weeks to update their statuses. As a matter of practice merchants should setup a daily report to check for any ACH statuses that changed, so they can update their own records. To do so, run an RSAPI report using “action_date”. The report will show you the data for all transaction confirmations that were received from the previous day.

Recurring Reporting

Starting with version 3.6.1 of QSAPI, it returns a recurring ID (“recurring_id”) that merchants can use to segment out their recurring transactions from their standard transactions. This extra ID is in addition to the standard transaction ID. For many of our older API users who wish to have recurring IDs shown in an RSAPI report the switch to a newer version can usually be easily accommodated. Contact [email protected] to find out what would need to be modified for an upgrade.

Parsing the Data

The data should be parsed using field names. It should not be based on the incremental position of data rows. Future versions of RSAPI may include new field names or exclude previous field names, and parsing based on incremental values could lead to internal migration complexities for merchants.

Card Capture

Identifying a card brand: Issuer identification numbers are used to identify which card issuing company a particular card belongs to. You can determine this by checking the first few numbers of a credit card.

  • Visa – Starts with 4
  • Mastercard – Starts with numbers 51-55
  • American Express – Starts with 34, 37
  • Discover – Starts with 6011, 622126-622925, 644-649, 65
  • JCB – Starts with 3528-3589

Verifying if a credit card is a valid number prior to submitting a transaction:
All credit card numbers can be proven as being a valid credit card number by running a “Mod 10” or “Luhn algorithm” against a card number. Some merchants choose to verify a card prior to submission, to reduce the number of declined transactions that they receive. This practice is typically handled by a java script. Numerous examples of scripts that handle “Mod 10” can be found on the internet. Bluefin does not require merchants to perform a “Mod 10” check prior to submitting a card.

Error Messages

When coding your applications, please note that the wording on error handling responses are subject to change.

Zero Dollar ($0) Authorizations

When the Merchant issues a $0 authorization thru the API, depending on the end processor, Bluefin may register the $0 authorization but in reality, is sending a $1 authorization to the processor, receiving approval from the processor, passing the approval to the Merchant and at the same time, automatically issuing a reversal of the $1 authorization. So, it is possible that the actual cardholder could see a $1 authorization on their card, even though the authorization was reversed and in effect, cancelled.

URL Encoding

If you do not use the Bluefin PHP class in interacting with the API’s, the data element values that are sent must meet the “URL Encoding” standards.

URL Encoding is the process of converting string(s) into a valid URL format. Valid URL format means that the URL contains only what is termed as "alpha, digit, safe, extra, escape" characters, replacing “unsafe ASCII” characters with a “%” followed by two hexadecimal digits.

URL encoding is normally performed to convert data passed via html forms, because such data may contain special character, such as "/", ".", "#", and so on, which could either: a) have special meanings; or b) is not a valid character for an URL; or c) could be altered during transfer. For instance, the "#" character needs to be encoded because it has a special meaning of that of an html anchor. The space character also needs to be encoded because is not allowed on a valid URL format. Also, some characters, such as "~" might not transport properly across the internet