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 Type | MHDR |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. |
| Account ID | 12-digit PayConex Account Number. |
| API Access Key | 32-character PayConex API Access Key. |
| FI Number | 3-digit Financial Institution Number (optional). |
Token Request Detail (TOKN)
| Record Type | TOKN |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. |
| Token ID | 12-digit PayConex Transaction Token ID. |
| Custom Label | Up 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 Type | CARD |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. |
| Card Number | 13-16-digit Primary Account Number (PAN) from card. |
| Expiration | 4-digit, zero-filled card expiration date [MMYY]. |
| Custom Label | Up 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 Type | FHDR |
|---|---|
| Sequence | 6-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 Date | Date/Time response processed OUT [YYYYMMDDHHMMSS] |
Merchant Header (MHDR)
| Record Type | MHDR |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. |
| Account ID | 12-digit PayConex Account Number. |
Token Response Detail (TOKN)
| Record Type | TOKN |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. Maps directly to the Sequence number in the request file. |
| Response Code | 1-character Elavon AUP response code. |
| New Token ID | 12-digit PayConex Transaction Token ID. |
| Present only if Response Code is "A" or "B". | |
| New Expiration | 4-digit, zero-filled card expiration date [MMYY]. |
| Present only if Response Code is "A" or "B". | |
| New Card Brand | Card brand of new card (Only if Response Code is "A”). |
| New Last 4 | Last 4 of new card (Only if Response Code is "A”). |
| Recurring ID | Recurring Schedule ID(s) touched. |
| Present only if Response Code is "A" or "B". | |
| Old Token ID | Old Token ID (same as one in the matching request record). |
| Old Last 4 | Old card last 4. |
| Custom Label | Optional field. |
Card Response Detail (CARD)
| Record Type | CARD |
|---|---|
| Sequence | 6-digit, zero-filled, incrementing number. Maps directly to the Sequence number in the request file. |
| Response Code | 1-character Elavon AUP response code. |
| New Card Number | 13-16-digit Primary Account Number (PAN) from the card. |
| Present only if Response Code is "A". | |
| New Expiration | 4-digit, zero-filled card expiration date [MMYY]. |
| Present only if Response Code is "A" or "B". | |
| New Card Brand | Card brand of new card (Only if Response Code is "A”). |
| New Last 4 | Last 4 of the new card (Only if Response Code is "A”). |
| Recurring ID | Recurring Schedule ID(s) touched. |
| Present only if Response Code is "A" or "B". | |
| Old Card Number | Old card number (same as one in the matching request record). |
| Old Last 4 | Old card last 4. |
| Custom Label | Optional field. |
Error Response Detail (FAIL)
| Record Type | FAIL |
|---|---|
| Row ID | 6-digit number. Maps directly to the physical row in the request file. |
| Sequence | 6-digit, zero-filled number. Maps directly to the Sequence number in the request file. |
| Response Type | "pass" or "fail". |
| Response Date | Date/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.
| CODE | RESPONSE | DESCRIPTION |
|---|---|---|
| A | Match - Update PAN | New account number and expiration date. Use going forward. |
| B | Match - Update Expiry | New expiration date, same account number. Use going forward. |
| C | Match - Closed | Account is marked as closed. Cardholder should be contacted. |
| D | Match - Contact Cardholder | Unknown reason and cardholder should be contacted. |
| E | Match - No Change | No update and it matches, so continue to use. |
| F | No Match - BIN in range | No match to the data provided. |
| G | No Match - BIN out of range | No match to the data provided. |
| H | Error - Non-numeric PAN | Bad PAN data (not valid characters or format). |
| I | Error - Failed Luhn | Does not match a Luhn (Mod 10) check (not a valid card value). |
| J | Error - Invalid Expiry | Expiration date was not properly formatted. |
| K | Error - Invalid MID | MID for the file is incorrect. |
Updated over 2 years ago