Bulk Import Tool

Bluefin PayConex features a web-based virtual terminal that merchants can use to process transactions from any PC, any time, including from our encrypted mobile or POS swipe solutions, with reporting and account management.

Merchants can also use our comprehensive set of APIs (fully loaded payment gateway) that offer debit/credit card and ACH processing, recurring and subscription billing, electronic check acceptance, and security features such as tokenization and transparent redirection.

Merchants can also use Bluefin’s batch file processing method, which allows for “bulk” processing of credit card transactions (authorization, sale, refund, capture, reissue, and recurring) and also ACH transactions (checking, savings, and recurring) through the Bluefin PayConex gateway to your merchant account.

Introduction

When using the Bluefin batch file processing feature, the merchant generates a comma separated value file (CSV) and uploads it to a designated location supplied by Bluefin on account set-up.

The file that is generated and uploaded, for maximum protection, should be PGP encrypted before uploading to Bluefin. Valid file extensions if PGP encrypted are .pgp, .gpg, and .asc. It is not a requirement to use PGP encryption, but it is best practice to do so. If the merchant chooses to not use PGP encryption, the file extension should be .csv. Files with extensions other than those listed will not be processed.

When the merchant account is set-up to allow batch file uploading, there will be two directories created for the merchant account; an IN directory, and an OUT directory. Access for these directories and file uploads/downloads will be through the following URL:
https://sftp.cardconex.com/

Incoming files will be “dropped” in to the appropriate IN directory, and the result file created after processing will be placed in to the OUT directory by the Bluefin batch file process.

The IN directory will follow the following “path” scheme for certification (testing):
/Batch-Cert/IN/<account_number>

And the OUT file will be similar, like the following:
/Batch-Cert/OUT/<account_number>

When the merchant has tested the batch file processing system thoroughly, for live processing the directory structure would change to the following, but not that if it is used, the data in the files WILL be processed in production.
/Batch-Prod/IN/<account_number>

Timing

Bluefin checks the IN folders for new files every minute, so there is no real delay in processing the file contents from that standpoint. The time it takes to complete the entire batch file process can vary greatly and involves many factors.

  • One factor that influences the time to process a file is the number of transactions in the file itself.
  • A second factor is the type of transaction, whether it is a credit card transaction, or and ACH (check) transaction.
  • The last factor to consider is how busy the server actually is when processing the files. If you upload several at a time, the server will attempt to process them at the same time, and thus might be a bit slower in accomplishing the task. Currently, from rough estimates, 1000 credit card transactions take approximately 20 minutes to process, and 1000 ACH ones take approximately 7 minutes to process.

Request File Structure

The file must be a comma separated value (CSV) file and be conform to format described below.

📘

TIP

Check out the “Bluefin Bulk File Example” Excel file and use it as a model of the required format to follow.

Click here to download the "Bluefin Bulk File Example"

The file structure must contain a header row, the transaction rows, and a footer row. The file must have ALL fields (columns) indicated in the example file, in each row. Some fields are “optional”, but they MUST be included (empty or as “null” values).

If the file structure is not correct, the file will be rejected and NONE of the transactions in it will be processed.

If the file contains fields that are the wrong data format, the file will be rejected and NONE of the transactions in it will be processed.

Header Line

The header row must be the first row of the submitted CSV file, must have these fields, in order, starting with field (column) #1:

Variable NameMaxTypeReq'dDescription
row_type3CharacterYesThis is the type of data in the row. For the header row, this value must be HDR
account_id12NumericYesThis is the Payconex account identification number that you are issued after your account has been setup.
api_access_key32AlphanumericYesThis is a secret key that you will be provided when your Payconex account is set up and when you have requested access to QSAPI.
batch_date10DateYesDate the batch was generated. MUST be in YYYY-MM-DD format.

Footer Line

The footer row must be the last row of the submitted CSV file, must have these fields, in order, starting with field (column) #1:

