Request

The Point Of Sale (POS) device posts to QSAPI the following data

Variable Name Max Type Req'd Description
account_id 12 Numeric Yes The Payconex account identification number that you are issued after your account has been setup.
api_accesskey 32 Alphanumeric Yes The secret key that you will be provided when your Payconex account is set up and when you have requested access to QSAPI.
timestamp 19 YYYY-MM-DD HH:MM:SS No If used, MUST be included in a hash for authenticated transactions. See "Appendix: Using HASH for Authenticated Transactions"
tender_type n/a Enumerated Yes The payment tender type that you are submitting. The following enumerated values are allowed: CARD: credit, debit, and check cards EBT: Electronic Benefits Transfer (Elavon only) DEBIT: PIN Debit card only (Elavon/Omaha/North)
transaction_type n/a Enumerated Yes The type of transaction you are requesting, with these enumerated values allowed: SALE: authorizes the funds on the card and flags the transaction to be captured for settlement at the next settlement time. REFUND: refunds a previous sale. If the transaction has not yet been settled, then this results in a void. Otherwise, for Cards only, it results in a credit back on the card. ACH transactions can't be refunded once they are submitted for settlement (NOTE: For actual transaction settlement times, contact Bluefin support). You can specify an amount less than the original sale amount. Requires token_id. BALANCE: request account balance on an EBT/Debit card (Elavon only).
transaction_amount 9 Numeric with decimal Yes This is the dollar (or other currency) amount of the transaction. Only numbers and a single decimal are allowed. Commas are not allowed. The maximum amount is 999999.99. That is 1 cent less than 1 million. This is because the 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_description 65K Character No A description of the payment. This is an open field. If emails are sent to the customer or merchant, this will show in the “Description:” field. You may use this to send any information that you wish. It can store up to 65,000 characters.
card_tracks ? Character Yes/No The characters from the full, un-modified payload. Must be well formed XML string, see “EMV Tag Info” section below (request column)
pin ? Alphanumeric No The encrypted PIN Block portion for PIN debit or PIN EBT transactions. It must be obtained from a PCI PTS/PED Certified device that is injected by Bluefin’s Encryption Service Organization or Key Injection Facility (KIF). This PIN Block may never be stored for any reason.
ksn ? Alphanumeric No The Key Sequence Number (DUKPT) portion for PIN debit, PIN EBT, or EMV transactions. It must be obtained from a PCI PTS/PED Certified device that is injected by Bluefin’s Encryption Service Organization or Key Injection Facility (KIF). The KSN may never be stored for any reason.
ebt_type n/a Enumerated Yes/No For EBT (Electronic Benefits Transfer), the type can be as follows: FOOD: this is for a food sale CASH: this is for a cash sale Required if tender_type=EBT
customer_data 65K Character No Any customer data relevant to the transaction (for semi-integrated only)
cashier * 100 Alphanumeric No The cashier that created the original transaction.
token_id 12 Numeric No 12-digit transaction_id of a previous transaction, when doing a refund. Please see the SLAPI documentation for more information.

Response

The response will be the same as a QSAPI response (see above section on QSAPI Response) with a few differences.

EMV transaction response additionally includes processor’ EMV related data (emv_tags). This data is to communicate to the card’s chip for update.

EMV – contains an XML string of chip related processor response – see “EMV Tag Info” section below (request column, ones marked with an ‘X’)

📘

Note

AppVer parameter of Dvc tag will indicate the following methods: - AppVer=”1.0” (Swipe) - AppVer=”2.0” (Contactless) - AppVer=”2.1” (EMV and Contactless)

Example

card_tracks=’<PAX Ver="2.0"><Dvc App="Bluefin" AppVer="2.1" DvcType="S500" DvcSN="65000111" Entry="EMV"></Dvc><ICC _9f26="000000002000" _9f27="80" _9f37="549F8B9C" _9f36="0001" _95="0480000000" _9c="00" _82="5D80_9f33="E0F8C8" _9f34="5E0300" _9a="160519" _5f2a="840" _9f02="000000002000" _9f03="000000000000" _9f35="22" _5f34="00" _5f24="161130" _9f10="06020103A00000" _9f1a="840"></ICC><Card CEncode="0" ETrk1="670219E5024E11D06EF137DC8F35C89FFAD0FBCC82BE30A29FE152B9F5183A49AF8A5BDF048757C32147F771F099410BDC66035DC7CC0DD3C2E73EFE4CFE6D90" ETrk2="90A52091B09589BE7195CF3787E51DCB1314C7B11BC99028BE4905149DC674F295C687F7D06A3D93" CDataKSN="62994912410000800051" CHolder="FDCS/TEST CHECK CARD" EFormat="0"></Card><Addr></Addr><Tran TranType="CREDIT"></Tran></PAX>’" EFormat="0"></Card><Addr></Addr><Tran TranType="CREDIT"></Tran></PAX>’
emv_tags='<icc _9f36="000B" _5f34="01" EMV_Key_Date="06152016" />'

EMV Tag Info

