Back

Transaction Request Fields

This chapter describes the fields that can be used in a transaction request to the EPX payment gateway.

ACCOUNT_NBR

The ACCOUNT_NBR field contains the account number to be acted upon during the transaction.

• Variable Type: Numeric
• Max Length: 19
• REGEX: ^([0-9,*]){4,19}$

Example:

<ACCOUNT_NBR>4111111111111111</ACCOUNT_NBR>

ACI

The Authorization Characteristics Indicator (ACI) field is used to identify specific characteristics of the transaction for the Networks. The table below describes the possible values.

• Variable Type: Alphanumeric
• Max Length: 2

Example:

<ACI>Q</ACI>

ACI_EXT

The Authorization Characteristics Indicator Extension (ACI_EXT) field is used to identify additional characteristics of the transaction for the Networks. The table below describes the possible values. The below table describes the possible values.

ACI Extension Values for card types

If the four-part processing key requires a CVV2 value to process an authorization, sending the ACI_EXT field will override this requirement, as recurring or installment transactions do not require a CVV2 value. This field should always be submitted when performing a recurring or installment authorization or sale transactions.

This field may also be used for recurring ACH transactions with a Standard Entry Class value of WEB. Sending the field with a value of “RA” will allow the transaction to clear as recurring rather than as the default value, S (Single).

• Variable Type: Alphanumeric
• Max Length: 2

Example:

    <ACI_EXT>RB</ACI_EXT>

ACTION_CODE

The ACTION_CODE field contains the action code U that indicates that the account should be updated by Visa or MasterCard. This action should be taken against an ORIG_AUTH_GUID during an Automatic Account Updater Service transaction.

• Variable Type: Alpha
• Max Length: 1

Example:

<ACTION_CODE>U</ACTION_CODE>

ADDENDA_1 through 10

The ADDENDA_X fields, where X is a number between 1 and 10, are used in the ACH environment to attach an addendum to a transaction.

• Variable Type: Alphanumeric
• Max Length: 80

Example:

<ADDENDA_6>Customer Checking Account</ADDENDA_6>

ADDRESS

The ADDRESS field contains the street address associated with the account number. This field, along with ZIP_CODE, is part of the credit card address verification as the numeric value contained in this field will be validated against the value recorded at the issuing bank for the account when doing a credit card authorization. The response for this verification is found in the AUTH_AVS field. EPX supports all AVS formats supported by the card networks.

