{"templateId":"markdown","versions":[{"version":"1.0","label":"1.0","link":"/omni-api/1.0/overview/file-uploads/native","default":false,"active":false,"folderId":"6bec560c"},{"version":"1.1","label":"1.1","link":"/omni-api/1.1/overview/file-uploads/native","default":false,"active":false,"folderId":"6bec560c"},{"version":"1.2","label":"1.2","link":"/omni-api/overview/file-uploads/native","default":true,"active":true,"folderId":"6bec560c"}],"sharedDataIds":{"sidebar":"sidebar-omni-api/@1.0/overview/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Native Percents transaction format"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"native-percents-transaction-format","__idx":0},"children":["Native Percents transaction format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content=percents-txn-stream"]}," for the recommended issuer transaction format. Upload UTF-8 CSV (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileType=csv"]},", the default) or a JSON array (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileType=json"]},"). Both formats use the same row fields."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"row-fields","__idx":1},"children":["Row fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Contract"},"children":["Contract"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Non-empty issuer transaction identifier; unique within the file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reference date: ISO ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," or ISO datetime with a timezone."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlementDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Other transaction date: ISO ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," or ISO datetime with a timezone; may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer USD cents from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-999999999"]}," through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["999999999"]},", inclusive; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["475"]}," represents USD 4.75."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["omniMerchantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Omni merchant UUID returned by the merchant catalog."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardBin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String of exactly 6 or 8 digits; retain leading zeros."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardLast4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String of exactly 4 digits; retain leading zeros."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billingZip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Billing postal code, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uppercase two-letter country code (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US"]},"), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Four-digit merchant category code as a string; retain leading zeros. May be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," or blank in CSV."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["new"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loyal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lapsed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locationString"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction location/descriptor string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lowercase ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["visa"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mastercard"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discover"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amex"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["swipe"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chip"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactless"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["online"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyed_in"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["other"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"; other currencies are currently unsupported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer card identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer cardholder identifier."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the referenced merchant's segment definitions when supplying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segment"]},". Do not infer a merchant UUID from its name. Optional fields may be omitted or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," in JSON and blank in CSV. Required fields must contain values."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typescript-reference","__idx":2},"children":["TypeScript reference"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"export type UUID = `${string}-${string}-${string}-${string}-${string}`;\n\nexport type PercentsTxnUploadRow = {\n  id: string;\n  authDate: string;\n  settlementDate?: string | null;\n  amount: number;\n  omniMerchantId: UUID;\n  cardBin: string;\n  cardLast4: string;\n  billingZip?: string | null;\n  countryCode?: string | null;\n  mcc?: string | null;\n  segment?: 'new' | 'loyal' | 'lapsed' | null;\n  authCode: string;\n  locationString: string;\n  cardType: 'visa' | 'mastercard' | 'discover' | 'amex';\n  authMethod:\n    | 'swipe'\n    | 'chip'\n    | 'contactless'\n    | 'online'\n    | 'keyed_in'\n    | 'other';\n  currency: 'USD';\n  cardId: string;\n  cardholderId: string;\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JSON files contain an array of these rows. Dates are ISO strings, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is an integer in USD cents. The field constraints above still apply; TypeScript does not validate values at runtime."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"json-example","__idx":3},"children":["JSON example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"id\": \"issuer-transaction-001\",\n    \"authDate\": \"2026-10-01T10:00:00Z\",\n    \"settlementDate\": null,\n    \"amount\": 475,\n    \"omniMerchantId\": \"0df83025-5c37-4bb2-a258-f06bc34fd495\",\n    \"cardBin\": \"012345\",\n    \"cardLast4\": \"0042\",\n    \"billingZip\": \"94607\",\n    \"countryCode\": \"US\",\n    \"mcc\": \"0742\",\n    \"segment\": \"loyal\",\n    \"authCode\": \"ABC123\",\n    \"locationString\": \"Example Coffee Oakland CA\",\n    \"cardType\": \"visa\",\n    \"authMethod\": \"chip\",\n    \"currency\": \"USD\",\n    \"cardId\": \"issuer-card-001\",\n    \"cardholderId\": \"issuer-cardholder-001\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"csv-example","__idx":4},"children":["CSV example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The first row contains field names. Quote values containing commas, quotes, or line breaks according to CSV escaping rules."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csv","header":{"controls":{"copy":{}}},"source":"id,authDate,settlementDate,amount,omniMerchantId,cardBin,cardLast4,billingZip,countryCode,mcc,segment,authCode,locationString,cardType,authMethod,currency,cardId,cardholderId\nissuer-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\n","lang":"csv"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whole-file-validation","__idx":5},"children":["Whole-file validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/omni-api/overview/webhooks/processing-results"},"children":["processing result"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/omni-api/overview/file-uploads/status"},"children":["file status"]}," expose validation and ingestion outcomes; they do not determine individual transaction approval, rewards, or invoices."]}]},"headings":[{"value":"Native Percents transaction format","id":"native-percents-transaction-format","depth":1},{"value":"Row fields","id":"row-fields","depth":2},{"value":"TypeScript reference","id":"typescript-reference","depth":2},{"value":"JSON example","id":"json-example","depth":2},{"value":"CSV example","id":"csv-example","depth":2},{"value":"Whole-file validation","id":"whole-file-validation","depth":2}],"frontmatter":{"seo":{"title":"Native Percents transaction format"}},"lastModified":"2026-10-02T20:53:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/omni-api/overview/file-uploads/native","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}