Object Attributes

The following lists and defines various attributes used in JSON payloads.

Amounts

Amount values are a decimal format, based on the currency.

Note

• For currencies with two decimal places, such as USD, you must provide exactly two digits past the decimal, so 2.00 for two dollars and zero cents.

• For currencies with zero decimal places, only whole numbers are permitted.

US Dollar Amount Examples

Amount Formatting Examples

amountFormattingTable

Currency Amount	API Formatted Amount
$2.00	2.00
$2.50	2.50
$100.00	100.00
$100.50	100.50
$1,000.50	1000.50
$12,400.50	12400.50

Address Verfication Service (AVS)

Customer address information is required to achieve the best possible interchange qualifications and inhibit fraud. At the very least, the postal (zip) code should be provided.

Country

These are the ISO 2-letter country codes. Please see ISO 3166-1 alpha-2 for a reference on valid codes.

Currencies

These are the ISO 3-letter currency codes. Please see ISO 4217 for a reference on valid codes.

Customer System ID

We use KSUIDs in many parts of our system where others would use UUIDs, an explaination of KSUIDs can be found at https://github.com/segmentio/ksuid

Unique, ksuid.KSUID

Data Action

Data Action is the type of data maintenance requested.

Allowed values for Data Action:

dataActionTable

Value	Description
token/add	Request to Add the Token Data
token/stored-by-merchant	Card data is retrieved by a token credential previously stored at the merchant location

Data Action additional information

Data Action requests are embedded with another transaction request through a DataAction name, value JSON pair. This allows a Data Action request to be executed alongside another transaction request.

Data Value value - token/add for cards

This request generates a new Token ID for a specific merchant for a specific customer and specific customer card.

The Token ID is used like a card-on-file by the merchant with the card data for the Token ID stored securely at Paynetworx.

NOTE

• This type of request will add an embedded Data Action request for token data to the current transaction request.
• The Token ID is not allowed in the request message when this particular embedded Data Action request is used.

Requirements: token/add for cards

• Card-related Token is determined by Transaction Type
• PAN must be provided
• Card Expiration Month must be provided
• Card Expiration Year must be provided
• Token ID must NOT be present

Data Value value - token/add for accounts

This request generates a new Token ID for a specific merchant for a specific customer and specific account number and bank routing number. The Token ID is used like a account-on-file by the merchant with the account data for the Token ID stored securely at Paynetworx. This type of request will add an embedded Data Action request for token data to the current transaction request. The Token ID is not allowed in the request message when this particular embedded Data Action request is used.

Requirements: token/add for accounts

• Account-related Token is determined by Transaction Type
• Account Number must be provided
• Routing Number must be provided
• Token ID must NOT be present

Debit Card Transaction

See the Processing Specifiers section on this page, and refer to the DebitDirect field to indicate a debit card transaction.

NOTE

If absent, this is not a debit transaction.

Detail Order Data

The Order data under the detail object include Standard Data and Corporate Data.

detailOrderTable