Variable NameMaxTypeReq'dDescription
row_type3CharacterYesThis is the type of data in the row. For the footer row, this value must be FTR
batch_count6NumericYesThis the total number of transactions specified in the file.
batch_total9Numeric with decimalYesThis is the total dollar amount of all transactions listed in the file. Only numbers and a single decimal are allowed. Commas are NOT allowed. The maximum amount is 999999.99 (decimal is counted in the max size). Values with no decimal and no cents are allowed. Values with only a single number after the decimal are allowed and will be assumed to have a trailing 0.

Transaction Lines

The transaction rows (in between header and footer rows) in the submitted CSV file must have these fields, in order, starting with field (column) #1.

Variable Name Max Type Req'd Description
row_type 3 Alphanumeric Yes This is the type of data in the row. For transaction rows, this value must be TX
uid 40 Alphanumeric Yes This is a unique identifier. Each row MUST be unique.
transaction_type n/a Enumerated Yes This is the type of transaction you are requesting. The following enumerated values are allowed.
AUTHORIZATION: authorizes the funds on the card, but does not transfer the funds.
SALE: authorizes the funds on the card and marks the transaction to be captured for settlement at next settlement time.
REFUND: refunds a previous sale. If the transaction has not yet been settled, this results in a void. Otherwise, it results in a credit back to the card or bank account. Requires token_id.
CREDIT: puts money onto a card or into a bank with no offsetting sale. Turned off by default (contact Bluefin support).
CAPTURE: flags a previous AUTHORIZATION to be captured for settlement at next settlement time. Requires token_id.
STORE: stores credit card/ach account info for later use.
FORCE: forces through a transaction. A 6 digit authorization_code must also be provided.
token_id 12 Numeric No 12 digit transaction_id of a previous transaction. The token_id is used for reissues, refunds, and recurring transaction creation.
method 1 Alphanumeric Yes This is the method you wish to perform, with valid values being:
C - Credit Card
A - ACH
T - Token
tender_type n/a Enumerated Yes This is the payment tender type that you are submitting. The following enumerated values are allowed:
CARD: credit, debit, or check
ACH: ACH , EFT, or electronic check
EBT: USDA FNS, Electronic Benefits Transfer
GIFT: gift card or stored value card
card_number 16 Numeric Yes/No The card number with no spaces, dashes, or hyphens. REQUIRED if method = C.
card_expiration 4 Numeric Yes/No The card expiration date in the format of MMYY. No hyphens, dashes, spaces, or slashes. REQUIRED if method = C.
bank_routing_number 9 Numeric Yes/No The bank routing (ABA) number. REQUIRED if method = A.
bank_account_number 26 Numeric Yes/No The bank account (DDA) number. REQUIRED if method = A.
check_number 15 Numeric No The number of the check used for electronic checks that are processed via ACH.
ach_account_type n/a Enumerated No This is the type of bank account for ACH/electronic check transactions. It will default to checking if none is specified. The allowed values are:
CHECKING: checking account
SAVINGS: savings account
ach_sec_code n/a Enumerated No This is the Standard Entry Class (SEC) code that is required for ACH/echeck transactions. If no SEC code is provided, the default that is set up for the account is used. Please note that if you provide an SEC Code here that the account is not underwritten for, the bank will decline the transaction. Acceptable types are:
CCD: Cash Concentration or Disbursement. This is the default type for corporations. Requires a signature.
PPD: Prearranged Payment & Deposit. Requires a signature.
WEB: Web-originated, ecommerce transactions.
TEL: Telephone-initiated transactions. Voice recording required.
POP: Point-of-Purchase, in-person transaction.
ARC: Accounts Receivable. This is for converting a check into an electronic ACH transaction.
RCK: Re-presented Check. This is used to present a declined check an additional time.
DEF: This can be sent to tell Payconex to use the default ACH SEC code. Sending nothing will result in the same action.
ach_opcode n/a Enumerated No For processor-specific ACH features. 01, 02, 03, S, R
amount 9 Numeric with decimal Yes This is the dollar amount of the transaction. Only numbers and a single decimal are allowed. Commas are NOT allowed. The maximum amount is 999999.99 (decimal is counted in the max size). Values with no decimal and no cents are allowed. Values with only a single number after the decimal are allowed and will be assumed to have a trailing 0.
authorization_code 6 Alphanumeric Yes/No For credit/debit cards, this is the 6 digit authorization code from a previously authorized transaction. Required when transaction_type=FORCE.
reissue 1 Boolean No If set to 1, this creates a new transaction based on the cardholder data from a previous transaction. The transaction_id from the transaction that you would like to use as a template for the reissue is required to be sent through the token_id variable. The dollar amount can be changed as well as expiration date, name, description and other variables.
payment_type n/a Alpha No Type of payment. Valid values are:
INSTALLMENT
RECURRING
ECOMMERCE
MOTO
payment_number 100 Numeric No This is the payment number. Only used if payment_type=INSTALLMENT
total_payments 100 Numeric No This is the total number of payments. Only used if payment_type=INSTALLMENT
group 12 Alphanumeric No Groups are flexible groups that can be used for various reasons, including: a) to assign transactions to a specific grouping that you wish; or b) to direct transactions to separate back-end merchant accounts or depository accounts.
cashier 100 Character No This is the name or id of the cashier that is submitting the transaction. This is shown with Payconex transaction details as the originator of the transaction. You may use any designation you wish. Good choices are the user name of the POS clerk, email address, or the name of the application that is connecting.
order_id 25 Alphanumeric No This property is used to specify an order number to identify the purchase or service.
level2_tax ??? Alphanumeric No Used exclusively for level 2 transactions. REQUIRED for level 2 transactions. For Visa cards, value must be expressed as greater than 0.00, for Mastercard value may be expressed as 0.00 if desired.
level2_zip 10 Numeric with hyphen No Used exclusively for level 2 transactions. REQUIRED for level 2 transactions and it is probably the same value as the "zip" variable value. This value is not validated like the "zip" variable value, so any alphanumeric value up to 10 digits is valid.
level2_orderid 10 Numeric No Used exclusively for level 2 transactions. Merchant determines any custom alphanumeric value.
level2_merchant_reference 15 Alphanumeric No Used exclusively for level 2 transactions. Required for level 2 transactions. Merchant determines the custom value.
first_name 50 Character Yes/No Card: This is the first name of the cardholder as it appears on the front of the card. It is not required for cards.
ACH: This is the first name of the account holder as it appears on the front of the check or bank statement. It is required by NACHA to provide first and last name.
last_name 50 Character Yes/No Card: This is the last name of the cardholder as it appears on the front of the card. It is not required for cards.
ACH: This is the last name of the account holder as it appears on the front of the check or bank statement. It is required by NACHA to provide first and last name.
street_address1 50 Character No Street address of the card or account holder.
street_address2 50 Character No Suite or other part of an address. Not sent to the processor.
city 100 Character No The city portion of the cardholder or accountholder address. This is not sent to the processor.
state 2 Alphabetic No The two digit state code of the cardholder or account holder address. This is not sent to the processor.
zip 10 Numeric with hyphen No The 5 digit format or 5+4 formatted zip code of the cardholder or accountholder. For example, 12345 or 12345-1234. Only numbers and a hyphen are allowed.
INTERNATIONAL: Can contain any combination of letters or numbers, and either a space or a hyphen.
country 2 Alphabetic No This is the two character country code for the cardholder/account holder: http://www.iso.org/iso/country_codes
phone 20 Alphanumeric No This is the phone number for the cardholder/account holder. It is not sent to the processor, and is stored only for your reporting use.
email n/a Character No This is the email address of the cardholder/account holder. It does not expect any specific format, is not sent to the processor, and is stored only for your reporting use or sending email receipts.
ip_address 15 NNN.NNN.NNN.NNN No IP address of the client which initiated the transaction.
custom_id 50 Character No This is a custom identifier that can be used for any purpose you wish. For some processors (such as Paymentech), this ID is passed through to the processor and available in their reporting. This can ease syncing up reporting.
transaction_description 256 Character No A description of the payment. This is an open field that can be used to send any information that you wish.
custom_data 256 Character No An open variable. Many developers use this variable to transmit structured data formats or serialized variables. You can send through many variable=value pairs through this single variable.

