Native Percents transaction format

Use content=percents-txn-stream for the recommended issuer transaction format. Upload UTF-8 CSV (fileType=csv, the default) or a JSON array (fileType=json). Both formats use the same row fields.

Row fields

Field	Required	Contract
`id`	Yes	Non-empty issuer transaction identifier; unique within the file.
`authDate`	Yes	Reference date: ISO `YYYY-MM-DD` or ISO datetime with a timezone.
`settlementDate`	No	Other transaction date: ISO `YYYY-MM-DD` or ISO datetime with a timezone; may be `null`.
`amount`	Yes	Integer USD cents from `-999999999` through `999999999`, inclusive; `475` represents USD 4.75.
`omniMerchantId`	Yes	Omni merchant UUID returned by the merchant catalog.
`cardBin`	Yes	String of exactly 6 or 8 digits; retain leading zeros.
`cardLast4`	Yes	String of exactly 4 digits; retain leading zeros.
`billingZip`	No	Billing postal code, or `null`.
`countryCode`	No	Uppercase two-letter country code (for example `US`), or `null`.
`mcc`	No	Four-digit merchant category code as a string; retain leading zeros. May be `null` or blank in CSV.
`segment`	No	`new`, `loyal`, `lapsed`, or `null`.
`authCode`	Yes	Authorization code.
`locationString`	Yes	Transaction location/descriptor string.
`cardType`	Yes	Lowercase `visa`, `mastercard`, `discover`, or `amex`.
`authMethod`	Yes	`swipe`, `chip`, `contactless`, `online`, `keyed_in`, or `other`.
`currency`	Yes	`USD`; other currencies are currently unsupported.
`cardId`	Yes	Issuer card identifier.
`cardholderId`	Yes	Issuer cardholder identifier.

Use the referenced merchant's segment definitions when supplying segment. Do not infer a merchant UUID from its name. Optional fields may be omitted or null in JSON and blank in CSV. Required fields must contain values.

TypeScript reference

export type UUID = `${string}-${string}-${string}-${string}-${string}`;

export type PercentsTxnUploadRow = {
  id: string;
  authDate: string;
  settlementDate?: string | null;
  amount: number;
  omniMerchantId: UUID;
  cardBin: string;
  cardLast4: string;
  billingZip?: string | null;
  countryCode?: string | null;
  mcc?: string | null;
  segment?: 'new' | 'loyal' | 'lapsed' | null;
  authCode: string;
  locationString: string;
  cardType: 'visa' | 'mastercard' | 'discover' | 'amex';
  authMethod:
    | 'swipe'
    | 'chip'
    | 'contactless'
    | 'online'
    | 'keyed_in'
    | 'other';
  currency: 'USD';
  cardId: string;
  cardholderId: string;
};

JSON files contain an array of these rows. Dates are ISO strings, and amount is an integer in USD cents. The field constraints above still apply; TypeScript does not validate values at runtime.

JSON example

[
  {
    "id": "issuer-transaction-001",
    "authDate": "2026-10-01T10:00:00Z",
    "settlementDate": null,
    "amount": 475,
    "omniMerchantId": "0df83025-5c37-4bb2-a258-f06bc34fd495",
    "cardBin": "012345",
    "cardLast4": "0042",
    "billingZip": "94607",
    "countryCode": "US",
    "mcc": "0742",
    "segment": "loyal",
    "authCode": "ABC123",
    "locationString": "Example Coffee Oakland CA",
    "cardType": "visa",
    "authMethod": "chip",
    "currency": "USD",
    "cardId": "issuer-card-001",
    "cardholderId": "issuer-cardholder-001"
  }
]

CSV example

The first row contains field names. Quote values containing commas, quotes, or line breaks according to CSV escaping rules.

id,authDate,settlementDate,amount,omniMerchantId,cardBin,cardLast4,billingZip,countryCode,mcc,segment,authCode,locationString,cardType,authMethod,currency,cardId,cardholderId
issuer-transaction-001,2026-10-01T10:00:00Z,,475,0df83025-5c37-4bb2-a258-f06bc34fd495,012345,0042,94607,US,0742,loyal,ABC123,Example Coffee Oakland CA,visa,chip,USD,issuer-card-001,issuer-cardholder-001

Whole-file validation

Malformed fields, undeclared JSON properties or CSV headers, unknown merchant IDs, and duplicate transaction IDs within a file fail validation for the entire file. No rows from a failed file are ingested. Correct the source and reserve a new filename before resubmitting. The processing result and file status expose validation and ingestion outcomes; they do not determine individual transaction approval, rewards, or invoices.