EMV Data
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:
XMLSee 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 |
Updated over 3 years ago