Download Bluefin Bulk File Example here

Response File Format

Normally, your files will process successfully and you will receive a CSV file response (in your OUT directory), for your records. The variables and values returned in the file will follow the list below:

Variable Name Max Type Description
id 12 NumericThe transaction id for the new transaction. When using tokenization, this is the transaction_id that you submit as the token_id.
batch_id 12 Numeric Will be returned for refunds. This is the original transaction_id of the Sale transaction that was refunded.
uid 40 Alphanumeric The UID that was submitted in the file.
transaction_timestamp 19 YYYY-MM-DD HH:MM:SS This is the timestamp of the newly created transaction.
transaction_id 12 Numeric The transaction id for the new transaction.
original_transaction_id 12 Numeric Will be returned for refunds. This is the original transaction_id of the Sale transaction that was refunded.
tender_type n/a Enumerated This will be the same as the tender_type provided in the request.
transaction_type n/a Enumerated This is the type of transaction you requested.
card_brand n/a Enumerated VISA, MASTERCARD, AMERICAN EXPRESS, DISCOVER, ACH, EBT
transaction_amount 9 Numeric with decimal The same variable submitted in the request. If a partial auth is valid, this represents the actual amount authorized.
last4 4 Numeric The last four digits of the card number or Primary Account Number (PAN). For ACH, it is the last four digits of the account number.
card_expiration 4 Numeric The month and year of the card expiration date in the format MMYY. For example, 0115 for January 2015.
authorization_code 6 Alphanumeric This is the auth code returned by the processor.
authorization_message 50 Alphanumeric APPROVED or the auth message from the processor (e.g. AUTH DECLINED 200).
avs_response 1 Enumerated A single letter address verification response:
DFJMQVXY - Address and ZIP code match
LWZ - ZIP code match, address is wrong
ABOP - Address match, ZIP code is wrong
KN - No match, address and ZIP is wrong
U - No data from issuer/banknet switch
R - AVS System unable to process
S - Issuing bank does not support AVS
E - Error, AVS not supported for your business
C - Invalid address and ZIP format (International)
I - Address not verifiable (International)
G - Global non-verifiable address (International)
? - Unrecognized codes (none of the above)
_ No AVS data (blank)
custom_id 50 Character The same variable submitted in the request.
error 1 Boolean True for error conditions or decline.
error_code 5 Numeric 0 for no error, > 0 for error number.
error_message ? Character DECLINED or textual description of other API errors (e.g., “Must send card_number” or “Invalid bank_account_number”).
transaction_approved 1 Boolean True for approved.
ip_address 15 NNN.NNN.NNN.NNN IP address of the client which initiated the transaction.
first_name 50 Character The same variable submitted in the request.
last_name 50 Character The same variable submitted in the request.
custom_data 256 Character The same variable submitted in the request.
transaction_description 256 Character The same variable submitted in the request.

Receiving the above file does not necessarily mean that all transactions were successful. Some of them may have not processed correctly, or not as intended.

It is always recommended to check the file, noting variables like “authorization_message”, “avs_response”, “error”, “error_code”, and “error_message” for more information.

If the file was NOT processed at all (none of the transactions were processed), you will receive a file (in your OUT directory) with the following name convention: error_{original file name}.csv

In the error file will be a variable explaining the reason that none of the transactions were processed.

Typically, it is because the account information submitted was incorrect, the footer value does not agree with the transaction row summation, or the fields are of the wrong format.