Merchant File Specifications

The Account Updater tool works by sending a request file to Bluefin via a secure FTP connection and receiving a response file with the update in the same manner.

All files passed back and forth between the merchant and PayConex are formatted as comma-separated values (.CSV).

📘

Note

These files are CSV files, as they have comma separated values, but they contain header lines that have a different number of fields than the rest of the file.

Request File Format

Request files consist of one or more Merchant Groups.

A merchant group consists of a Merchant Header (MHDR) record and one or more Card Detail (CARD) and/or Token Detail (TOKEN) records.

Each record holds on its own line and contains a Sequence number which is required to be consecutive numbers.

The same file can contain multiple Merchant Groups, but we recommend using separate files for separate merchants, as any one error in the file will result in the entire file being rejected.

Merchant Header (MHDR)

Record TypeMHDR
Sequence6-digit, zero-filled, incrementing number.
Account ID12-digit PayConex Account Number.
API Access Key32-character PayConex API Access Key.
FI Number3-digit Financial Institution Number (optional).

Token Request Detail (TOKN)

Record TypeTOKN
Sequence6-digit, zero-filled, incrementing number.
Token ID12-digit PayConex Transaction Token ID.
Custom LabelUp to 50 characters, Custom Label field used for reference (optional).
*Note: only - A-z0-9 characters are allowed and the first and last character must be alphanumeric A-z0-9 only.

Card Request Detail (CARD)

Record TypeCARD
Sequence6-digit, zero-filled, incrementing number.
Card Number13-16-digit Primary Account Number (PAN) from card.
Expiration4-digit, zero-filled card expiration date [MMYY].
Custom LabelUp to 50 characters, Custom Label field used for reference (optional).
Note: only - A-z0-9 characters are allowed and the first and last character must be alphanumeric A-z0-9 only.

🚧

Caution

If the file has trailing spaces at the ends of lines, the file will be rejected, as these extra spaces would be read as being part of the Custom Label which does not accept spaces as a last character.

Example Request File

MHDR,000001,120614961789,8e62677abc4a73af0086ba2ffb65e482
    CARD,000002,4503300000001238,1218,Ref ABC
    CARD,000003,5415244444444444,1222,Ref XYZ
    CARD,000004,5424180001234506,1218, 
    CARD,000005,4002960001111116,0416, 
    CARD,000006,4005571701111111,0416, 
    CARD,000007,5424180011113336,1218,Ref 123 
    CARD,000008,4159282222222221,1215,
    ...
    CARD,000032,4124939999999990,1215, 
    MHDR,000033,120614961797,0334eebb71418c7d23aed96970d0d6e8 
    TOKN,000034,000000143347,Ref ABC 
    TOKN,000035,000000114608,
    TOKN,000036,000000142160,
    TOKN,000037,000000116520,Ref 123 
    TOKN,000038,000000125027,Ref XYZ

Response File Format

Response files mirror the Request files. For every record in the Request file, there will be a matching record in the Response file. The columns DO differ, however.

File Header (FHDR)

Record TypeFHDR
Sequence6-digit, zero-filled number. Always "000000"
Response Type"pass" or "fail". A response type of “fail” indicates that the request file had errors in it that caused it to be rejected. The extension on the response file name will be “.ERR”
Response DateDate/Time response processed OUT [YYYYMMDDHHMMSS]

Merchant Header (MHDR)

Record TypeMHDR
Sequence6-digit, zero-filled, incrementing number.
Account ID12-digit PayConex Account Number.

Token Response Detail (TOKN)

Record TypeTOKN
Sequence6-digit, zero-filled, incrementing number. Maps directly to the Sequence number in the request file.
Response Code1-character Elavon AUP response code.
New Token ID12-digit PayConex Transaction Token ID.
Present only if Response Code is "A" or "B".
New Expiration4-digit, zero-filled card expiration date [MMYY].
Present only if Response Code is "A" or "B".
New Card BrandCard brand of new card (Only if Response Code is "A”).
New Last 4Last 4 of new card (Only if Response Code is "A”).
Recurring IDRecurring Schedule ID(s) touched.
Present only if Response Code is "A" or "B".
Old Token IDOld Token ID (same as one in the matching request record).
Old Last 4Old card last 4.
Custom LabelOptional field.

Card Response Detail (CARD)

Record TypeCARD
Sequence6-digit, zero-filled, incrementing number. Maps directly to the Sequence number in the request file.
Response Code1-character Elavon AUP response code.
New Card Number13-16-digit Primary Account Number (PAN) from the card.
Present only if Response Code is "A".
New Expiration4-digit, zero-filled card expiration date [MMYY].
Present only if Response Code is "A" or "B".
New Card BrandCard brand of new card (Only if Response Code is "A”).
New Last 4Last 4 of the new card (Only if Response Code is "A”).
Recurring IDRecurring Schedule ID(s) touched.
Present only if Response Code is "A" or "B".
Old Card NumberOld card number (same as one in the matching request record).
Old Last 4Old card last 4.
Custom LabelOptional field.

Error Response Detail (FAIL)

Record TypeFAIL
Row ID6-digit number. Maps directly to the physical row in the request file.
Sequence6-digit, zero-filled number. Maps directly to the Sequence number in the request file.
Response Type"pass" or "fail".
Response DateDate/Time response processed OUT [YYYYMMDDHHMMSS].
FHDR,000000,pass,20151223152623
    MHDR,000001,120614961789 
    CARD,000002,A,4862345634563454,1221,VISA,3454,,4503300000001238,1238,Ref ABC 
    CARD,000003,E,,,,,,,,
    CARD,000004,G,,,,,,,,
    CARD,000005,G,,,,,,,,
    CARD,000006,B,,0419,,,,,,
    CARD,000007,G,,,,,,,,
    CARD,000008,B,,1220,,,,,,
    ...
    CARD,000032,A,4862111122223336,1218,VISA,3336,,4503300000001238,1238, 
    MHDR,000033,120614961797
    TOKN,000034,B,,0520,,,,,,
    TOKN,000035,C,,,,,,,,
    TOKN,000036,E,,,,,,,,
    TOKN,000037,B,,1022,,,,,, 
    TOKN,000038,A,000000164422,1221,MASTERCARD,4784,,200003016401,4784,Ref XYZ ...

Response File Match Table

In the response file, the third element of the TOKEN or CARD response will have a letter that corresponds to the following table. The actual response Bluefin receives is included along with a brief description of the merchant’s actions.

If a TOKEN was included by the merchant in their request file, match codes A and B will be updated by Bluefin accordingly.

CODERESPONSEDESCRIPTION
AMatch - Update PANNew account number and expiration date. Use going forward.
BMatch - Update ExpiryNew expiration date, same account number. Use going forward.
CMatch - ClosedAccount is marked as closed. Cardholder should be contacted.
DMatch - Contact CardholderUnknown reason and cardholder should be contacted.
EMatch - No ChangeNo update and it matches, so continue to use.
FNo Match - BIN in rangeNo match to the data provided.
GNo Match - BIN out of rangeNo match to the data provided.
HError - Non-numeric PANBad PAN data (not valid characters or format).
IError - Failed LuhnDoes not match a Luhn (Mod 10) check (not a valid card value).
JError - Invalid ExpiryExpiration date was not properly formatted.
KError - Invalid MIDMID for the file is incorrect.