Attribute	Data Type	Description	Required
Order	object	Order Data details related to the transaction (Standard Data and Corporate Data)	False
OrderID	string	Merchant may assign a unique identifier for this order OrderID is aKey/Value of the "Order" Object.	False
OrderDate	timestamp string (ISO8601 format)	Initiation date and time of order OrderDate is aKey/Value of the "Order" Object.	False
Invoice	string	Invoice number assigned to order Invoice is aKey/Value of the "Order" Object.	False
CorporateCustomer	boolean	True indicates corporate customer (required to be true for corporate customer processing) CorporateCustomer is aKey/Value of the "Order" Object.	False
CustomerPO	string	Purchase Order number for the customer order CustomerPO is aKey/Value of the "Order" Object.	False
CustomerANI	string	Telephony Automatic Number Identification to record origin of call CustomerANI is aKey/Value of the "Order" Object.	False
CustomerANICallType	string	Telephony data two-digit pair, ANI information identifier digits (ANI II) CustomerANICallType is aKey/Value of the "Order" Object.	False
CustomerIPAddress	string	Customer IP Address related to the initiation of the transaction order CustomerIPAddress is aKey/Value of the "Order" Object.	False
CustomerBrowserType	string	Customer Browser Type related to the initiation of the transaction order CustomerBrowserType is aKey/Value of the "Order" Object.	False
CustomerRegistered	boolean	Customer has a profile registered in the merchant system CustomerRegistered is aKey/Value of the "Order" Object.	False
CustomerProfileModified	timestamp string (ISO8601 format)	Customer profile modified in conjunction with this transaction CustomerProfileModified is aKey/Value of the "Order" Object.	False
CustomerCode	string	Reference identifier given by customer or consumer (Corporate data with an example being consumer ID or driver ID) CustomerCode is aKey/Value of the "Order" Object.	False
MerchantHostname	string	Merchant URL used in relation to transaction MerchantHostname is aKey/Value of the "Order" Object.	False
MerchantTaxID	string	Merchant Tax ID (Corporate data) MerchantTaxID is aKey/Value of the "Order" Object.	False
AlternateTaxID	string	Alternate Tax ID (Corporate data) AlternateTaxID is aKey/Value of the "Order" Object.	False
MerchantEmail	string	Merchant email address (Corporate data) MerchantEmail is aKey/Value of the "Order" Object.	False
MerchantReferenceNumber	string	Merchant reference number facilitating merchant communication with the corporation (Corporate data) MerchantReferenceNumber is aKey/Value of the "Order" Object.	False
NAICSCode	string	North American Industry Classification System (NAICS) codes for businesses (Corporate data) NAICSCode is aKey/Value of the "Order" Object.	False
AdditionalCardAcceptorInformation	string	Additional information about the merchant (Corporate data) AdditionalCardAcceptorInformation is aKey/Value of the "Order" Object.	False
AuthorizedContactPhone	string	Phone number of authorized person or entity for company purchases (Corporate data) AuthorizedContactPhone is aKey/Value of the "Order" Object.	False
AuthorizedContactName	string	Name of authorized person or entity for company purchases (Corporate data) AuthorizedContactName is aKey/Value of the "Order" Object.	False
InvoiceLevelDiscountTreatment	string	Overall order discount treatment indicator (Corporate data: no-discount, tax-calculation-post-discount, tax-calculation-pre-discount) InvoiceLevelDiscountTreatment is aKey/Value of the "Order" Object.	False
DiscountType	string	Type of discount applied DiscountType is aKey/Value of the "Order" Object.	False
AustinTetraNumber	string	A unique identifier for businesses (Corporate data) AustinTetraNumber is aKey/Value of the "Order" Object.	False
BusinessCertificationType	string	Certification type of the business (Corporate data: not-certified, sba-small-business, sba-small-disadvantaged-business, agency-recognized-certification, self-certified-small-business, sba-and-agency-small-business, sba-and-agency-small-disadvantaged-business, agency-self-certified-small-business, sba-certification-8a, self-certified-small-disadvantaged-business, sba-certification-hubzone, unknown) BusinessCertificationType is aKey/Value of the "Order" Object.	False
BusinessOwnerType	string	Business owner type description (Corporate data: no-application-classification, female-business-owner , physically-handicapped-female-business-owner , physically-handicapped-male-business-owner , unknown) BusinessOwnerType is aKey/Value of the "Order" Object.	False
BusinessRacialEthnicType	string	Business racial ethnic type (Corporate data: , african-american, asian-pacific-american, subcontinent-asian-american, hispanic-american, native-american-indian, native-hawaiian, native-alaskan, caucasian, other, unknown) BusinessRacialEthnicType is aKey/Value of the "Order" Object.	False
BusinessType	string	Business type (Corporate data: , corporation, unknown-business-type, sole-proprietorship, partnership, association, estate, trust , tax-exempt-orginization-501c , international-organization , limited-liability-company, government-agency) BusinessType is aKey/Value of the "Order" Object.	False
CardAcceptorVATNumber	string	Merchant value-added-tax number (Corporate data) CardAcceptorVATNumber is aKey/Value of the "Order" Object.	False
CorporationVATNumber	string	Corporation value-added-tax number (Corporate data) CorporationVATNumber is aKey/Value of the "Order" Object.	False
CustomerVATNumber	string	Customer value-added-tax number (Corporate data) CustomerVATNumber is aKey/Value of the "Order" Object.	False
UniqueInvoiceReferenceNumber	string	Reference number that is unique to this invoice (Corporate data) UniqueInvoiceReferenceNumber is aKey/Value of the "Order" Object.	False
UniqueVATInvoiceReferenceNumber	string	Reference number that is unique to this invoice for the value-added-tax number (Corporate data) UniqueVATInvoiceReferenceNumber is aKey/Value of the "Order" Object.	False

BusinessCertificationType - Allowed field values:

orderBusinessCertificationType