• Variable Type: Alphanumeric
• Max Length: 30
• REGEX: ^([a-zA-Z0-9\/\.\-_,#'&+\s\xc0-\xff]){0,30}$

Example:

<ADDRESS>123 My Street</ADDRESS>

AMOUNT

The AMOUNT field contains the positive dollar amount of funds to be moved during the transaction. The AMOUNT should be the amount of goods and service including any reference field amount; for example, TIP_AMT, TAX_AMT.

AMOUNT should not include cashback amounts.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

Example:

<AMOUNT>12.34</AMOUNT>

AUTH_SOURCE

The AUTH_SOURCE field should be sent with a value of OTHER when attempting to capture a transaction using an AUTH_CODE and an ORIG_AUTH_GUID that does not reference a Pre-Authorization in the EPX System. In a situation where a voice authorization is needed, this field allows a BRIC such as one from a BRIC Storage transaction to be used to reference the account information, while also using the voice authorization/approval code during the transaction.

Example:

<AUTH_SOURCE>OTHER</AUTH_SOURCE>

BARCODE_DATA

The BARCODE_DATA field contains the data produced from a barcode scan. This field must be sent with CARD_ENT_METH value of “A” and supports non-encrypted PAN or Visa TLV formats. The value for the BARCODE_DATA tag must be formatted as described in the following table.

• REGEX: ^([0-9A-Fa-f]){4,1024}$

Consider an example where the barcode scan of a PAN (with no encryption) returns 3123456789012345678. The data that follows shows how this result needs to be submitted to EPX.

<BARCODE_DATA>0003123456789012345678</BARCODE_DATA>
<CARD_ENT_METH>A</CARD_ENT_METH>

BATCH_ID

The BATCH_ID field contains a unique number created by the operator to identify a batch of transactions. This field works in conjunction with the TRAN_NBR field. The same BATCH_ID/TRAN_NBR combination cannot be used more than once under a single merchant number (MERCH_NBR). Commonly, this field contains the date in a number format, which groups the transactions into a daily batch.

• Variable Type: Numeric
• Max Length: 10
• REGEX: ^([0-9]){0,10}$

Example:

<BATCH_ID>180412</BATCH_ID>

BIRTH_DATE

The BIRTH_DATE field is an optional field that contains the birth date of the customer associated with the account number for the transaction.

• Variable Type: Numeric
• Format: MMDDYYYY
• Max Length: 8

Example:

<BIRTH_DATE>11261980</BIRTH_DATE>

CARD_ENT_METH

The CARD_ENT_METH field is used to indicate how the card number was entered for the transaction.

• Variable Type: Alpha
• Max Length: 1

Example:

<CARD_ENT_METH>X</CARD_ENT_METH>

Card Entry Method Codes

• A—Used when scanning a Bar Code
• B—OCR
• D—Used when sending Swiped Track 2 data
• E—Key Entered Card Number via Ecommerce
• G—Chip (EMV contact)
• H—Used when sending Swiped Track 1 data
• M—Used when sending MICR data
• Q—Proximity / Contactless MSD non-EMV (Track 2 data is required)
• R—Proximity / Contactless EMV-based (Track 2 data is required)
• T—Token from third party
• X—Key Entered MICR or Card Number (Typed in using keyboard or keypad)
• Z—BRIC/GUID Token Transaction
• 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader (Legacy)
• 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader (Legacy)
• 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader (Legacy)
• 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader (Legacy)
• 4—Mobile Commerce (mCommerce) / Digital Wallet (Discover Only)
• 5—PAN Auto Entry via Server (issuer, acquirer, or third party vendor system)
• 6—PAN Entry via COF (Merchant's Card On File)

CARD_ID

The CARD_ID field contains the code that represents the industry used for the transaction requested.

• Variable Type: Alphanumeric
• Max Length: 1

Example:

<CARD_ID>P</CARD_ID>

Card Identification Codes

Following are the possible Card Identification Codes:

• 0—CARDHOLDER PRESENT
• 1—CARDHOLDER NOT PRESENT
• M—CARDHOLDER PRESENT, Card not readable
• T—Discover "PayButton"
• P—PIN (online PIN)

If no value is supplied, the industry default applies.

CASH_BK_AMT

The amount specified in the CASH_BK_AMT field is added to the transaction amount indicated in the AMOUNT field when the request is sent to the networks for approval. For example, for a purchase transaction with an AMOUNT containing $20.00 and a cash-back amount (CASH_BK_AMT) containing $10.00, the amount (AUTH_AMOUNT_REQUESTED) is sent to the networks as a total of $30.00.

Partial approvals do not apply for the cash back amount. EPX includes the approved total amount in response tag AUTH_AMOUNT.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

Example:

<CASH_BK_AMT>10.00</CASH_BK_AMT>

CHECK_NBR

The CHECK_NBR field contains the check number associated to with an ACH transaction.

• Variable Type: Numeric
• Max Length: 8

Example:

<CHECK_NBR>1402</CHECK_NBR>

CHECK_TYPE

The CHECK_TYPE field contains the type of check being read during a TeleCheck transaction.

• Variable Type: Alpha
• Max Length: 1

Example:

<CHECK_TYPE>M</CHECK_TYPE>

Possible values:

• P—Consumer/Business
• C—Company
• X—Travelers
• S—Payroll
• M—Cash
• T—Two Party
• G—Government

CHIP_CONDITION_CODE

The CHIP_CONDITION_CODE tag is used to indicate the reason for the EMV fallback transaction. EMV fallback transactions are presented as a standard swipe transaction and the CHIP_CONDITION_CODE must be present and set to the appropriate value.

CHIP_CONDITION_CODE Values

• Variable Type: Numeric
• Max Length: 1

Example:

<CHIP_CONDITION_CODE>2</CHIP_CONDITION_CODE>

CITY

The CITY field contains the city associated with the account number for the transaction.

• Variable Type: Alphanumeric
• Max Length: 25
• REGEX: ^([a-zA-Z0-9\/\.\-_,#'&+\s\xc0-\xff]){0,25}$

Example:

<CITY>Phoenix</CITY>

COF_PERIOD

The COF_PERIOD tag is used to indicate a base transaction for Card on File and Merchant Initiated Transactions. The COF_PERIOD tag designates the BRIC / GUID as COF / MIT and the number of months to keep the BRIC / GUID available for usage. This tag is only used during the base transaction request or customer initiated transaction. All subsequent COF / MIT transactions should not contain this tag.

• If COF_PERIOD is not supplied with “CCx0” AVS Only, “CCx1” Sale, and “CCx2” Auth Only transactions, EPX will by default mark as COF with the standard 13 month life usage window.
• If COF_PERIOD is supplied with a value of 1 – 24, EPX will mark as COF with the numeric value indicating the amount of months the BRIC / GUID will be available for usage. If the EPX BRIC / GUID is used within the initially specified window of time, EPX will reset the usage window to the original requested number of months; essentially restoring it with a new life cycle.
• If COF_PERIOD is supplied with a value of “0”, EPX will NOT mark as COF. The BRIC can only be used to perform “CCx4” Capture Only, “CCx7” Reversal, “CCx9” Return, and “CCxX” Void transactions. The BRIC cannot be used to process any new “CCx0” AVS Only, “CCx1” Sale, and “CCx2” Auth Only transactions. The cardholder must provide their account information to process new transactions with the ACCOUNT_NBR, EXP_DATE, and CVV2.

The table below indicates the possible values and usage for COF_PERIOD.

COF_PERIOD Values

• Variable Type: Numeric
• Max Length: 2
• REGEX: ^([1-9]|1[0-9]|2[0-4]){0,1}$

Example:

<COF_PERIOD>24</COF_PERIOD>

CONVENIENCE_FEE

The CONVENIENCE_FEE field is a reference field that contains the convenience fee amount which is included in the amount of the transaction. This field does not get added to the AMOUNT field during the transaction, it is only referencing the convenience fee amount already included. The client application is responsible for adding the convenience fee into the total AMOUNT prior to initiating the transaction request.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

<CONVENIENCE_FEE>3.50</CONVENIENCE_FEE>

COUNTRY_CODE

The COUNTRY_CODE field contains the standard ISO code used to identify the country of card origination. For example, USA (United States of America) has a code of 840 which is also the numeric code for US (United States).

• Variable Type: Numeric
• Max Length: 3

<COUNTRY_CODE>840</COUNTRY_CODE>

CURRENCY_CODE

The CURRENCY_CODE field contains the standard ISO code used to identify the type of currency in the AMOUNT field. For example, USD (US Dollar) has a code of 840 which is also the numeric code for US (United States).

• Variable Type: Numeric
• Max Length: 3

<CURRENCY_CODE>840</CURRENCY_CODE>

CVV2

The CVV2 field contains the credit card’s CVV2 number.

• Variable Type: Numeric
• Max Length: 4
• REGEX: ^([0-9]){3,4}$

<CVV2>123</CVV2>

DEVICE_ID

The DEVICE_ID field is used to provide the unique ID of the physical device that’s initiating the transaction.

• Variable Type: alphanumeric
• Max Length: 40
• REGEX: ^([a-zA-Z0-9-.]){0,40}$

Example:

<DEVICE_ID>ajh-kfmkq-nrnjsp</DEVICE_ID>

DL_NBR

The DL_NBR field contains the customer's driver's license number during a TeleCheck transaction.

• Variable Type: Alphanumeric
• Max Length: 22

<DL_NBR>A123456789</DL_NBR>

DL_STATE

The DL_STATE field contains the state that the customer's driver's license was issued in during a TeleCheck transaction.

• Variable Type: Alpha
• Max Length: 2

<DL_STATE>DE</DL_STATE>

E2EE

The E2EE tag (End to End Encryption) identifies which type of encryption is in use. Use this tag in correspondence with the CARD_ENT_METH tag.

Valid values are as follows:

• Variable Type: Numeric
• Max Length: 1

Example:

<E2EE>2</E2EE>

EMV_DATA

The EMV_Data tag contains the request data from the EMV kernel as a variable list of tags and their data in TLV format.

• Variable Type: Alphanumeric
• Max Length: 510

Example:

<EMV_DATA>9F34030200009F260828BF9D3AFCC8DD529F2701809F1008010103A0000000009F37044ABAA8C49F3602008595054040040000820258009F3303E0F8C89F1A0208409F3501229F1E0832323135333731309F03060000000000009A031504309C01009F02060000000010005F2A0208409F090200025F3401009F4104000000039F0607A0000000041010</EMV_DATA>

Allowed / Maximum EMV Fields

The maximum length for the EMV_DATA tag is 510 bytes

Allowed EMV fields

ENHANCED_TLV

The ENHANCED_TLV field contains enhanced / level III data in TLV format. Reference the EPX Data Dictionary – Enhanced / Level II & III Data for additional information.

• Variable Type: Alphanumeric
• Format: TLV
• Max Length: 2000

Example:

<ENHANCED_TLV>0010006VISA_G00200510010009CUSTCODE7005000523.000090003840011000603142200300900010007COMCODE0020009ITEM,DESC0030008PRODCODE004000130050004EACH0060006300.000100006600.00</ENHANCED_TLV>

EXP_DATE

The EXP_DATE field contains the credit card’s expiration date.

• Variable Type: Numeric
• Format: YYMM
• Max Length: 4
• REGEX: ^(([0-9][0-9](0[1-9]|1[0-2]))|0000)$

Example:

<EXP_DATE>2104</EXP_DATE>

FIRST_NAME

The FIRST_NAME field contains the first name the customer associated with the account number for the transaction.

• Variable Type: Alpha
• Max Length: 25

Example:

<FIRST_NAME>John</FIRST_NAME>

FOLIO_NBR

The FOLIO_NBR field is an optional field that contains the folio number of the customer associated with the account number for the transaction.

• Variable Type: Alphanumeric
• Max Length: 25

Example:

<FOLIO_NBR>1582</FOLIO_NBR>

IDENT_NBR

The IDENT_NBR field is an optional field that the merchant can use to store an identification number related to the transaction.

• Variable Type: Alphanumeric
• Max Length: 15

Example:

<IDENT_NBR>765412</IDENT_NBR>

INDUSTRY_TYPE

The use of the INDUSTRY_TYPE tag allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique TERMINAL_NBR(s) configured specifically for each industry type.

If the INDUSTRY_TYPE tag is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically TRAN_TYPE.

The INDUSTRY_TYPE value has the following effects:

• For the credit card transaction class, the INDUSTRY_TYPE value will override the industry code value found in all credit card class "CCIx" TRAN_TYPE(s), where “I” is the industry type.
• For all other transaction classes (CK, DB, EB, SS, SM, and SV), which do not have the industry code embedded, the INDUSTRY_TYPE value will determine the proper POS characteristics for each transaction.

The table below indicates the TRAN_TYPE values with the corresponding INDUSTRY_TYPE value mapping and descriptions.

• Variable Type: Alpha
• Max Length: 1
• REGEX: ^([EMP]){1}$

Example:

<INDUSTRY_TYPE>P</INDUSTRY_TYPE>

INVOICE_NBR

The INVOICE_NBR field is an optional field that will contain the invoice number of the customer associated with the account number for the transaction.

• Variable Type: Alphanumeric
• Max Length: 25

Example:

<INVOICE_NBR>12354</INVOICE_NBR>

ISSUE_NBR

The ISSUE_NBR field contains the credit card’s issue number. This is commonly found on Maestro, Switch, or Solo credit cards that have been re-issued and may be required when processing such card types.

• Variable Type: Numeric
• Max Length: 3

Example:

<ISSUE_NBR>2</ISSUE_NBR>

LAST_NAME

The LAST_NAME field contains the last name the customer associated with the account number for the transaction.

• Variable Type: Alpha
• Max Length: 25

Example:

<LAST_NAME>Doe</LAST_NAME>

MAC

The MAC field contains either the Merchant Authorization Code (EPX Hosted Pay Page) or the TIC value generated by EPX. The MAC can also be enabled in the Merchant Profile as a required field for API processing. The MAC would then need to be sent with transactions in addition to the 4-part key.

• Variable Type: Alphanumeric
• Max Length: N/A

Key Value Pair Example:

MAC=00000000000000000000000000000000

MICR_DATA

The MICR_DATA field contains the MICR data in raw TOAD MICR format from the check being scanned at the register.

• Variable Type: Alphanumeric

Example:

<MICR_DATA>T999999991T 1234567890O 1234</MICR_DATA>

MICR_TYPE

The MICR_TYPE field contains the type of MICR being sent when processing a TeleCheck transaction.

• Variable Type: Numeric
• Max Length: 2

Example:

<MICR_TYPE>09</MICR_TYPE>

Possible Values:

• 09—Raw MICR
• 18—Routing and Account Number Only
• 19—Manual MICR

MPG ID (Merchant Payment Gateway Identifier)

The MasterCard MPG ID (Merchant Payment Gateway Identifier) is used to identify the gateway or processing solution that is initiating card not present transactions. The MC MPG ID value can be dynamically included with transaction requests by utilizing the TLV_SETS API tag with data set "NETWORK" & TLV tag "008" (MC MPG ID).  The table below contains specific details including a sample of the TLV string.

Note: If the MPG ID is not included with MasterCard transaction requests, the EPX platform will use a default value. This is intended specifically for card not present transactions. The gateway or processing solution will need to register directly with MasterCard to obtain a unique value indicator.

MC MPG ID – TLV_SETS “NETWORK”

• Variable Type: Numeric
• Max Length: 11
  Example: <TLV_SETS>0026000007NETWORK0080077654321</TLV_SETS>

MPOS_TYPE

The mPOS Type field is used to indicate the type of reader used by the mPOS device. This field is required for all card brands for transactions that are initiated from a true mPOS device. An mPOS device is not a terminal, rather a mobile device that is running a payment app and possibly using an external reader of some type. The table below describes the possible values.

mPOS values

• Variable Type: AlphaNumeric
• Max Length: 3
• REGEX: ^([0-3]){1}$

Example:

<MPOS_TYPE>0</MPOS_TYPE>

MPOS_TYPE

The mPOS Type field is used to indicate the type of reader used by the mPOS device. This field is required for all card brands for transactions that are initiated from a true mPOS device. An mPOS device is not a terminal, rather a mobile device that is running a payment app and possibly using an external reader of some type. The table below describes the possible values.

mPOS values

• Variable Type: AlphaNumeric
• Max Length: 3
• REGEX: ^([0-3]){1}$

Example:

<MPOS_TYPE>0</MPOS_TYPE>

ORDER_NBR

The ORDER_NBR field is an optional field that will contain the order number of the customer associated with the account number for the transaction.

• Variable Type: Alphanumeric
• Max Length: 25

Example:

<ORDER_NBR>65421</ORDER_NBR>

ORIG_AUTH_AMOUNT

The ORIG_AUTH_AMOUNT tag contains the original authorization amount that was returned in the AUTH_AMOUNT response tag from the original base Card on File CCx0 AVS, CCx1 Sale, and CCx2 Auth Only transaction requests. EPX will include this value in the COF / MIT authorization request to the Networks.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13
• REGEX: ^(([0-9]){1,12}?(\.[0-9]{0,4})|([0-9]){0,12}?(\.[0-9]{1,4}))$

Example:

<ORIG_AUTH_AMOUNT>77.00</ORIG_AUTH_AMOUNT>

ORIG_AUTH_GUID

The ORIG_AUTH_GUID field contains the BRIC/GUID (Globally Unique Identifier) of the original transaction being referenced in the current transaction. This field is used in transactions such as a capture of an existing authorization or the void of an existing unsettled sale. This field is also used when doing a BRIC/GUID-based token transaction such as a new Authorization or Sale.

• Variable Type: Alphanumeric
• Max Length: 20

Example:

<ORIG_AUTH_GUID>0V7017HDJXK00PNZKBE</ORIG_AUTH_GUID>

ORIG_AUTH_TRAN_IDENT

The ORIG_AUTH_TRAN_IDENT tag contains the NTID (Network Transaction ID) value that was returned in the AUTH_TRAN_IDENT response tag from the original base Card on File CCx0 AVS, CCx1 Sale, and CCx2 Auth Only transaction requests. EPX will include this value in the COF / MIT authorization request to the Networks.

• Variable Type: Alphanumeric
• Max Length: 20
• REGEX: ^([A-Z0-9]){0,20}$

Example:

<ORIG_AUTH_TRAN_IDENT>210817175754976</ORIG_AUTH_TRAN_IDENT>

ORIG_BATCH_ID

The ORIG_BATCH_ID field contains the BATCH_ID from the original Purchase transaction. This field is currently required in all Food Stamp Return (EB01) request messages. However, based on Underwriting / Risk rules, in some circumstances a merchant account may require this tag to be present in all Return/Refund request messages (beyond EBT transactions). Additionally, one or more card networks might mandate the use of this tag in the future.

• Variable Type: Numeric
• Max Length: 10
• REGEX: ^([0-9]){1,10}$

Example:

<ORIG_BATCH_ID>123</ORIG_BATCH_ID>

ORIG_TRAN_NBR

The ORIG_TRAN_NBR field contains the TRAN_NBR from the original Purchase transaction. This field is currently required to be included in all Food Stamp Return (EB01) request messages. However, based on Underwriting / Risk rules, in some circumstances a merchant account may require this tag to be present in all Return/Refund request messages (beyond EBT transactions). Additionally, one or more card networks might mandate the use of this tag in the future.

• Variable Type: Numeric
• Max Length: 10
• REGEX: ^([0-9]){1,10}$

Example:

<ORIG_TRAN_NBR>17</ORIG_TRAN_NBR>

Partial Authorizations

The Partial Authorization capability is enabled and disabled through a merchant account profile setting. It is imperative that the merchant profile be set up completely for partial approvals/authorizations. The merchant must specify this capability during the initial merchant set up process.

For a Partial Authorization, the transaction response contains an AUTH_RESP value of 10 with the partial amount approved reflected in the AUTH_AMOUNT tag.

To generate the response in the UAP Test environment, use the test trigger cards with the amount of 1.59.

Partial Reversals

The Partial Reversal is to allow the merchant to make a correction on an open Sale CCx1 or a non-captured CCx2 Authorization Only prior to settlement. The amount specified in the AMOUNT request tag will be the actual amount that will remain authorized, i.e. the amount the corrected Authorization should be.

For example, the original transaction Authorization AMOUNT was for 150.00 and the corrected/final transaction amount is 120.00. The partial CCx7 reversal request would be sent with an AMOUNT of 120.00.

PAYLOAD_1

The PAYLOAD_1 field is used for generic payload information for specific transactions.

• Variable Type: Alphanumeric
• Format: Base64

Example:

<PAYLOAD_1>IkZvcmQsIiBoZSBzYWlkLCAieW91J3JlIHR1cm5pbaW4uIFN0b3AgaXQuIg</PAYLOAD_1>

PAYMENT_INITIATION_CHANNEL

The MasterCard Payment Initiation Channel provides information about the device type used to identify mobile-initiated, MSD Contactless, and EMV Contactless-based transactions. Contactless-enabled applications are required to transmit the device type indicator value for MasterCard transactions in the Sale or Authorization request POST messages.

This field will indicate the type of device used at the terminal. In the scope of EMV transactions it must be populated using the device type field value from tag 9F6E.

This is required for MasterCard Contactless transactions containing the below Card Entry Methods:

• Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed)
• R—Proximity / Contactless EMV-based (Track 2 data is required)
• Variable Type: Numeric
• Fixed Length: 2
• REGEX: ^([0-9]){1,2}$

Example:

<PAYMENT_INITIATION_CHANNEL>21</PAYMENT_INITIATION_CHANNEL>

Payment Initiation Channel Indicators

• 00—Card
• 01—Mobile Network Operator (MNO) controlled removable secure element (SIM or UICC) personalized for use with a mobile phone or smartphone
• 02—Key Fob
• 03—Watch using a contactless chip or a fixed (non-removable) secure element not controlled by the MNO
• 04—Mobile Tag
• 05—Wristband
• 06—Mobile Phone Case or Sleeve
• 07—Mobile phone or smartphone with a fixed (non-removable) secure element controlled by the MNO, for example, code division multiple access (CDMA)
• 08—Removable secure element not controlled by the MNO, for example, memory card personalized for used with a mobile phone or smartphone
• 09—Mobile Phone or smartphone with a fixed (non-removable) secure element not controlled by the MNO
• 10—MNO controlled removable secure element (SIM or UICC) personalized for use with a tablet or ebook
• 11—Tablet or e-book with a fixed (non-removable) secure element controlled by the MNO
• 12—Removable secure element not controlled by the MNO, for example, memory card personalized for use with a tablet or e-book
• 13—Tablet or e-book with fixed (non-removable) secure element not controlled by the MNO
• 14—Mobile phone or smartphone with a payment application running in a host processor
• 15—Tablet or e-book with a payment application running in a host processor
• 16—Mobile phone or smartphone with a payment application running in the Trusted Execution Environment (TEE) of a host processor
• 17—Tablet or e-book with a payment application running in the TEE of a host processor
• 18—Watch with a payment application running in the TEE of a host processor
• 19—Watch with a payment application running in a host processor

• 20—Card
• 21—Phone: Mobile phone
• 22—Tablet/e-reader: Tablet computer or e-reader
• 23—Watch/Wristband: Watch or wristband, including a fitness band, smart strap, disposable band, watch add-on, and security/ID band
• 24—Sticker
• 25—PC: PC or laptop
• 26—Device Peripheral: Mobile phone case or sleeve
• 27—Tag: Key fob or mobile tag
• 28—Jewelry: Ring, bracelet, necklace, and cuff links
• 29—Fashion Accessory: Handbag, bag charm, and glasses
• 30—Garment Dress
• 31—Domestic Appliance: Refrigerator, washing machine
• 32—Vehicle: Vehicle, including vehicle attached devices
• 33—Media/Gaming Device: Media or gaming device, including a set top box, media player, and television

PHONE_CELL

The PHONE_CELL field is an optional field that contains the cell phone number of the customer associated with the account number for the transaction.

• Variable Type: Numeric
• Max Length: 10

Example:

<PHONE_CELL>3025551234</PHONE_CELL>

PHONE_HM

The PHONE_HM field is an optional field that contains the home phone number of the customer associated with the account number for the transaction.

• Variable Type: Numeric
• Max Length: 10

Example:

<PHONE_HM>3025551234</PHONE_HM>

PHONE_WK

The PHONE_WK field is an optional field that contains the work phone number of the customer associated with the account number for the transaction.

• Variable Type: Numeric
• Max Length: 10

Example:

<PHONE_WK>3025551234</PHONE_WK>

PIN_BLK

The data provided within the PIN_BLK field should be the 16-character hexadecimal encrypted pin block (EPD) followed by the DUKPT key serial number KSN. Depending on the specific PIN entry device (PED) this data may need to be reformatted.

Example:

EPB = 1B9C1845EB993A7A KSN = FFFF9876543210E00001
PIN_BLK = 1B9C1845EB993A7AFFFF9876543210E00001

READER_STATUS

The READER_STATUS field contains the status of the MICR Reader when processing a TeleCheck transaction.

• Variable Type: Alphanumeric
• Max Length: 3

Example:

<READER_STATUS>15</READER_STATUS>

Possible Values:

• 15—Valid read by MICR Reader
• 15I—Valid read by MICR Reader
• 3—Mag ink present but failed read
• 5—No Mag ink present
• 9—Manual only – No read attempts

REASON_CODE

The REASON_CODE field is used to indicate the reason for the reversal of an EMV-based transaction approval.

REASON_CODE Values

• Variable Type: Numeric
• Max Length: 1

Example:

<REASON_CODE>1</REASON_CODE>

RECV_NAME

The RECV_NAME field contains the customer's full name associated with the account number for an ACH transaction.

• Variable Type: Alpha
• Max Length: 22

Example:

<RECV_NAME>John Doe</RECV_NAME>

REFERENCE_NBR

The REFERENCE_NBR field is a required field for PIN-less Debit transactions that contain the consumer’s account information, such as electrical, telephone, loan, or policy number for the bill that is being paid during the transaction.

• Variable Type: Alphanumeric
• Max Length: 25

Example:

<REFERENCE_NBR>12345678</REFERENCE_NBR>

RENTAL_NBR

The RENTAL_NBR field is an optional field that contains the rental number of the customer associated with the account number for the transaction.

• Variable Type: Alphanumeric
• Max Length: 25

Example:

<RENTAL_NBR>4512</RENTAL_NBR>

ROUTING_NBR

The ROUTING_NBR field contains the Bank’s routing number associated with the account number for an ACH transaction.

• Variable Type: Numeric
• Max Length: 9

Example:

<ROUTING_NBR>031100092</ROUTING_NBR>

SERVER_OPR

The SERVER_OPR field is an optional field that contains the user name of the person running the application that is submitting the transaction.

• Variable Type: Alpha
• Max Length: 25

Example:

<SERVER_OPR>JDoe</SERVER_OPR>

SIGNATURE

The SIGNATURE field is an electronic representation of the signature, most often binary code, which is Base64 encoded so it can be transmitted over the Internet. Refer to the Signature Capture Transaction Specifications document for information on how and when to use the SIGNATURE field.

• Variable Type: Alphanumeric
• Max Length: 8k

Example:

<SIGNATURE>[Base64 encoded data]</SIGNATURE>

SIGNATURE_FORMAT

The SIGNATURE_FORMAT field is used to represent the actual device that captured the transaction, since each device may have its own proprietary format for the signature data. EPX is currently coded for the following formats: OPOS (Open Point of Sale) is an attempt to standardize message formats, interfaces, etc. for different hardware vendors, so that one API can be used among multiple devices; FPE (Forms Processing Engine) is proprietary to Hypercom Inc.

• Variable Type: Numeric (0 = OPOS Format, 1 = FPE Format, 2 = Ingenico, 3 = MagTek IPAD)
• Max Length: 3

Example:

<SIGNATURE_FORMAT>0</SIGNATURE_FORMAT>

SOFT_DESCRIPTOR and SOFT_DESCRIPTOR_2

The SOFT_DESCRIPTOR fields contain replacement descriptor information that will be used when the field is sent in with a transaction, rather than using the default descriptor set up in the merchant's profile. This is commonly used when a merchant is using the same four-part key for a number of DBAs. In order for you to use this field, your profile must be set up in production.

Refer to the Soft Descriptors User’s Manual for more information on the use of these fields. Contact the EPX Integration Team if this manual was not part of your integration package.

• Variable Type: Alpha
• Max Length: 40

Example:

<SOFT_DESCRIPTOR>Jac D’s Construction</SOFT_DESCRIPTOR>

SPECIAL_1

The SPECIAL_1 field can contain different values based on the transaction type being sent. When used with a Citi Private Label Auth or Sale transaction, this field should contain the credit plan number. When used in a Debit Batch Hold Release transaction, this field should contain the batch close sequence number that will be stored with each debit transaction and returned in the debit reconciliation file.

• Variable Type: Numeric

Example:

<SPECIAL_1>123456</SPECIAL_1>

STATE

The STATE field contains the two-character representation of the state associated with the account number for the transaction. This field is not a required field.

• Variable Type: Alphanumeric
• Max Length: 3
• REGEX: ^([a-zA-Z0-9\/\.\-_,#'&+\s]){0,3}$

Example:

<STATE>AZ</STATE>

STD_ENTRY_CLASS

The STD_ENTRY_CLASS field is used to indicate the standard entry class (SEC) code for an ACH transaction. If this field and code is not included with the ACH transaction request, the SEC code that is set within the merchant profile will be used by default.

• Variable Type: Alpha
• Max Length: 3

Example:

<STD_ENTRY_CLASS>PPD</STD_ENTRY_CLASS>

Standard Entry Class (SEC) Codes

SEC Codes

START_DATE

The START_DATE field contains the credit card’s issue date. This is commonly found on Maestro, Switch, or Solo credit cards and may be required when processing such card types.

• Variable Type: Alpha
• Format: YYMM
• Max Length: 4

<START_DATE>1610</START_DATE>

TAVV

The TAVV field contains the cryptogram returned by the Token Provider and can contain up to 81 characters. This is very similar to the CAVV value and how 3DS and MC SecureCode function.

When sending a MasterCard request, the Cryptogram data string is required in Base64 format.

When sending a Visa request, if the string length is 28, the data will be considered to be in Base64 format; if the string length is 40 it will be considered to be in HEX format; if its length is not equal to 28 or 40 it will not be included in the authorization request.

The optional XID can be in BASE64 or HEX (40) representation. If present, place a “|” (vertical bar) after the TAVV and then append the XID value.

• Variable Type: Alphanumeric
• Max Length: 81

Example (HEX):

<TAVV>0000010732799312345678901279930000000000</TAVV>

Example (Base64):

<TAVV>AAABAWFlmQAAAABjRWWZEEFgFz+=</TAVV>

TAVV_ECI

The TAVV_ECI field contains the ECI response returned by the Token Provider.

• Variable Type: Numeric
• Max Length: 2

Example:

<TAVV_ECI>5</TAVV_ECI>

TAX_AMT

The TAX_AMT field is a reference field that contains the tax amount which is included in the amount of the transaction. This field does not get added to the Amount field during the transaction, it is only referencing the tax amount already included.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

Example:

<TAX_AMT>1.35</TAX_AMT>

TAX_EXEMPT

The TAX_EXEMPT field is a reference field that contains an indication as to whether the transaction is tax exempt. This field assists in qualifying a transaction for Level II processing using the following rule. If a transaction is tax-exempt, then there is no need to send a tax amount, and if it is not then the tax amount should be supplied in the TAX_EXEMPT field.

• Variable Type: Alpha
• Max Length: 1

<TAX_EXEMPT>Y</TAX_EXEMPT>

TAX_EXEMPT Values

• Y—Sending a tag with a value of Y indicates that the transaction is tax exempt and tax amount does not need to be provided for Level II qualification.
• N—Sending a tag with a value of N indicates that the transaction is not tax exempt and tax amount needs to be provided for Level II qualification.

TIP_AMT

The TIP_AMT field is a reference field that contains the tip amount which is included in the amount of the transaction. This field does not get added to the Amount field during the transaction, it is only referencing the tip amount already included.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

Example:

<TIP_AMT>1.35</TIP_AMT>

TRACK_DATA

The TRACK_DATA field contains the track data from the credit or debit card. This field works with the CARD_ENT_METH field and may be in clear text or encrypted based on the card reader used during the transaction. When sending track data, track 1 is to be used when processing a credit card transaction, and track 2 is to be used if track 1 is unavailable or when processing a debit or EBT transaction. Refer to sections MagneSafe or MagneSafe v2.0 for additional information regarding the required format of the encrypted TRACK_DATA value.

• Variable Type: Alphanumeric
• Max Length: 256

Example:

<TRACK_DATA>B4111111111111111^CARD/TEST^10121010000012345678</TRACK_ DATA>

TRAN_FEE

The TRAN_FEE is used to indicate the surcharge fee amount applied to a specific transaction. The amount specified in the TRAN_FEE field is added to the transaction amount indicated in the AMOUNT field when the request is sent to the networks for approval. For example, a purchase transaction with an “AMOUNT” containing $20.00 and a transaction surcharge fee amount “TRAN_FEE” containing $2.50, the amount (AUTH_AMOUNT_REQUESTED) is sent to the networks as a total of $22.50. EPX includes the approved total amount in response tag AUTH_AMOUNT.

• Variable Type: Numeric (Decimal Point Required)
• Format: N.NN
• Max Length: 13

Example:

<TRAN_FEE>2.50</TRAN_FEE>

TRAN_NBR

The TRAN_NBR field contains a unique number created by the operator to identify a transaction within a batch. This field works in conjunction with the BATCH_ID field. The same BATCH_ID/TRAN_NBR combination cannot be used more than once under a single merchant number (MERCH_NBR). Commonly, this field contains an invoice number, or is just incremented throughout the day.

• Variable Type: Numeric
• Max Length: 10
• REGEX: ^([0-9]){0,10}$

Example:

<TRAN_NBR>28</TRAN_NBR>

TRAN_TYPE

The TRAN_TYPE field contains the TRAN_TYPE code specific to the type of transaction which is to be performed on the account number during the request. Below are lists defining the valid Transaction Type field values. (For details about specific transaction types, refer to the EPX transaction specification document for the selected industry.)

• Variable Type: Alphanumeric
• Max Length: 4

Example:

<TRAN_TYPE>CCE1</TRAN_TYPE>

Ecommerce Transaction Types

• CCE0—Ecommerce Account Verification transaction
• CCE1—Ecommerce Purchase Authorization & Capture transaction
• CCE2—Ecommerce Purchase Authorization Only transaction
• CCE4—Ecommerce Purchase Capture Only transaction
• CCE7—Ecommerce Purchase Authorization Reversal
• CCE8—Ecommerce BRIC Storage transaction
• CCE9—Ecommerce Return Capture transaction
• CCEA—Ecommerce Return Authorization & Capture transaction
• CCEC—Ecommerce Visa Debt Repayment Authorization and Capture
• CCEG—Ecommerce Return Authorization & Capture Hold Release
• CCEM—Ecommerce Payment Authorization & Capture transaction
• CCEN—Ecommerce Edit Authorization and Capture transaction
• CCEX—Ecommerce Void transaction
• CCEZ—Ecommerce Close Batch transaction

Retail Transaction Types

• CCR0—Retail Account Verification transaction
• CCR1—Retail Purchase Authorization & Capture transaction
• CCR2—Retail Purchase Authorization Only transaction
• CCR4—Retail Purchase Capture Only transaction
• CCR7—Retail Purchase Authorization Reversal
• CCR8—Retail BRIC Storage or Updates transaction
• CCR9—Retail Return Capture transaction
• CCRA—Retail Return Authorization & Capture transaction
• CCRG—Retail Return Authorization & Capture Hold Release
• CCRN—Retail Edit Authorization and Capture transaction
• CCRX—Retail Void transaction
• CCRY—Open to Buy/Balance Inquiry transaction. Citi Private Label only
• CCRZ—Retail Close Batch transaction

MOTO Transaction Types

• CCM0—MOTO Account Verification transaction
• CCM1—MOTO Purchase Authorization & Capture transaction
• CCM2—MOTO Purchase Authorization Only transaction
• CCM4—MOTO Purchase Capture Only transaction
• CCM7—MOTO Purchase Authorization Reversal
• CCM8—MOTO BRIC Storage or Update Transactions
• CCM9—MOTO Return Capture transaction
• CCMA—MOTO Return Authorization & Capture transaction
• CCMC—MOTO Visa Debt Repayment Authorization and Capture
• CCMG—MOTO Return Authorization & Capture Hold Release
• CCMN—MOTO Edit Authorization and Capture transaction
• CCMX—MOTO Void transaction
• CCMZ—MOTO Close Batch transaction

Debit Transaction Types

• DB00—DEBIT Purchase (Default) transaction
• DB01—DEBIT Return (Default) transaction
• DB0P—DEBIT PIN-less Purchase (Default) transaction
• DB0S—DEBIT PIN-less Return (Default) transaction
• DB0V—DEBIT Void and/or Reversal
• DB0Z—DEBIT Hold Release

EBT Transaction Types

• EB00—EBT Food Stamp Purchase / Voucher transaction
• EB01—EBT Food Stamp Return transaction
• EB02—EBT Food Stamp Bal Inq. transaction
• EB05—EBT Cash Benefits Purchase (Cash Back optional) transaction
• EB07—EBT Cash Benefits Balance Inq. transaction
• EB0V—EBT Reversal/Void/Cancel transaction

ACH Transaction Types

• CKC0—Checking Pre-note Debit transaction
• CKC1—Checking Pre-note Credit transaction
• CKC2—Checking Account Debit transaction
• CKC3—Checking Account Credit transaction
• CKC8—Checking BRIC Storage transaction
• CKCX—Checking Account Debit Void
• CKS0—Savings Pre-note Debit transaction
• CKS1—Savings Pre-note Credit transaction
• CKS2—Savings Account Debit transaction
• CKS3—Savings Account Credit transaction
• CKS8—Savings BRIC Storage transaction
• CKSX —Savings Account Debit Void

TeleCheck Transaction Types

• CKCE— Check Follow Up Transaction
• CKCF—Check Pre-Auth Transaction
• CKCG—Check Verify/Guarantee Transaction

Banking Transaction Types

• CCBJ—BANKING Cash Authorization & Capture transaction
• CCBK—BANKING Cash Authorization Only transaction

• CCBL—BANKING Cash Capture Only transaction
• CCBN—BANKING Edit Authorization and Capture transaction

Special Transaction Types

• SS01—Sending a signature capture
• SS02—Batch Totals
• SS03—Account Query
• SS0E—Enhanced TLV Edit / Add

Visa Money Transfer Transaction Types

• SM0G—VMT Account Funding Transaction (AFT)
• CCEW—VMT Watch List Screening Transaction (WLS)
• SM0H—VMT Original Credit Transaction (OCT)

MasterCard Money Transfer Transaction Types

• SM0G—SMS Funding Transaction
• SM0K—SMS Payment Transaction

Citi Private Label Transaction Types

• CCxH—Citi Card Payment Adjustment Capture and Hold transaction
• CCxI—Citi Card Payment Adjustment Capture and Hold Release transaction
• CCxT—Citi Card Payment Capture and Hold transaction
• CCxU—Citi Card Payment Capture and Hold Release transaction
• SS07—Citi Account Lookup Transaction
• SS08—Citi New Account Request / Apply for Credit Transaction

USER_DATA_1 through 10

The USER_DATA_X fields are optional fields that the merchant can use to store additional information about the transaction where X equals a number between 1 and 10.

• Variable Type: Alphanumeric
• Max Length: 80

Example:

<USER_DATA_3>XL Shirt</USER_DATA_3>

VERBOSE_RESPONSE

The VERBOSE_RESPONSE field determines if the verbose transaction response will be enabled. When enabled, the field contains a Y and all request and response elements are returned.

• Variable Type: Alpha
• Max Length: 1

Example:

<VERBOSE_RESPONSE>Y</VERBOSE_RESPONSE>

ZIP_CODE

The ZIP_CODE field contains the Zip code associated with the account number for the transaction. This field is not required.

This field, along with ADDRESS, is part of the credit card address verification as the value contained in this field will be validated against the value recorded at the issuing bank for the account when doing a credit card authorization. The response for this verification is found in the AUTH_AVS field. EPX supports all AVS formats supported by the card networks.

• Variable Type: Alphanumeric
• Max Length: 10
• REGEX: ^([A-Za-z0-9\-\s]){0,10}$

Examples:

<ZIP_CODE>198041258</ZIP_CODE>

<ZIP_CODE>T6V 1X7</ZIP_CODE>

Top of Page