Card Present
To support Card Present transactions additional data is required to identify the terminal and provide additional data required by Swipe, Chip and Contactless transactions.
In additional to the basic field requirements in the TransactDirect API Guide the following fields are available to support Card Present transaction processing.
Card Present transaction requires independent acquirer approval. Contact Monek Support for further information.
Card Present Request Fields
| Field Name | Description | Req'd | Size | Type |
|---|---|---|---|---|
| TerminalId | An 8-digit number indicating the unique terminal identifier. | M | 8 | N |
| MessageNumber | A 4-digit number indicating the current receipt number for the terminal. | M | 4 | N |
| TransactionTime | Original local transaction date and time in ISO 8601 format. | M | V | A |
| CardDetail | Structured field containing keyed, swiped, chip, or contactless card data. | M | Max 40 | A |
| KSN | Key Serial Number used in conjunction with DUKPT encrypted card details. | O | 20 | A |
| IccData | Structured field containing ICC request data as defined by EMV. | O | V | A |
| AuxiliaryData | Structured field containing APACS auxiliary request data as defined in APACS Standard 70. | O | V | A |
TerminalId
An 8-digit number value denoting the unique terminal identity number. Each payment terminal should be given a unique Terminal Identifier (TID).
Can be allocated by Monek or specified by hardware vendor.
Structure of Terminal Identifier field
| Digits | Description |
|---|---|
| 1 to 4 | RID - Registered Identifier (Identifies the organisation) |
| 5 to 8 | UID - Unit Identifier (Identifies the terminal) |
MessageNumber
A 4-digit number indicating the current receipt number for the terminal. Used in conjunction with the Terminal Identifier.
Note: Number must be 4 digits and should be zero padded where necessary.
TransactionTime
Original local transaction date and time in ISO 8601 format.
e.g. 2017-10-17T12:00:00
CardDetail
Base64 encoded representation of the DUKPT encrypted card information block. Used in conjunction with the KSN field.
Card Detail contents vary based on the card details mode of entry. The mode of entry used for card details must be applicable for the message type. For example, a message type denoting a swiped transaction must provide card details in the form of a magnetic stripe read.
Additional cardholder information can be supplied in the optional Customer Detail record.
Structure of card information data
The contents of this structure should be DUKPT encrypted and transmitted in Base64 encoded form.
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1 | Card Detail record. Any of the standard Card Detail formats are supported | M | Max 40 | A |
| 2 | Record Separator (ASCII RS) | O | 1 | |
| 3 | Cardholder Detail record. Optional cardholder information. | O | Max 245 | A |
Card Detail Record – Magnetic stripe read – Track 2 data
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1.1 | Unaltered contents of magnetic stripe track 2 (must include checksum and sentinels) | M | Max 40 | A |
Card Detail Record – Manually keyed
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1.1 | Unit Separator (ASCII US) | M | 1 | |
| 1.2 | Card Number | M | Max 25 | N |
| 1.3 | Unit Separator (ASCII US) | M | 1 | |
| 1.4 | Expiry Date (YYMM) | M | 4 | N |
| 1.5 | Unit Separator (ASCII US) | O | 1 | |
| 1.6 | Issue Number | O | Max 2 | N |
| 1.7 | Unit Separator (ASCII US) | O | 1 | |
| 1.8 | Start Date (YYMM) | O | 4 | N |
Card Detail Record – ICC supplied equivalent Track 2 data
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1.1 | ICC Track 2 Data | M | Max 37 | A |
| 1.2 | Unit Separator (ASCII US) | M | 1 | |
| 1.3 | ICC Application PAN Sequence Number | O | Max 2 | N |
Card Detail Record – ICC supplied equivalent manually keyed
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1.1 | ICC Card Number | M | Max 19 | N |
| 1.2 | Unit Separator (ASCII US) | M | 1 | |
| 1.3 | ICC Expiry Date (YYMM) | M | 4 | N |
| 1.4 | Unit Separator (ASCII US) | O | 1 | |
| 1.5 | ICC Sequence Number | O | 2 | N |
Cardholder Detail Record
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 3.1 | Unit Separator (ASCII US) | M | 1 | |
| 3.2 | Postcode | O | Max 10 | A |
| 3.3 | Unit Separator (ASCII US) | O | 1 | |
| 3.4 | Address | O | Max 100 | A |
| 3.5 | Unit Separator (ASCII US) | O | 1 | |
| 3.6 | Cardholder Name | O | Max 50 | A |
| 3.7 | Unit Separator (ASCII US) | O | 1 | |
| 3.8 | Telephone | O | Max 30 | A |
| 3.9 | Unit Separator (ASCII US) | O | 1 | |
| 3.10 | Email Address | O | Max 50 | A |
KSN
This field is used for a transaction where DUKPT (Derived Unique Key Per Transaction) encryption is supported and must be formatted as a 20-digit Hexadecimal string. e.g.
FFFF9876543210E10004
When a KSN is supplied the CardDetail field will always be treated as base64 encoded DUKPT encrypted data.
IccOptions
This field is used to indicate certain card present processing events not identifiable from the standard transaction data.
This field should be presented as a comma delimited list of all applicable value. e.g. in a swiped fallback scenario with cardholder signature you would send:
FB,SV
ICC Option Codes
| Code | Description |
|---|---|
| CF | Indicates communications failure prevented the transaction being authorised online. Note: Transactions must be submitted as PAYMENT_ONLY_ |
| FA | Indicates the transaction was authorised offline, e.g. Contactless Note: Transactions must have the AuthorisationCode field populated with the authorisation code supplied by the card/terminal. |
| FB | Indicates an ICC transaction was attempted by could not complete, and that the transaction was processed as Swiped Fall-back |
| FN | Indicates the transaction should be processed without Monek carrying out expiry date or LUHN checking. Note: Only be used for certain card types as advised by your acquirer |
| XR | Indicates the transaction was an authorisation following a referral. Note: Transactions must be labelled as PAYMENT_ONLY_ and have the AuthorisationCode field populated with the authorisation code supplied by the issuer/acquirer. |
IccData
This field is used for an ICC transaction where the card details have been read from the card's integrated circuit card. Defined in EMV and is as follows:
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1 | Application Cryptogram - Tag 9F26 | M | 16 | A |
| 2 | Application Interchange Profile (AIP) - Tag 82 | M | 4 | A |
| 3 | Application Transaction Counter (ATC) - Tag 9F36 | M | 4 | A |
| 4 | Unpredictable Number - Tag 9F37 | M | 8 | A |
| 5 | Terminal Verification Result (TVR) - Tag 95 | M | 10 | A |
| 6 | Cryptogram Transaction Type - Tag 9C | M | 2 | N |
| 7 | Issuer Application Data (IAD) - Tag 9F10 | M | max64 | A |
| 8 | Unit Separator (ASCII US) | M | 1 | |
| 9 | Application Identifier (AID) - Tag 9F06 | M | max 32 | A |
| 10 | Unit Separator (ASCII US) | M | 1 | |
| 11 | Terminal Application Version Number - Tag 9F09 | M | 4 | A |
| 12 | Unit Separator (ASCII US) | M | 1 | |
| 13 | Cryptogram Information Data - Tag 9F27 | M | 2 | A |
| 14 | Unit Separator (ASCII US) | M | 1 | |
| 15 | CVM Results - Tag 9F34 | M | 6 | A |
| 16 | Record Separator (ASCII RS) | M | 1 | |
| 17 | Application Usage Control - Tag 9F07 | M | 4 | A |
| 18 | Application Version - Tag 9F08 | M | 4 | A |
| 19 | Transaction Status Information - Tag 9B | M | 4 | A |
| 20 | Terminal Type - Tag 9F35 | M | 2 | A |
| 21 | Terminal Capabilities - Tag 9F33 | M | 6 | A |
| 22 | POS Entry Mode – Tag 9F39 | M | 2 | A |
| 23 | Record Separator (ASCII RS) | C1 | 1 | |
| 24 | Reason On-line Code - Vendor specific tag | C1 | 2 | N |
AuxiliaryData
This field is used for transactions where APACS auxiliary request data is required. Field format should follow the APACS Standard 70 specification as defined in Book 2 Appendix B.
Auxiliary data field format
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| A | Auxiliary Data Terminal Capabilities. 1 if Auxiliary Response Data is supported; otherwise 0. | M | 1 | N |
| B | Auxiliary Data Message Size Limit.Fixed: 0480 | M | 4 | N |
| C.1 | 1st Auxiliary Data Record | O | V | A |
| C.2 | 2nd Auxiliary Data Record | O | V | A |
| C.N | nth Auxiliary Data Record | O | V | A |
Auxiliary data record format
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| A | Record Separator (ASCII RS) | M | 1 | |
| B | Data record type | M | 2 | A |
| C | Data record sub-type | M | 2 | N |
| D.1 | Group Separator (ASCII GS) | M | 1 | |
| E.1 | 1st data element as defined by data record type | M | V | A |
| D.N | Group Separator (ASCII GS) | O | 1 | |
| E.N | Nth data element as defined by data record type | O | V | A |
Card Present Response Fields
| Field Name | Description | Req'd | Size | Type |
|---|---|---|---|---|
| IccData | Structured field containing ICC response data as defined by EMV. | O | V | A |
| AuxiliaryData | Structured field containing APACS auxiliary response data as defined in APACS Standard 70. | O | V | A |
IccData
This field is used for an ICC transaction where the card details have been read from the card's integrated circuit card. Defined in EMV and is as follows:
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| 1 | Issuer Authentication Data - Tag 91 | M | Max 32 | A |
| 2 | Unit Separator (ASCII US) | O | 1 | |
| 3 | Issuer Script Data – Tag 71 or Tag 72 | O | Max 256 | A |
AuxiliaryData
This field is used for transactions where APACS auxiliary response data is required. Field format should follow the APACS Standard 70 specification as defined in Book 2 Appendix B.
Auxiliary data field format
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| A.1 | 1st Auxiliary Data Record | O | V | A |
| A.2 | 2nd Auxiliary Data Record | O | V | A |
| A.N | nth Auxiliary Data Record | O | V | A |
Auxiliary data record format
| No | Field Name and Contents | Req'd | Size | Type |
|---|---|---|---|---|
| A | Record Separator (ASCII RS) | M | 1 | |
| B | Data record type | M | 2 | A |
| C | Data record sub-type | M | 2 | N |
| D.1 | Group Separator (ASCII GS) | M | 1 | |
| E.1 | 1st data element as defined by data record type | M | V | A |
| D.N | Group Separator (ASCII GS) | O | 1 | |
| E.N | Nth data element as defined by data record type | O | V | A |
Base Derivation Key
The DUKPT base derivation key (BDK) for all test merchants is:
C1D0F8FB4958670DBA40AB1F3752EF0D
Message Types
Message types consist of the transaction type and card capture method. The following message type are applicable for card present transactions.
For all Contactless transactions use the _CHIP message type.
| Message Type | Description |
|---|---|
| SALE_CHIP | Sale transaction, card details read from ICC at point of sale. |
| SALE_SWIPED | Sale transaction, card details read from magnetic stripe at point of sale |
| SALE_KEYED | Sale transaction, card details keyed at point of sale |
| SALE_CNP_MO | Sale transaction, cardholder not present, mail order |
| SALE_CNP_TO | Sale transaction, cardholder not present, telephone order |
| SALE_CASHBACK_CHIP | Sale transaction with cash back, card details read from ICC at point of sale |
| SALE_CASHBACK_SWIPED | Sale transaction with cash back card details read from magnetic stripe at point of sale |
| SALE_CASHBACK_KEYED | Sale transaction with cash back, card details keyed at point of sale |
| REFUND_CHIP | Refund transactions, card details read from ICC at point of sale |
| REFUND_SWIPED | Refund transactions, card details read from magnetic stripe at point of sale |
| REFUND_KEYED | Refund transaction, card details keyed |
| REFUND_CNP | Refund transaction, cardholder not present |
| REVERSAL_CHIP | Cancellation of earlier Chip & PIN transaction |
| REVERSAL_SWIPED | Cancellation of earlier card swiped transaction |
| REVERSAL_KEYED | Cancellation of earlier card keyed transaction |
To prevent duplicate authorisations the PAYMENT_ONLY_ prefix should be used when sending transacitons in the following scenarios:
- A Chip & PIN transaction that has been authorised off-line
- Manual authorisation following a referral
- Real time communication has failed.
e.g. When sending a transaction where real time communication has failed
MessageType=PAYMENT_ONLY_SALE_CHIP
IccOptions=CF
Reason Online Code
From the APACS Standard 70 Book 2 the Reason Code should be populated as follows:
| Code | Description | Example Conditions |
|---|---|---|
| 00 | IC application common data file unable to process | Only used by IC/MSR terminals where the terminal has possession of the card and when this condition can be accurately identified |
| 01 | IC application, application data file unable to process | Only used by integrated IC/MSR terminals where the terminal has possession of the card and when this condition can be accurately identified |
| 02 | IC random selection | Not Used |
| 03 | Terminal random selection | 'Transaction selected randomly for real-time processing' bit set in TVR (i.e. byte 4, bit 5) |
| 04 | Terminal not able to process IC | Fallback for IC |
| 05 | Real-time forced by IC | IC forced real-time, no bits set in TVR |
| 06 | Real-time forced by card acceptor | Card used twice Max times per day One in 'n' authorisation PAN key entry authorisation. Transaction type authorisation. Exclusion band checks. Pre-valid card |
| 07 | Real-time forced by terminal | Not used |
| 08 | Real-time forced by terminal | TVR indicates real-time required |
| 09 | Real-time forced by card issuer | Expired card. New card. Service code. Hot card |
| 10 | Over floor limit | Above floor limit |
| 11 | Card acceptor suspicious | Force authorisation (NO at signature check). Card returns an inappropriate cryptogram |
Terminal Type Codes
Code indicating the terminal's capabilities sent as 4-digit hexadecimal value. e.g. F186 for a standard attended terminal.
The exact value for each given terminal and operating environment should be agreed with the merchant acquirer in each instance.
| Description | Feature | 8 | 4 | 2 | 1 |
|---|---|---|---|---|---|
| First position | IC contact reader | X | |||
| Terminal capabilities | Magnetic stripe reader | X | |||
| Manual card entry | X | ||||
| Extended terminal capabilities. See note 1 | X | ||||
| Second position | Lines available | X | |||
| Number of display or print lines | X | ||||
| X | |||||
| X | |||||
| Third position | Down-line loading Referral tel. no | X | |||
| Response message capabilities | Hold capability | X | |||
| Down-line loading floor limits | X | ||||
| Response additional data supported | X | ||||
| Fourth position | Unattended device | X | |||
| Additional features | Pin Pad available | X | |||
| Terminal or operator able to capture card | X | ||||
| Cardholders device. e.g. PC, phone | X |
Note 1: If this bit is set then the data supplied in the 'Extended Terminal Capabilities and Attributes' auxiliary data message takes priority.