Value	Description
not-certified	Not Certified
sba-small-business	SBA small business
sba-small-disadvantaged-business	SBA small disadvantaged business
agency-recognized-certification	Agency recognized certification
self-certified-small-business	Self certified small business
sba-and-agency-small-business	SBA and agency small business
sba-and-agency-small-disadvantaged-business	SBA and agency small disadvantaged business
sba-certification-8a	SBA certification 8a
self-certified-small-disadvantaged-business	Self-certified small disadvantaged business
sba-certification-hubzone	SBA certification hubzone
unknown	Unknown

BusinessOwnerType - Allowed field values:

orderBusinessOwnerType

Value	Description
no-application-classification	no-application-classification
female-business-owner	female-business-owner
physically-handicapped-female-business-owner	physically-handicapped-female-business-owner
physically-handicapped-male-business-owner	physically-handicapped-male-business-owner
unknown	unknown

BusinessRacialEthnicType - Allowed field values:

orderBusinessRacialEthnicType

Value	Description
african-american	African American
asian-pacific-american	Asian Pacific American
subcontinent-asian-american	Subcontinent Asian American
hispanic-american	Hispanic American
native-american-indian	Native American Indian
native-hawaiian	Native Hawaiian
caucasian	Caucasian
other	Other
unknown	Unknown

BusinessType - Allowed field values:

orderBusinessType

Value	Description
corporation	Corporation
unknown-business-type	Unknown business type
sole-proprietorship	Sole proprietorship
partnership	Partnership
association	Association
estate	Etate
trust	Trust
tax-exempt-organization-501c	Tax-exempt organization 501c
international-organization	International organization
limited-liability-company	Limited Liability Company
government-agency	Government Agency

Detail Item Data

The object array of Item data under the detail object include Standard Data and Corporate Data. The Item object array describes a list of goods and services in a sale.

An Item entry may contain units that comprise that item. Specific fields reference Item for the main item, and other specific field reference Unit or PerUnit that comprise the item.

detailItemTable

