Retail API Fields

FieldNameLength
Type
Description
0060Unique Device ID2-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
0400Product Code2-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.
0401Invoice Number/ROC1-10
numeric
Contains the invoice number or record of charge (ROC).
Ex.: 0401,123456
0406Item 1 Text40 max
alphanumeric
REQUIRED. Description of purchased item. This field is required along with API Field 0412.
Ex.: 0406,BRUSH
0407Item 2 Text40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 2 (API Field 0413).
Ex.: 0407,SOAP
0408Item 3 Text40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 3 (API Field 0414).
Ex.: 0408,SHAMPOO
0409Item 4 Text40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 4 (API Field 0415).
Ex.: 0409,TOOTHPASTE
0410Item 5 Text 40 max
alphanumeric
Description of purchased item. Required if there is an Item Code 5 (API Field 0416).
Ex.: 0410,TOOTHBRSH
0411Retail Terms4
numeric
Identifies special terms or payment options.
Ex.: 0411,1234
0412Item Code/Details 14‐35
alphanumeric
Item code describing 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).
0413Item Code/Details 24‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 2 text.  Refer to description for field 0412.
0414Item Code/Details 34‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 3 text. Refer to description for field 0412.
0415Item Code/Details 44‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 4 text. Refer to description for field 0412.
0416Item Code/Details 54‐35
alphanumeric
Item Code describing type of product purchased. Required if there is an Item 5 text. Refer to description for Field 0412.
0723Recurring Payments Status1
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
0738Recurring compliance data1-50
alphanumeric
Contains compliance data that merchants should retain and then return unaltered in the next recurring/card on file transaction.
Ex.: 0738,12345
5020Token Account Status1
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
5021Token Assurance Level2
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.
5022Token Requestor ID11
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.
5023Token Cryptogram40
alphanumeric
EMV tag Contactless chip cryptogram is uniquely generated by the Token Requestor to validate authorized use of the Token.
5024Last 4 Digits of Primary PAN4
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.
5025Card Brand Token Status1
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 otherwise 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.