Retail API Fields

0060 (Unique Device ID)

  • Description: 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
  • Length: 2-8
  • Data Type: Numeric

0400 (Product Code)

  • Decription: 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.
  • Length: 2-4
  • Data Type: Numeric

0401 (Invoice Number/ROC)

  • Decription: Contains the invoice number or record of charge (ROC). Ex.: 0401,123456
  • Length: 1-10
  • Data Type: Numeric

0406 (Item 1 Text)

  • Decription: REQUIRED. Description of purchased item. This field is required along with API Field 0412. Ex.: 0406,BRUSH
  • Length: 40 max
  • Data Type: Alphanumeric

0407 (Item 2 Text)

  • Decription:Description of purchased item. Required if there is an Item Code 2 (API Field 0413). Ex.: 0407,SOAP
  • Length: 40 max
  • Data Type: Alphanumeric

0408 (Item 3 Text)

  • Decription: Description of purchased item. Required if there is an Item Code 3 (API Field 0414). Ex.: 0408,SHAMPOO
  • Length: 40 max
  • Data Type: Alphanumeric

0409 (Item 4 Text)

  • Decription: Description of purchased item. Required if there is an Item Code 4 (API Field 0415). Ex.: 0409,TOOTHPASTE
  • Length: 40 max
  • Data Type: Alphanaumeric

0410 (Item 5 Text)

  • Decription: Description of purchased item. Required if there is an Item Code 5 (API Field 0416). Ex.: 0410,TOOTHBRSH
  • Length: 40 max
  • Data Type: Alphanumeric

0411 (Retail Terms)

  • Decription: Identifies special terms or payment options.
    Ex.: 0411,1234
  • Length: 4
  • Data Type: Numeric

0412 (Item Code/Details 1)

  • Decription: 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).
  • Length: 4-35
  • Data Type: Alphanumeric

0413 (Item Code/Details 2)

  • Decription: Item Code describing type of product purchased. Required if there is an Item 2 text.  Refer to description for field 0412.
  • Length: 4-35
  • Data Type: Alphanumeric

0414 (Item Code/Details 3)

  • Field Name:
  • Decription: Item Code describing type of product purchased. Required if there is an Item 3 text. Refer to description for field 0412.
  • Length: 4-35
  • Data Type: Alphanumeric

0415 (Item Code/Details 4)

  • Length: 4-35
  • Data Type: Alphanumeric

0416 (Item Code/Details 5)

  • Field Name:
  • Decription: Item Code describing type of product purchased. Required if there is an Item 5 text. Refer to description for Field 0412.
  • Length: 4-35
  • Data Type: Alphanumeric

0723 (Recurring Payments Status)

  • Decription: Flag indicating status of recurring payment (Card on File transaction).
  • Valid values:
    • F - First Payment
    • S – Subsequent scheduled recurring payment (i.e., regular payment)
    • U – Unscheduled recurring payment/purchase - Ex.: 0723,F
  • Length: 1
  • Data Type: Alphanumeric

0738 (Recurring compliance data)

  • Decription: Contains compliance data that merchants should retain and then return unaltered in the next recurring/card on file transaction. - Ex.: 0738,12345
  • Length: 1-50
  • Data Type: Alphanumeric

5020 (Token Account Status)

  • Decription: 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:
    • R - Regulated
    • N - Non-Regulated
  • Length: 1
  • Data Type: Alphanumeric

5021 (Token Assurance Level)

  • Field Name:
  • Decription: 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.
  • Length: 2
  • Data Type: Numeric

5022 (Token Requestor ID)

  • Decription: 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.
  • Length: 11
  • Data Type: Numeric

5023 (Token Cryptogram)

  • Field Name:
  • Decription: EMV tag Contactless chip cryptogram is uniquely generated by the Token Requestor to validate authorized use of the Token.
  • Length: 40
  • Data Type: Alphanumeric

5024 (Token Cryptogram)

  • Decription: 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.
  • Length: 4
  • Data Type: Numeric

5025 (Card Brand Token Status)

  • Field Name:
  • Decription: Contains the status of the token.
  • Valid Values:
    • 0 = Non Token Transaction
    • 1 = Active
    • 2 = Suspended
    • 3 = Deactivated
    • 4 = Expired
    • 5 = Unknown.
  • Length: 1
  • Data Type: Numeric

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.