Attribute	Data Type	Description	Required
Item	object array	Item Data detail is related to one item in a sale, and one Item may be comprised of Units if desired (See fields with names that reference Item and Unit/PerUnit fields)	False
ItemID	string	Merchant may assign a unique identifier for this item ItemID is aKey/Value of the "Item" Object.	False
ShipmentID	string	An optional reference to the related field Detail.Shipment[x].ShipmentID ShipmentID is aKey/Value of the "Item" Object.	False
PackageID	string	An optional reference to the related field Detail.Shipment[x].ShipmentID.Package[y].PackageID PackageID is aKey/Value of the "Item" Object.	False
Description	string	Item description Description is aKey/Value of the "Item" Object.	False
ItemOrderDate	string	Timestamp of order for item ItemOrderDate is aKey/Value of the "Item" Object.	False
ItemMeasurementDescription	string	Description of the item measurement that may optionally include one or more units ItemMeasurementDescription is aKey/Value of the "Item" Object.	False
ItemMeasurementCategory	string	Measurement category type of a single unit within the item (weight, size, quantity, service, pieces, parts, regularhours, overtimehours, expense) ItemMeasurementCategory is aKey/Value of the "Item" Object.	False
ItemPrice	decimal	Price of a single instance of this item ItemPrice is aKey/Value of the "Item" Object.	False
ItemQuantity	decimal	Quantity of item ItemQuantity is aKey/Value of the "Item" Object.	False
ItemAmount	decimal	ItemPrice multiplied by the ItemQuantity ItemAmount is aKey/Value of the "Item" Object.	False
NumberOfUnitsInItem	decimal	One item contains this many units NumberOfUnitsInItem is aKey/Value of the "Item" Object.	False
PerUnitMeasurementDescription	string	Description of a single unit measurement, an item is composed of units PerUnitMeasurementDescription is aKey/Value of the "Item" Object.	False
PerUnitMeasurementCategory	string	Measurement category type of a single unit, and item is composed of units (weight, size, quantity, service, pieces, parts, regularhours, overtimehours, expense) PerUnitMeasurementCategory is aKey/Value of the "Item" Object.	False
PerUnitPrice	decimal	Price of a single unit, an item is composed of units PerUnitPrice is aKey/Value of the "Item" Object.	False
GoodsSoldType	string	Goods sold type (giftcard, giftcard-reloadable, giftcard-not-reloadable) GoodsSoldType is aKey/Value of the "Item" Object.	False
CategoryCode	string	Category or Department code for the item CategoryCode is aKey/Value of the "Item" Object.	False
ProductCode	string	Product code for the item ProductCode is aKey/Value of the "Item" Object.	False
ProductItemNumber	string	Product number for the item ProductItemNumber is aKey/Value of the "Item" Object.	False
CommodityCode	string	Commodity code for the item CommodityCode is aKey/Value of the "Item" Object.	False
HealthcareEligible	boolean	Healthcare eligible is true when the item is elegile for healthcare purposes HealthcareEligible is aKey/Value of the "Item" Object.	False
ContractNumber	string	Contract number related to the item ContractNumber is aKey/Value of the "Item" Object.	False
ItemDiscountAmount	decimal	Discount amount for the item ItemDiscountAmount is aKey/Value of the "Item" Object.	False
ItemDiscountRate	string	Discount rate for the item ItemDiscountRate is aKey/Value of the "Item" Object.	False
DiscountPerLineItem	decimal	Amount of discount on this line item according to Item Discount Treatment DiscountPerLineItem is aKey/Value of the "Item" Object.	False
ItemDiscountTreatment	string	Overall order discount treatment indicator (Corporate data: no-discount, tax-calculation-post-discount, tax-calculation-pre-discount) ItemDiscountTreatment is aKey/Value of the "Item" Object.	False
ItemDiscountPerLine	decimal	Discount amount on this item ItemDiscountPerLine is aKey/Value of the "Item" Object.	False
TaxExempt	boolean	TaxExempt is aKey/Value of the "Item" Object.	False
TaxAmount	decimal	Tax amount on this item TaxAmount is aKey/Value of the "Item" Object.	False
TaxRate	decimal	Tax rate applied for this item TaxRate is aKey/Value of the "Item" Object.	False
VATTaxAmount	decimal	Value-added-tax amount for this item VATTaxAmount is aKey/Value of the "Item" Object.	False
VATTaxRate	decimal	Value-added-tax rate for this item VATTaxRate is aKey/Value of the "Item" Object.	False
VATTaxForFreightShippingAmount	decimal	Value-added-tax amount for freight shipping VATTaxForFreightShippingAmount is aKey/Value of the "Item" Object.	False
VATTaxFreightShippingRate	decimal	Value-added-tax rate for freight shipping VATTaxFreightShippingRate is aKey/Value of the "Item" Object.	False
AlternateTaxAmount	decimal	Alternate tax amount AlternateTaxAmount is aKey/Value of the "Item" Object.	False
ItemShippingAmount	decimal	Shipping amount for the item ItemShippingAmount is aKey/Value of the "Item" Object.	False
ItemIncentiveAmount	decimal	Incentive amount for the item ItemIncentiveAmount is aKey/Value of the "Item" Object.	False
Promotional	object array	Promotional is aKey/Value of the "Item" Object.	False
PromotionStartDate	timestamp string (ISO8601 format)	Start date for the promotional event PromotionStartDate is aKey/Value of the "Promotional" Object.	False
PromotionEndDate	timestamp string (ISO8601 format)	End date for the promotional event PromotionEndDate is aKey/Value of the "Promotional" Object.	False
PromotionalCode	string	Promotional code for the promotional event PromotionalCode is aKey/Value of the "Promotional" Object.	False
MedicalServicePriceAdjustment	string	Type of medical service price adjustment (price-adjustment, credit, rebill) MedicalServicePriceAdjustment is aKey/Value of the "Item" Object.	False
MedicalServiceProductNumberQualifier	string	Product number qualifier for medical service MedicalServiceProductNumberQualifier is aKey/Value of the "Item" Object.	False
MedicalServiceShiptoHealthIndustryNumber	string	Ship-to health industry number for medical service MedicalServiceShiptoHealthIndustryNumber is aKey/Value of the "Item" Object.	False

ItemMeasurementCategory - Allowed field values:

detailMeasurementCategory

Value	Description
weight	Weight
size	Size
quantity	Quantity
service	Service
pieces	Pieces
parts	Parts
regularhours	Regular Hours
overtimehours	Overtime Hours
expense	Expense

PerUnitMeasurementCategory - Allowed field values:

detailMeasurementCategory

Value	Description
weight	Weight
size	Size
quantity	Quantity
service	Service
pieces	Pieces
parts	Parts
regularhours	Regular Hours
overtimehours	Overtime Hours
expense	Expense

GoodsSoldType - Allowed field values:

orderGoodsSoldType