A list of EMV tags with requirements, lengths and sample data to allow one to build or understand the EMV payloads. Also note if the tag value is included in the response.

TagID Req'd Length Type Sample Value Notes Request Response
9F26 Yes 16 Hex B3CD6686EFC20095 Value returned by the chip (ICC) in response to a “Generate AC” command. X
9F27 2 Hex 80 The Cryptogram Information Data X
9F37 Yes 8 Hex E180229B Value is used to provide variability and uniqueness to the generation of a cryptogram. X
9F36 4 Hex 000B The Application Transaction Counter (ATC) X X
95 Yes 10 Hex 8E+09 Status of the different functions as seen from the terminal. X
9C 2 Numeric 0 Type of financial transaction, represented by the first two digits of the ISO 8583 X
82 4 Hex 1C00 Application interchange profile -- capabilities of the card to support specific function within the app. X
9F33 Yes 6 Hex E0B8C8 Value that indicates the card data input, CVM, and security capabilities of the terminal. X
9F34 Yes 6 Hex 410302 Results of the last Card Verification Method (CVM) performed. X
9A 6 Numeric 100812 Local date that the transaction was authorized (YYMMDD). X
5F2A 3 Numeric 124 Currency code of the transaction according to the ISO 4217 standard. X
9F02 12 Numeric 1000 Authorized amount of the transaction (excluding adjustments). X
9F03 12 Numeric 0 Value is used to indicate a secondary “Cashback” amount associated with the transaction. X
9F35 Yes 2 Numeric 22 Terminal Type X
5F34 2 Numeric 1 The Application PAN Sequence Number (CSN) X X
5F24 Yes 6 Numeric 151231 The Application Expiration Date (YYMMDD) X
9F10 64 Hex 06010A03A48800 The Issuer Application Data X
9F1A 3 Numeric 840 The Terminal Country Code X
8A 2 Alpha The Authorization Response Code X
9F6E 8 Hex Form Factor Indicator X
9F7C 64 Hex The Customer Exclusive Data X
9F6E 64 Hex Third Party Data X
84 32 Hex Dedicated File Name (Application Identifier) X
71 256 Hex The Card Issuer Script Command to be submitted to the Chip card X
72 256 Hex The Card Issuer Script Command to be submitted to the Chip card X
91 32 Hex The Issuer Authentication Data X
8 Numeric 3092016 The date of the last Host EMV Key Update in MMDDYYYY format X

Key Exchange Request

When the POS (Point of Sale) gets the EMV_Key_Date field back from Elavon in a response message, the POS needs to compare that date to the date the POS has stored. If the host date is newer, the POS needs to send to Bluefin an “EMV Key Exchange Request”.

In order to do this, the POS posts to QSAPI the following:

Variable Name Max Type Req'd Description
account_id 12 Numeric Yes The Payconex account identification number that you are issued after your account has been setup.
api_accesskey 32 Alphanumeric Yes The secret key that you will be provided when your Payconex account is set up and when you have requested access to QSAPI.
transaction_type n/a Enumerated Yes The type of transaction you are requesting, with enumerated value of: KEYEXCHANGE
custom_id Yes The value returned in the last response for the "record_number" attribute.

Key Exchange Response
Key exchange response includes

  • transaction_timestamp
  • error
  • error_code
  • error_message
  • emv_tags

📘

Note

emv_tags value is XML string formatted as follow: XML See section below entitled “Key Exchange Attributes” for more detail on returned attributes.

Example

account_id=180000000045&api_accesskey=5f6964d6babeb1d927470931dc68d83c &transaction_type=KEYEXCHANGE&custom_id=0
transaction_timestamp=2016-07-18+12%3A15%3A01 &error=0&error_code=0&error_message=&emv_tags=

Key Exchange Attributes

A list of the Key Exchange Attributes that can be returned in a response as follows:

AttributeID Req'd Length Type Sample Value Notes
Record_Number Optional 4 Numeric 0 Next Request Record Number.
Additional_Key_Available Yes 1 Numeric 1 0 = No more keys to download; 1 = there are more keys available for download.
Data_Type 2 Numeric 1 Type of EMV key. 01 = CA Public Key
RID Yes 10 Alpha A000000003 Registered Application Provider Identifier.
PKI Yes 2 Hex 94 CA Public Key Index
Hash_ID 2 Alpha 1 Hash Algorithm Identifier (01 = default).
Digital_Signature_ID 2 Alpha 1 Digital Signature Algorithm Identifier (01 = default)
Public_Key Yes 496 Hex ACD2B12302… Value of the Public Key
Exponent Yes 6 Alpha 3 Public Key Exponent Value
Check_Sum Yes 40 Hex C4A3C43CCF… CA Public Key Check Sum
CA_Public_Key_Length Yes 2 Hex F8 Length of the Public Key in hex
CA_Public_Key_Exp_Date Yes 6 Numeric 221231 CA Public Key Expiration Date in YYMMDD format
EMV_Key_Date 8 Numeric 6152016 The date of the last Host EMV Key Update in MMDDYYYY format