Retail API Fields

Field Name Length
Type
Description
0060 Unique Device ID 2-8
numeric
Identifies the source lane or terminal through which a transaction is processed, so that a compromised device or fraudulent transaction can be easily identified.
The last two numbers must be unique to each register within a location (01-99 as the base line for compatibility for all TPP’s). This field should be presented in all transaction types supported by a POS/PMS application.
Ex.: 0060,51563621
0400 Product Code 2-4
numeric
An international numeric code describing the type of purchase. A list of valid codes should be provided to the merchant by the acquiring bank or processor. Used in European countries.
0401 Invoice Number/ROC 1-10
numeric
Contains the invoice number or record of charge (ROC).
Ex.: 0401,123456
0406 Item 1 Text 40 max
alphanumeric
REQUIRED. Description of purchased item. This field is required along with API Field 0412.
Ex.: 0406,BRUSH
0407 Item 2 Text 40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 2 (API Field 0413).
Ex.: 0407,SOAP
0408 Item 3 Text 40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 3 (API Field 0414).
Ex.: 0408,SHAMPOO
0409 Item 4 Text 40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 4 (API Field 0415).
Ex.: 0409,TOOTHPASTE
0410 Item 5 Text  40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 5 (API Field 0416).
Ex.: 0410,TOOTHBRSH
0411 Retail Terms 4
numeric
Identifies special terms or payment options.
Ex.: 0411,1234
0412 Item Code/Details 1 4‐35
alphanumeric
Item code descibing type of product purchased.
SubField 1 - Item Code describing type of product purchased [max size 16, numeric]
SubField 2 - Item Quantity [max size 3, numeric]
SubField 3 - Item Amount [max size 13]
Format: NNNN;NNN;NNNNNNNNNN.NN
Examples:
0412,23;1;13.42 (This example includes all subfields, item code, quantity, amt)
0412,;2;2.35 (This example is quantity + amt only)
0412,453 (This example is item code only. This is an example of Legacy use).
0413 Item Code/Details 2 4‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 2 text.  Refer to description for field 0412.
0414 Item Code/Details 3 4‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 3 text. Refer to description for field 0412.
0415 Item Code/Details 4 4‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 4 text. Refer to description for field 0412.
0416 Item Code/Details 5 4‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 5 text. Refer to description for Field 0412.
0723 Recurring Payments Status 1
alphanumeric
Flag indicating status of recurring payment (Card on File transaction). Valid values are:
F - First Payment
S – Subsequent scheduled recurring payment (i.e., regular payment)
U – Unscheduled recurring payment/purchase
Ex.: 0723,F
0738 Recurring compliance data 1-50
alphanumeric
Contains compliance data that merchants should retain and then return unaltered in the next recurring/card on file transaction.
Ex.: 0738,12345
5020 Token Account Status 1
alphanumeric
Identifies the account range as regulated or non-regulated and is received from the Card Brand. It will contain one of the below values to indicate the status of the account range and should be included in capture if present in the authorization response. Valid values are:
R - Regulated
N - Non-Regulated
5021 Token Assurance Level 2
numeric
Defined by the token service provider, this Visa or MasterCard value indicates the assigned confidence level of the token-to-PAN/cardholder binding. It will be returned back to merchants in authorization response when it’s available from association.
5022 Token Requestor ID 11
numeric
Contains the value that uniquely identifies the pairing of token requestor with the token domain. This value is sent in capture to identify the requestor to the card brand. For payment token transactions, merchant should send in token requestor id when it’s available. It’s a required field for MasterCard card-on-file token transactions.
5023 Token Cryptogram 40
alphanumeric
EMV tag Contactless chip cryptogram is uniquely generated by the Token Requestor to validate authorized use of the Token.
5024 Last 4 Digits of Primary PAN 4
numeric
Last 4 digits of actual account number will be returned back in authorization response when it’s available from association, merchant can use it for receipt-printing purposes instead of using payment token number.
5025 Card Brand Token Status 1
numeric
Contains the status of the token. Valid Values:
0 = Non Token Transaction
1 = Active
2 = Suspended
3 = Deactivated
4 = Expired
5 = Unknown

Tabulated Data

Tabulated Data is an API field type that supports multiple values in a single input API field. It was developed to better address data that can be grouped together. This field allows API expansion to an area of the API (Retail, Direct Marketing, etc.) where available API fields are ptherwise limited. The data separator in a tabulated field is a semi-colon (;).

The tabulated data are described as follows:

  • Retail tabulated data fields: 0412, 0413, 0414, 0415, and 0416
  • SubField 1: Item code describing the type of product purchased [max size 16, type N]
  • SubField 2: Item quantity [max size 3, type N]
  • SubField 3: Item amount [max size 13, type C]
  • Format: NNNN;NNN;NNNNNNNNNN.NN

Overall total size = 4 + ; 16 + ; 3 + ; 10 + 2 = 35 total

In this example, API Field 0412 includes all subfields, item code, quantity and amount.

      0412,23;1;13.42

In this example, API Field 0412 is being used to pass only the Item Quantity and Amount and the Item Code field has been left blank.

0412,;2;2.35

In this example, API Field 0412 is being used as the item code only. It’s an example of Legacy use.

0412,453

AMEX Level III increased subfield 1 from 4 to 16 to accommodate SKUs as well as item codes.