Value	Description
giftcard	Giftcard
giftcard-reloadable	Giftcard Reloadable
giftcard-not-reloadable	Giftcard Not Reloadable

MedicalServicePriceAdjustment - Allowed field values:

orderMedicalServicePriceAdjustment

Value	Description
price-adjustment	Price Adjustment
credit	Credit
rebill	Rebill

Detail Ship From Data

The Ship From data under the detail object contains the name, address, and contact information for the sender of the shipment.

detailShipFromTable

Attribute	Data Type	Description	Required
ShipFrom	object	Shipment sender data (Standard Data and Corporate Data)	False
Name	string	Shipment sender name (Full Name) Name is aKey/Value of the "ShipFrom" Object.	False
Line1	string	Shipment sender address line 1 Line1 is aKey/Value of the "ShipFrom" Object.	False
Line2	string	Shipment sender address line 2 Line2 is aKey/Value of the "ShipFrom" Object.	False
City	string	Shipment sender city City is aKey/Value of the "ShipFrom" Object.	False
State	string	Shipment sender state State is aKey/Value of the "ShipFrom" Object.	False
PostalCode	string	Shipment sender postal code (AKA Zip Code) PostalCode is aKey/Value of the "ShipFrom" Object.	False
Country	string	Shipment sender country Country is aKey/Value of the "ShipFrom" Object.	False
Phone	string	Shipment sender Phone Number Phone is aKey/Value of the "ShipFrom" Object.	False
Email	string	Shipment sender Email Email is aKey/Value of the "ShipFrom" Object.	False

Detail Ship To Data

The Ship To data under the detail object contains the name, address, and contact information for the receiver of the shipment.

detailShipToTable

Attribute	Data Type	Description	Required
ShipTo	object	Shipment receiver data (Standard Data and Corporate Data)	False
Name	string	Shipment receiver name (Full Name) Name is aKey/Value of the "ShipTo" Object.	False
Line1	string	Shipment receiver address line 1 Line1 is aKey/Value of the "ShipTo" Object.	False
Line2	string	Shipment receiver address line 2 Line2 is aKey/Value of the "ShipTo" Object.	False
City	string	Shipment receiver city City is aKey/Value of the "ShipTo" Object.	False
State	string	Shipment receiver state State is aKey/Value of the "ShipTo" Object.	False
PostalCode	string	Shipment receiver postal code (AKA Zip Code) PostalCode is aKey/Value of the "ShipTo" Object.	False
Country	string	Shipment receiver country Country is aKey/Value of the "ShipTo" Object.	False
Phone	string	Shipment receiver Phone Number Phone is aKey/Value of the "ShipTo" Object.	False
Email	string	Shipment receiver Email Email is aKey/Value of the "ShipTo" Object.	False

Detail Shipment Data

The Shipment data under the detail object array contains the details of the shipment(s) including shipper(s), package(s) and other details.

detailShipmentTable

Attribute	Data Type	Description	Required
Shipment	object array	One or more package shipment details for sending order items (Standard Data and Corporate Data)	False
ShipmentID	string	Merchant may assign a unique identifier for this entry of Shipment details ShipmentID is aKey/Value of the "Shipment" Object.	False
ShipperName	string	Shipment company name ShipperName is aKey/Value of the "Shipment" Object.	False
ShipperAddress	object	Shipment company address ShipperAddress is aKey/Value of the "Shipment" Object.	False
Name	string	Shipping Company name as related to address Name is aKey/Value of the "ShipperAddress" Object.	False
Line1	string	Shipping Company address line 1 Line1 is aKey/Value of the "ShipperAddress" Object.	False
Line2	string	Shipping Company address line 2 Line2 is aKey/Value of the "ShipperAddress" Object.	False
City	string	Shipping Company city City is aKey/Value of the "ShipperAddress" Object.	False
State	string	Shipping Company state State is aKey/Value of the "ShipperAddress" Object.	False
PostalCode	string	Shipping Company postal code (AKA Zip Code) PostalCode is aKey/Value of the "ShipperAddress" Object.	False
Country	string	Shipping Company country Country is aKey/Value of the "ShipperAddress" Object.	False
Phone	string	Shipping Company Phone Number Phone is aKey/Value of the "ShipperAddress" Object.	False
Email	string	Shipping Company Email Email is aKey/Value of the "ShipperAddress" Object.	False
ShippingMethod	string	Shipping method for this shipment and all packages under this shipment (sameday, overnight, priority, ground, electronicdelivery, ship-to-shore, freight) ShippingMethod is aKey/Value of the "Shipment" Object.	False
TrackingNumber	string	Shipment tracking number from shipment company TrackingNumber is aKey/Value of the "Shipment" Object.	False
ShipDate	timestamp string (ISO8601 format)	Timestamp that shipment was sent ShipDate is aKey/Value of the "Shipment" Object.	False
PickupDate	timestamp string (ISO8601 format)	Timestamp that shipment was picked up from sender by shipment company PickupDate is aKey/Value of the "Shipment" Object.	False
DeliveryDate	timestamp string (ISO8601 format)	Timestamp that shipment was delivered to receiver DeliveryDate is aKey/Value of the "Shipment" Object.	False
NumberOfPackages	integer	Shipment contains this number of packages NumberOfPackages is aKey/Value of the "Shipment" Object.	False
Package	string	Package detail data for one or more packages in this shipment entry Package is aKey/Value of the "Shipment" Object.	False
PackageID	string	Merchant may assign a unique identifier of Package details for one package PackageID is aKey/Value of the "Package" Object.	False
ItemID	string array	One or more item identifiers which may reference fields in Detail.Item[x].ItemID if desired ItemID is aKey/Value of the "Package" Object.	False
PackageWeight	decimal	Weight of this one package PackageWeight is aKey/Value of the "Package" Object.	False
PackageShippingAmount	decimal	Shipping amount for this one package PackageShippingAmount is aKey/Value of the "Package" Object.	False
AdditionalInformation	string	Additional shipment information AdditionalInformation is aKey/Value of the "Shipment" Object.	False

ShippingMethod - Allowed field values:

detailShippingMethod

Value	Description
sameday	Same day
overnight	Overnight
priority	Priority
ground	Ground
electronicdelivery	Electronic delivery
ship-to-shore	Ship-to-shore
freight	Freight

Dynamic Descriptor

Use of the dynamic descriptor is optional. A properly configured dynamic descriptor is helpful to the merchant. This helps the merchant's customers to identify their transactions with that merchant.

Note

The "dynamic descriptor" is configured by the merchant through the Attributes.TransactionDescriptor object.

The Attributes.TransactionDescriptor object is not required.

The Paynetworx system builds the Dynamic Descriptor from the Attributes.TransactionDescriptor.Prefix and Attributes.TransactionDescriptor.Detail.

Asterisks are not allowed in the Attributes.TransactionDescriptor field.

(The required asterisk for the dynamic descriptor is added automatically by the Paynetworx system).

Dynamic Descriptor Example

Dynamic Descriptor = Attributes.TransactionDescriptor.Prefix combined with Attributes.TransactionDescriptor.Detail

In the Dynamic Descriptior Example, the following is the first portion of the dynamic descriptor:

• Attributes.TransactionDescriptor.Prefix

This is the recognizable reference to the merchant's business name. 3 to 7 characters in length. Asterisk is not allowed.

In the Dynamic Descriptior Example, the following is the second portion of the dynamic descriptor

• Attributes.TransactionDescriptor.Detail

This the the detailed reference to the merchant's customer transaction. Zero to 14 characters in length. Asterisk is not allowed.

Entry Mode

This is the entry mode for the card data, valid values include:

entryModeTable

Value	Description
manual	Manually entered PAN (Including Point of Sale and ECommerce)
manual-fallback	Manually entered PAN (Due to failure to read via magstripe, chip, or contactless-chip)
magstripe	Magnetic Stripe read (Track 2 data)
magstripe-fallback	Magnetic Stripe read (Magnetic stripe read due to failure to read via chip, or contactless-chip)
chip	EMV chip card
contactless-chip	EMV contactless chip card
card-on-file	Card on file, usually ecommerce or recurring

ICC Data

Data field definitions associated with chip cards may be found at: https://emvlab.org/emvtags/all/

All data is hex encoded bytes, and must be submitted as valid hexadecimal data, no spaces are permitted, and full bytes are required. (That is, "0000" is permitted, but "000" will cause a parsing validation error.)

iccDataTable

Value	Data Type	Description
AmountAuthorized	string	Tag 9F02; (Authorized transaction amount)
AmountOther	string	Tag 9F03; (Secondary amount associated with the transaction, such as a cash back amount)
ApplicationCryptogram	string	Tag 9F26; (Cryptogram generated by the chip card)
ApplicationIdentifier	string	Tag 9F06; (Terminal AID)
ApplicationInterchangeProfile	string	Tag 82; (Indicates card support of application functions)
ApplicationTransactionCounter	string	Tag 9F36; (Application counter in the chip card)
ApplicationUsageControl	string	Tag 9F07; (Issuer indicates restrictions for the application)
CardholderVerificationMethod	string	Tag 9F34; (Cardholder Verification Method Results)
CardSequenceNumber	string	Tag 5F34; (Sequence number of the card)
CryptogramInformationData	string	Tag 9F27; (Type of cryptogram and related actions)
CustomerExclusiveData	string	Tag 9F7C; (Sequence number of the card)
DedicatedFileName	string	Tag 84; (Dedicated File Name of the application)
FormFactorIndicator	string	Tag 9F6E; (Type of payment card used)
InterfaceDeviceSerialNumber	string	Tag 9F1E; (Serial number for the interface device)
IssuerApplicationData	string	Tag 9F10; (Application data for issuer)
IssuerAuthenticationData	string	Tag 91; (Response Data provided from the issuer for online authentication)
IssuerScriptResults	string	Tag 9F5B; (Terminal result from processing issuer script)
IssuerScriptTemplate1	string	Tag 71; (Response Data sent to ICC from issuer)
IssuerScriptTemplate2	string	Tag 72; (Response Data sent to ICC from issuer)
TerminalApplicationVersionNumber	string	Tag 9F09; (Assigned version number for the application)
TerminalCapabilities	string	Tag 9F33; (Card data input and associated capabilities)
TerminalCountryCode	string	Tag 9F1A; (Based on ISO country code in which the terminal is located)
TerminalType	string	Tag 9F35; (Terminal attributes and capabilites)
TerminalVerificationResults	string	Tag 95; (Terminal function status)
TransactionCurrencyCode	string	Tag 5F2A; (Based on ISO currency code)
TransactionDate	string	Tag 9A; (Date of the transaction)
TransactionSequenceNumber	string	Tag 9F41; (Value from terminal transaction counter)
TransactionType	string	Tag 9C; (Transaction Type)
UnpredictableNumber	string	Tag 9F37; (Variable, uniqued value for cryptogram)

Merchant Data

This is a section where arbitrary (but valid) JSON can be inserted by the merchant. Data included here is linked to the transaction and may be used for reporting functionality.

NOTE

This data must not be used to store card data, bank account data, nor any personally identifiable information as defined under either GDPR or CCPA.

NOTE

Please limit the size of this data to no more than 1024 bytes total for the JSON.

NOTE

Values that appear to be valid SQL may result in your transaction being rejected at the firewall level.

Processing Specifiers

The Processing Specifiers under the Attributes object further describe details of the requested transaction.

NOTE

The Access Token Device Types section explains the point of interaction device type requirements for the InitiatedByPOS, InitiatedByECommerce, and InitiatedByVirtualTerminal settings.

attributesProcessingSpecifiersTable

Attribute	Data Type	Description	Required
ProcessingSpecifiers	object	Attributes Processing Specifiers to specify attributes for processing of the request	False
InitiatedByPOS	boolean	Point of interaction device type that initiates the request is from a POS terminal (Access token device type is a POS terminal) InitiatedByPOS is aKey/Value of the "ProcessingSpecifiers" Object.	False
InitiatedByECommerce	boolean	Point of interaction device type that initiates the request is from an ECommerce device (Access token device type is an ECommerce device) InitiatedByECommerce is aKey/Value of the "ProcessingSpecifiers" Object.	False
InitiatedByVirtualTerminal	boolean	Point of interaction device type that initiates the request is from a Virtual terminal (Access token device type is a POS Virtual Terminal application) InitiatedByVirtualTerminal is aKey/Value of the "ProcessingSpecifiers" Object.	False
DebitDirect	boolean	Indicates that this is a debit card request DebitDirect is aKey/Value of the "ProcessingSpecifiers" Object.	False
FaxOrder	boolean	Indicates that this an order received by facsimile machine FaxOrder is aKey/Value of the "ProcessingSpecifiers" Object.	False
MailOrder	boolean	Indicates that this an order received by mail MailOrder is aKey/Value of the "ProcessingSpecifiers" Object.	False
TelephoneOrder	boolean	Indicates that this an order received by telephone TelephoneOrder is aKey/Value of the "ProcessingSpecifiers" Object.	False
RecurringPayment	boolean	Indicates that this a recurring payment, a fixed frequency and fixed amount payments (This falls into the Recurring Payment category) RecurringPayment is aKey/Value of the "ProcessingSpecifiers" Object.	False
StandingPayment	boolean	Indicates that this a standing payment, a fixed frequency and variable amount payments (This falls into the Recurring Payment category) StandingPayment is aKey/Value of the "ProcessingSpecifiers" Object.	False
UnscheduledPayment	boolean	Indicates that this an unscheduled payment, for variable frequency payments (This falls into the Recurring Payment category) UnscheduledPayment is aKey/Value of the "ProcessingSpecifiers" Object.	False
CredentialStorage	boolean	(DataAction must be present when this is true) CredentialStorage is aKey/Value of the "ProcessingSpecifiers" Object.	False
FirstPayment	boolean	(The Recurring object is required when this is true) FirstPayment is aKey/Value of the "ProcessingSpecifiers" Object.	False

Reasons

The Reason data indicates the reason for the transaction. Valid values for Reason include:

reasonsTable

Value	Description
system-error	System error ex. Terminal disconnect
customer-cancellation	Customer chose to cancel the transaction

Recurring Data

The Recurring category consists of several types, and the types are Recurring Payment, Standing Payment, and Unscheduled Payment.

The Recurring category table below defines usage according to the recurring amount and the recurring frequency.

recurringPaymentDefinitionTable

Recurring Category Type	Description of usage
Recurring Payment	Usage: Fixed amount. Fixed frequency.
Standing Payment	Usage: Variable amount. Fixed frequency.
Unscheduled Payment	Usage: All variable frequency.

The below Recurring object is allowed when the Processing Specifiers under the Attributes object is a Recurring category. The Recurring category is RecurringPayment, StandingPayment, and UnscheduledPayment.

recurringTable

Attribute	Data Type	Description	Required
PaymentAmountType	string	Amount for the payment is described by this type (fixed-amount, variable-amount, variable-amount-with-maximum)	False
Frequency	string	Frequency for the payment is described by this type (weekly, fortnightly, monthly, quarterly, yearly, variable-frequency)	False
IssuerReferenceID	string	Reference number or ID from the card issuer related to this payment	False
ValidationIndicator	boolean	Indicates the recurring payment was pre-validated by the merchant	False
MerchantData	object	Merchant Defined Transaction Data (supports 1 or more Merchant Defined Keys)	False

PaymentAmountType - Allowed field values:

recurringPaymentAmountType

Value	Description
fixed-amount	Fixed amount
variable-amount	Variable amount
variable-amount-with-maximum	Variable amount with maximum allowed amount

Frequency - Allowed field values:

recurringFrequency

Value	Description
weekly	Weekly
fortnightly	Fortnightly
monthly	Monthly
quarterly	Quarterly
yearly	Yearly
variable-frequency	Variable frequency

States

These are the two letter state abbreviations, for the US a list can be found here: List of U.S. state and territory abbreviations

Token ID

Token ID is a unique value used as a payment method for a transaction request. The Token ID represents a card or account.

Token ID is provided in a transaction request when it is used as a payment method. Alternatively for transaction requests, the Token ID may be intentionally excluded if an embedded Data Action request for Token Add is specified with the transaction request.

Token IDs are generated only by Paynetworx. A new Token ID can be requested by a Token Add request through the Data Action field. A generated Token ID from Paynetworx is associated with a specific merchant for a specific customer and specific card. This allows the Token ID to be used as a payment method between the merchant and customer. The Token ID references the customer's card or account as an on-file record which is kept securely at Paynetworx for that merchant.

To get the value of the Token ID and the Token Name, look to the response message in the Token object.

Note

Token IDs are never provided in any type of request that adds a Token ID.

Track2 Data

Start and end sentinels are required, so ";4000300020001000=1225000000000?"

Note

• Start Sentinel:
  • ;
• Seperator:
  • =
• End Sentinel:
  • ?

Transaction Entry Data

The Transaction Entry data records entry data on the point of interaction (POI) side.

transactionEntryTable

Attribute	Data Type	Description	Required
Device	string	Device Submitting the transaction	False
DeviceVersion	string	Device Version	False
Application	string	POS Application Name	False
ApplicationVersion	string	POS Application Version	False
TimeStamp	timestamp string (ISO8601 format)	Local Time submitted by the device for the transaction in ISO8601 format	False

Timestamp

This is a ISO8601 formatted timestamp indicating the local time of the POS device, or for ecommerce, the local time for the merchant.